3dInSync¶
Usage: 3dInSync [options]¶
NOTE: For most intersubject correlation analyses, use 3dISC. Its
linear mixed-effects framework (with crossed random effects for subject
pairs) is the established way to model ISC with covariates, groups, and
repeated conditions, and it should be your first choice.
3dInSync is still useful for several reasons, which is why it can also
write ready-to-run 3dISC commands (see the pair-map options below):
* It starts from time series, so you do not need to compute and assemble
the subject-pair correlation maps that 3dISC requires as input.
* It offers nonparametric inference that 3dISC does not: temporal nulls,
subject bootstrap, and group permutation. These are the resampling
approaches commonly used by other ISC packages (for example BrainIAK
and the ISC toolbox), so 3dInSync lets you run familiar nonparametric
tests within AFNI and compare them with those tools.
* It offers alternatives such as leave-one-out ISC, Spearman correlation,
fisher_mean/median summaries, and ROI-wise output from an atlas.
* It is a quick way to inspect ISC maps or sanity-check an analysis, and
to compare results against a 3dISC model of the same data.
Compute voxelwise intersubject correlation (ISC) directly from aligned
subject time-series datasets. Subject resampling, temporal-null inference,
paired condition contrasts, and a 3dISC pair-map bridge are available.
The input datasets must have the same spatial grid and number of time
points. They should already be preprocessed, censored consistently, and
aligned in stimulus time. 3dInSync does not regress nuisance signals or
alter temporal alignment.
Required input:¶
-dataTable @TABLE
-dataTableFile TABLE
-dataTable Subj Group InputFile s01 control s01+tlrc ...
TABLE requires an InputFile column. A short table has one row per
subject. A long table has one row per Subj x Condition cell, with every
cell present exactly once. If a Group column is present, one
ISC map is produced per group; otherwise all rows form one group.
Exactly two groups also produce a first-minus-second difference map.
Group order is order of first appearance in TABLE.
Options:¶
-prefix PREFIX Output dataset prefix [InSync].
-mask MASK Analyze nonzero voxels in MASK. Without -mask, all
voxels are analyzed.
-isc_method METHOD pairwise : correlate every subject pair [default]
loo : correlate each subject with the mean of
the other subjects in the same group
-summary METHOD median : median ISC [default]
fisher_mean : mean in Fisher-z space, returned as r
-correlation METHOD pearson : ordinary Pearson correlation [default]
spearman : average-rank Spearman correlation. This is
robust to monotone amplitude distortions;
-summary median remains the robust default
across subject pairs.
-censor FILE One common 0/1 censor vector with one value per input
time point. Retained time points are identical for all
subjects, conditions, voxels, and ROIs. At least three
must remain. Censoring cannot be combined with temporal
nulls, whose circular timeline would become ambiguous.
-zcensor Omit a time point when any subject/condition input
volume is all zero in the analysis mask. This creates
one common retained timeline, like -censor.
-zcensor_warn PCT Warn for each subject/condition input with more than
PCT percent all-zero volumes [20].
-missing POLICY error : reject nonfinite retained input data [default]
common : at each voxel/ROI, drop a time point from all
subjects and conditions if any input is
nonfinite there. Adds a ValidTR output map and
cannot be combined with temporal nulls.
-atlas ATLAS Also compute ISC from each atlas parcel's mean time
series and write PREFIX.roi.1D. Positive integer atlas
values define ROIs; -mask, when present, intersects them.
These are descriptive ROI estimates and matrices; the
voxelwise resampling maps are not averaged or repainted.
-roi_sel LIST Restrict -atlas to an AFNI integer label list.
-save_matrix FILE With -atlas, save long-form ROI subject matrices with
Condition, ROI, Subj1, Subj2, groups, and correlation.
-roi_only Requires -atlas. Run the ENTIRE analysis (bootstrap,
permutation, temporal null, condition contrasts, pair
maps) on the atlas-parcel mean time series, with one
'voxel' per ROI, instead of on voxels. Each ROI mean
is formed as the datasets are read, so only
subjects x ROIs x time points are held in memory
(megabytes, not the full 4D grid) and FDR/FWE families
are the ROIs. -mask, when present, intersects the
atlas first. The bucket is painted back onto the
input grid (every voxel of an ROI gets its ROI value)
and PREFIX.roi.1D lists every statistic, one row per
ROI. Not combined with -save_matrix or -edges*.
-float16 Hold the subject data in memory as 16-bit floats, half
the size of the default 32-bit. Each voxel series is
stored as a z-score, with its mean and SD kept in
32 bits, so rounding error is relative to each voxel's
own variability (about 1e-3 of its SD per sample; ISC
differs from 32-bit storage by about 1e-4 or less).
Use it when the default would not fit;
do not mix results from the two storage modes within
one analysis. Without -mask this stores every grid
voxel.
Memory. Subject data are held in the smallest of: the datasets as stored
on disk (no -mask), only the in-mask voxels (with -mask, chosen
automatically when smaller), or -roi_only ROI series. Datasets are read
one at a time, so peak memory while loading is the compact store plus a
single dataset. The preflight estimate reports which representation was
chosen and its size, using the datatype actually stored.
-memory_limit G Refuse an estimated peak above G GiB. Without this
option the limit is 80% of detected physical RAM.
-memory_override Continue after the memory estimate exceeds its limit.
-progress M auto, bar, line, or off [auto].
-quiet Suppress progress and informational diagnostics.
-group_column NAME Data-table group column [Group]. If NAME is absent,
all subjects are analyzed together.
-condition_column NAME
Long-table condition column [Condition]. If present,
every Subj x Condition cell is required exactly once.
-condition_contrast C1 C2
Report ISC(C1)-ISC(C2) in every group and, for two
groups, G1(C1-C2)-G2(C1-C2).
-ncondperm P Use P synchronized within-subject C1/C2 swaps for
condition inference. P must be at least 20.
-condition_exact Enumerate all condition swaps when feasible; otherwise
sample -ncondperm P swaps [default 10000].
-condition_tail two|one
Two-sided or upper-tailed condition tests [two].
-save_pairwise PREFIX
Write a Fisher-z pair-map bucket. A short table also
gets PREFIX.3dISC.txt. A repeated-condition table gets
one runnable PREFIX.C1__C2.3dISC.txt per ordered
condition pairing plus PREFIX.3dISC.all.txt. Splitting
is required by current 3dISC's one-row-per-pair rule.
-nboot B Draw B subject-bootstrap samples independently within
each group and output percentile confidence limits.
B must be at least 100. [no bootstrap]
-boot_alpha A Two-sided bootstrap interval error rate [0.05], giving
the 100*(1-A) percent interval.
-nperm P For exactly two independent groups, use P synchronized
subject-label permutations. Small permutation groups
are enumerated exactly when P reaches their size.
[no permutation inference]
-exact Request exact enumeration of group assignments when
feasible. If the exact group is above the library cap,
sample -nperm P assignments instead (default 10000).
-seed S Reproducible permutation/bootstrap seed [1234567].
-tail 1sided|2sided|bisided
Sidedness for the group-difference permutation test
[2sided]. The tested effect is first group minus
second group. 1sided tests the positive direction.
2sided uses one pooled absolute-value null. bisided
corrects positive and negative tails against separate
max-statistic nulls and reports doubled tail p-values.
The older one/two spellings remain accepted.
-1sided Short form of -tail 1sided.
-2sided Short form of -tail 2sided.
-bisided Short form of -tail bisided.
-temporal_null TYPE Test each group's ISC against disrupted temporal
alignment. TYPE is one of:
timeshift : independent circular subject shifts
phase : independent Fourier phase randomization
This is distinct from the -nperm group-difference test.
-nnull N Number of synchronized temporal-null sets, including
identity set 0. N must be at least 20.
-min_shift K For timeshift, require circular distance of at least K
time points from zero [1]. Choose K from the temporal
autocorrelation scale. Identity set 0 is retained for
empirical p-values; every random set obeys K.
-temporal_tail one|two
Upper-tailed positive ISC [one] or two-sided temporal
inference.
-show_table Print the parsed data table before analysis.
Output:¶
Each condition/group contributes an ISC_CONDITION_GROUP brick and an
N_CONDITION_GROUP brick (condition is omitted for a short table). N is the
number of finite subject-pair correlations (pairwise) or subject ISC
values (loo) at that voxel. With two groups, ISC_A-B is also written.
Voxels with no valid estimate are stored as zero with N=0.
-nboot adds BootLo_LABEL and BootHi_LABEL maps. Duplicate copies of one
subject do not create self-pairs in pairwise ISC.
-nperm adds P, Z, Q, PFWE, and ZFWE maps for ISC_A-B per condition. Q and
PFWE cover one synchronized condition x in-mask family. Z and ZFWE are
signed normal equivalents of P and PFWE. Subjects are permuted as whole
rows and columns of the pooled matrix; pairwise edges are never shuffled.
-temporal_null adds TP, TZ, TQ, TPFWE, and TZFWE per condition/group. TQ
and max-FWE jointly cover condition x group x in-mask voxel. The
same seeded surrogate set is reused everywhere. Timeshift preserves each
complete time series; phase preserves its mean and power spectrum.
Edge (cofluctuation) ISC:¶
An edge time series is the moment-by-moment product of two ROI signals,
z_i(t)*z_j(t), where each ROI series is z-scored within subject (sample
SD). Its mean over time is the ordinary Pearson r of the pair. These
options ask whether subjects share those moment-to-moment cofluctuations.
All need -atlas. The ROI series for every subject and condition are
reduced to one common retained timeline (see -censor, -zcensor, -missing).
-edges ISC of the edge series of every ROI pair, with the
-isc_method, -summary, -correlation and group settings
used elsewhere. Writes PREFIX.edge.1D: one row per
condition, group and ROI pair, with the pair's ISC and
the ISC of each of its two ROIs (Node1ISC, Node2ISC)
side by side so edge synchrony can be read against
node synchrony.
-edges_matrix With -edges, also write one square matrix file per
condition and group, PREFIX_edge_[COND_]GROUP.netcc, in
the 3dNetCorr .netcc layout for tools that read it. CC
is edge ISC (r) and FZ its Fisher z. The DIAGONAL holds
NODE ISC, not 1.0. With -edges_nnull it adds EX (Excess),
P and PFWE matrices. The tables carry the same numbers.
-edges_rss ISC of the global cofluctuation amplitude, RSS(t) =
sqrt(sum over pairs of (z_i z_j)^2): do subjects'
whole-brain cofluctuation rise and fall together?
Adds RSS_ISC and RSS_N columns to PREFIX.frames.1D.
-edges_events FRAC In each subject, call the FRAC fraction of frames with
the highest RSS(t) 'events' [FRAC in (0,0.5]]. For each
frame count how many subjects of a group have an event
there. Adds NHigh, NSubj and Frac to PREFIX.frames.1D.
PREFIX.frames.1D has one row per condition, group and retained frame, with
MeanRSS (the subject-mean amplitude) and the columns for the options given.
The group-level RSS values repeat down each condition/group block.
-edges_nnull N Surrogate sets (at least 20, identity set included) for
the nulls below. -min_shift and -seed apply. Cost grows
with N times the number of edges times the number of
subject pairs: use -roi_sel or a coarse atlas first.
-edges : ROI j of each pair is circularly
shifted by ONE offset common to all
subjects, so each ROI's own ISC is
unchanged while the within-subject
i-j coupling is broken. Adds NullMean,
Excess (= ISC - NullMean), P, Z, Q,
PFWE and ZFWE to PREFIX.edge.1D. P and
PFWE cover condition x group x edge.
-edges_rss,
-edges_events: each subject is shifted independently.
Adds RSS_NullMean and RSS_P, and the
per-frame EvNullMean, EvP, EvZ, EvQ,
EvPFWE and EvZFWE (max over frames,
conditions and groups), to the frames
table.
Cautions for edge ISC:
* Edge ISC is largely inherited from node ISC. If ROIs i and j are each
synchronized across subjects, their product is too, even when their
coupling is not shared. Always read edge ISC next to Node1ISC and
Node2ISC. 'Excess' under -edges_nnull is the quantity that
speaks to shared coupling beyond the nodes.
* Edge series are products, so they are heavy-tailed and dominated by
high-amplitude frames. That is often the point; -correlation spearman
gives a robust alternative.
* These are stimulus-locked measures. They need subjects aligned in
stimulus time and are not meaningful for unlocked data such as rest.
* ROI series are z-scored over the retained frames only, so edge values
depend on censoring. A constant ROI series gives a zero edge.
* Group-label permutation and condition contrasts are not yet applied to
edges, and edge analyses do not yet support the 3dISC bridge
(-save_pairwise applies to the voxelwise maps only).
Reading edge ISC against the node ISCs (Excess = ISC - NullMean):
* A rough expectation for edge ISC from the nodes alone is the PRODUCT of
the two node ISCs when their shared drivers are independent; NullMean is
the empirical version of that. An edge ISC below either node ISC is
therefore normal.
* One node high, the other near zero, edge near zero: expected. The
product of a shared signal and an idiosyncratic one is idiosyncratic.
* Both nodes high, Excess near zero: both regions follow the stimulus, each
by its own driver, and the drivers are not time-locked to each other.
This is shared activity, not shared coupling. A clearly negative Excess
is unusual: look at timing or polarity differences across subjects.
* Edge high, nodes low or negative: the regions cofluctuate at the same
moments in everyone though each region's own course differs. Possible
causes are response polarity or latency differing across subjects (sign
cancels in the product), stimulus-locked changes in coupling strength, or
a shared artifact. Check -correlation spearman and the frames table.
* Excess clearly positive (small P, PFWE): the relationship between the
regions is time-locked across subjects beyond what their separate
synchrony gives. Read this as time-locked coupling, not as proof of
functional connectivity. Rule out shared nuisance signals (motion,
respiration, global signal, arousal), spatial blur between neighboring
ROIs, and a few extreme frames. The null breaks only i-j timing.
* Edge high and Excess near zero: the edge only passes along the nodes'
synchrony. Report the nodes, not the edge.
* With a median over pairs, negative node ISC can simply mean the sample's
majority polarity is opposite. Do not read it as anti-synchrony.
Example:¶
3dInSync -prefix movie_isc -mask brain+tlrc \
-isc_method pairwise -summary median \
-nboot 2000 -nperm 10000 -seed 314159 \
-temporal_null timeshift -nnull 5000 -min_shift 10 \
-dataTableFile subjects.txt
# subjects.txt
Subj Group InputFile
s01 control s01_movie_scale+tlrc
s02 control s02_movie_scale+tlrc
s21 patient s21_movie_scale+tlrc
s22 patient s22_movie_scale+tlrc
Inference scope:¶
Bootstrap intervals quantify subject-sampling uncertainty within groups.
Label permutation tests an independent two-group difference under subject
exchangeability. Temporal nulls instead test whether within-group ISC
exceeds chance temporal alignment; they do not replace label permutation
for a group difference. Condition inference swaps labels within subjects
and never breaks pairing. Pair-map export uses Fisher z for 3dISC.
Scope boundary:¶
This program's analysis is static ISC, plus the explicit edge modes above.
Dynamic/windowed ISC, ISFC, and ISPS require distinct estimands, outputs,
and null models and are not accepted as aliases here. They remain
candidates for explicit future modes.
* This binary version of 3dInSync is compiled using OpenMP, a semi-
automatic parallelizer software toolkit, which splits the work across
multiple CPUs/cores on the same shared memory computer.
* OpenMP is NOT like MPI -- it does not work with CPUs connected only
by a network (e.g., OpenMP doesn't work across cluster nodes).
* For some implementation and compilation details, please see
https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html
* The number of CPU threads used will default to the maximum number on
your system. You can control this value by setting environment variable
OMP_NUM_THREADS to some smaller value (including 1).
* Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of
using all CPUs available.
++ However, on some systems, it seems to be necessary to set variable
OMP_NUM_THREADS explicitly, or you only get one CPU.
++ On other systems with many CPUS, you probably want to limit the CPU
count, since using more than (say) 16 threads is probably useless.
* You must set OMP_NUM_THREADS in the shell BEFORE running the program,
since OpenMP queries this variable BEFORE the program actually starts.
++ You can't usefully set this variable in your ~/.afnirc file or on the
command line with the '-D' option.
* How many threads are useful? That varies with the program, and how well
it was coded. You'll have to experiment on your own systems!
* The number of CPUs on this particular computer system is ...... 1.
* The maximum number of CPUs that will be used is now set to .... 1.
++ Compile date = Oct 13 2026 {AFNI_26.3.04:linux_ubuntu_24_64}
