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.  Output datasets follow the first
                     input's view (+orig, +tlrc) and template space, unless
                     MASK (or, with no -mask, -atlas) is in a different
                     view; then they take MASK's, as 3dRSA does.  So
                     template-space data that are labeled +orig, analyzed
                     with a +tlrc mask, are written +tlrc, and subject-space
                     data with a subject-space mask stay +orig.

-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. Censored temporal nulls require explicit
                     -temporal_censor joint_shift (see censoring example below).

-censor_column NAME  Optional per-source censor column [Censor]. Files are
                     finite 0/1 vectors on the full input timeline. Intersect
                     all subjects/conditions with global -censor/-zcensor.
                     Static ISC keeps its output layout and inference;
                     temporal censoring uses explicit joint_shift mode. Save
                     PREFIX.censor.tsv and PREFIX.common_censor.1D.

-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.
                     Run/block/window analyses write PREFIX.isc/ bundles; see below.

-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.

Numbered examples: whole input, runs, blocks, and sliding windows

Examples 1-2 and 5a use the same basic subjects.txt table:
Subj Group InputFile
s01  A     s01/bold.nii.gz
s02  A     s02/bold.nii.gz
s03  A     s03/bold.nii.gz
s04  B     s04/bold.nii.gz
s05  B     s05/bold.nii.gz
s06  B     s06/bold.nii.gz
Include every subject, with at least three subjects per group. Subjects must
share stimulus time. Inputs retain their full original timelines.

1. Original whole-run / whole-input ISC

   3dInSync -prefix whole_isc -isc_method pairwise -summary median \
            -dataTableFile subjects.txt

   One estimate across the entire input timeline; no Xmat or window options
   are needed. If inputs contain concatenated runs, this uses all their TRs
   together. It does not average separate run correlations.
   Optional subject inference: add -nboot 2000 and/or -nperm 10000 -seed 314159.
   The group-permutation example requires the two groups shown above.

   1b. Whole-input ISC with per-subject censor files

   3dInSync -prefix whole_censored -nboot 2000 \
            -dataTableFile subjects_censored.txt

   Add a Censor column to the SAME main table, for example:
   Subj Group Censor        InputFile
   s01  A     s01.censor.1D s01/bold.nii.gz
   s02  A     s02.censor.1D s02/bold.nii.gz
   s03  A     s03.censor.1D s03/bold.nii.gz
   # Continue with the other subjects if using two groups.
   A 1 retains a TR; a 0 censors it. Common support intersects source masks.

2. Separate ISC for each run

   3dInSync -run_starts 0,200 -prefix run_isc \
            -dataTableFile subjects.txt

   For two concatenated runs, run 1 starts at original TR 0 and run 2 at TR
   200. Each run gets its own estimate. Supply the actual zero-based starts.
   Add -whole_summary to ALSO obtain the whole-input estimate from example 1.
   An Xmat table can supply run boundaries instead of -run_starts.

Examples 3-4 and 5b use subjects_xmat.txt (one row per subject):
Subj Group Xmat                  InputFile
s01  A     s01/X.nocensor.xmat.1D s01/bold.nii.gz
s02  A     s02/X.nocensor.xmat.1D s02/bold.nii.gz
s03  A     s03/X.nocensor.xmat.1D s03/bold.nii.gz
s04  B     s04/X.nocensor.xmat.1D s04/bold.nii.gz
s05  B     s05/X.nocensor.xmat.1D s05/bold.nii.gz
s06  B     s06/X.nocensor.xmat.1D s06/bold.nii.gz
Here Vis and Aud are example StimLabels; substitute your design's labels.
Blocks are modeled-response support above the chosen peak fraction, not
recovered stimulus onset/duration files. The full design defines boundaries.
See Xmat-defined runs and blocks below for regressors and censor inputs.

3. Separate ISC for each block WITHIN ONE selected run

   3dInSync -xmat_blocks each -xmat_stims Vis,Aud -xmat_runs 1 \
            -xmat_threshold 0.5 -prefix run1_blocks \
            -dataTableFile subjects_xmat.txt

   One estimate per individual Vis/Aud block in run 1. No sliding occurs:
   each estimate uses that whole block's retained samples. Run IDs are
   one-based. Choose the response threshold explicitly for your design.

4. Separate ISC for each block IN EACH run

   3dInSync -xmat_blocks each -xmat_stims Vis,Aud \
            -xmat_threshold 0.5 -prefix all_run_blocks \
            -dataTableFile subjects_xmat.txt

   Omitting -xmat_runs selects all runs; -xmat_runs 1,2 selects a subset.
   Each individual block retains its run identity. Blocks are not combined.

   4b. Also summarize same-type blocks separately for each run

   3dInSync -xmat_blocks by_stim -xmat_stims Vis,Aud \
            -xmat_threshold 0.5 -block_summary median -prefix type_per_run \
            -dataTableFile subjects_xmat.txt

   Retain individual block results AND add one Vis and one Aud aggregate per
   run. Correlate within blocks, summarize corresponding pair/LOO components
   across blocks, then summarize within groups. This is not concatenation.
   Add -xmat_across_runs only if the desired type aggregate spans runs.

5. Sliding-window ISC

   5a. Slide separately within each run

   3dInSync -run_starts 0,200 -window 15 -step 1 -prefix sliding_runs \
            -dataTableFile subjects.txt

   Windows have 15 TRs and advance by 1 TR. With TR=2 seconds, these are
   30-second windows advancing every 2 seconds. No window crosses a run join.

   5b. Slide within each individual block, separately in each run

   3dInSync -xmat_blocks each -xmat_stims Vis,Aud -xmat_threshold 0.5 \
            -window 15 -step 1 -prefix sliding_blocks \
            -dataTableFile subjects_xmat.txt

   Restart the sliding schedule at each block's beginning. Windows never
   cross block/run boundaries. Blocks shorter than 15 TRs contribute no
   windows; incomplete trailing windows are omitted and short blocks reported.
   Add -xmat_runs 1 to restrict this example to one run. Sliding windows
   require each, not by_stim; this does not average matched window positions
   across repeated blocks.

6. Age-covariate modeling WITH 3dISC, using pair maps FROM 3dInSync

   This is a two-program workflow: 3dInSync computes and exports ISC pair maps;
   3dISC fits the mixed-effects model, age effect, and contrasts using R.
   3dInSync itself does not fit a general covariate model. Its -isc_* options
   configure the generated 3dISC commands; they do not fit the model directly.

   Keep subject-level covariates in the main data table. This example models
   one cohort; there is no Group column or group contrast.

   # subjects_age.txt
   Subj Age InputFile
   s01  20  s01/bold.nii.gz
   s02  22  s02/bold.nii.gz
   s03  24  s03/bold.nii.gz
   s04  26  s04/bold.nii.gz
   s05  28  s05/bold.nii.gz
   s06  30  s06/bold.nii.gz

   # Step 1: compute pair maps and write 3dISC inputs/commands.
   3dInSync -run_starts 0,200 -prefix age_runs -save_pairwise age_models \
            -isc_model 'I(Age1+Age2)+(1|Subj1)+(1|Subj2)' \
            -isc_qVars Age1,Age2 -isc_qVarCenters 25,25 \
            -isc_gltCode intercept '1 0' -isc_gltCode age_sum '0 1' \
            -dataTableFile subjects_age.txt

   # Step 2: call 3dISC through the generated scripts to fit the models.
   sh age_models.isc/run_all.sh

   Age is copied into Age1/Age2 for the two members of each exported pair.
   Center each age at 25 years, then model their SUM. The intercept is at
   pair mean age 25; age_sum tests the slope per unit of the centered sum.
   I(Age1+Age2) is symmetric: exchanging pair members leaves it unchanged.
   Choose the centering age to suit the study; 25 is illustrative.

   run_all.sh calls 3dISC once per requested run/block/window/summary. 3dISC
   does the covariate modeling; 3dInSync's export step does not execute R.
   Adding Age to the table alone does not adjust 3dInSync's ISC estimates or
   permutation tests. 3dISC and its R dependencies must be available for step 2.

   Use -run_starts 0 for a single whole-input model. For sliding windows, add
   -window 15 -step 1. For block models, use the Xmat options from examples
   3-4 and include Age alongside Xmat in the same main data table.

For examples 2-5, add -check_table to inspect expanded intervals before
estimation. Remove it to compute ISC. Runs, blocks, and windows have separate
result buckets plus a manifest; -whole_summary adds a full-input estimate.
Add -atlas parcels.nii.gz -roi_only to analyze parcel mean time series.
See the inference options below to add subject or temporal inference.
Explicit interval tables are an alternative to Xmat-defined blocks; their
Selection/Segment/Run/StartTR/StopTR columns are described below.

Optional run/block/window estimates:

Whole-input ISC above needs no window options or Xmat. The following
options estimate ISC for runs, blocks, windows, and summaries. Add -check_table to
validate schedules without loading BOLD samples or computing estimates.

In output tables, a 'selection' means one requested run, block, sliding
window, or combined-block/whole-input summary. SelectionID identifies that
analysis period; it does not mean selecting significant findings. Column
names (Selection, SelectionID) and filenames keep this technical label.

-check_table         Validate table, headers, and requested time intervals;
                     write PREFIX.selections.tsv and PREFIX.selection_summary.txt.
-whole_summary       Also estimate the full original input timeline, with its
                     censor mask. Separate whole_input role; not a window mean.
-window W            Complete sliding windows of W TRs (integer >=3).
-step S              Window step in TRs [1]; requires -window.
-run_starts LIST      Zero-based run starts, e.g. 0,100; first must be 0.
-tr SEC              Supply missing TR in seconds; reject header conflicts.
-min_valid N         Minimum retained samples per estimate [3], integer >=3.
-min_valid_frac F    Minimum retained/nominal fraction [0], in [0,1].
                     Both gates apply after censoring and common missingness.
-combine_blocks block_summary|pool
                     block_summary [default]: correlate within each block,
                     summarize corresponding pair/LOO values across blocks,
                     then apply the existing group -summary.
                     pool: concatenate retained segments before correlation.
-block_summary median|fisher_mean  Across-block summary [median]; independent
                     of the group -summary. A single admitted block is identity.
-block_missing require_all|drop_common  [require_all]. A block needs the
                     per-block -min_valid count/fraction and finite values
                     for every required pair/LOO subject in every group.
                     drop_common removes that block from ALL groups' aggregates
                     at the voxel; require_all invalidates the aggregate.
-min_blocks N        Minimum admitted blocks per aggregate [1], integer >=1.
-min_block_frac F    Minimum admitted/nominal block fraction [0], in [0,1].
-block_weight equal  Equal weights only; coverage weighting is not implemented.
                     Block-summary options cannot be combined with pool.
-segment_center none|mean  With pool only: center each retained segment [none].

3dInSync -window 30 -step 10 -run_starts 0,100 \
         -prefix movie_windows -dataTableFile subjects.txt
One result bucket per run/block/window/summary: PREFIX.sel000001.nii.gz, etc.
One-dimensional inputs use .1D buckets. PREFIX.results.tsv lists completed
outputs and ends with Status: complete only after all requested analyses finish.
Individual components are retained alongside block summaries and pools.
Block-summary buckets append BlocksNominal, BlocksEligible, BlocksUsed per
condition. Every contributing edge/LOO subject uses exactly BlocksUsed blocks.
PREFIX.selXXXXXX.blocks.nii.gz (or .1D) records each block's retained TRs,
eligibility and final weight; PREFIX.block_support.tsv maps these bricks to
original block IDs/coordinates. Weights are 1/BlocksUsed, or zero if unused.
Aggregate ValidTR is the total over admitted blocks, zero if the aggregate
fails. Single-block outputs retain their own descriptive validity rules.
Support can differ across voxels/conditions; paired-condition contrasts
require identical coordinates and admitted support (see inference below).
Original condition/group ISC,N brick order is followed by ValidTR, Valid,
PairComplete, and difference-validity maps. Invalid ISC is stored as zero
with Valid=0; a real zero has Valid=1. Constant series invalidate correlations.
PairComplete tests the within-group pair graph; it is not export permission.
-missing error checks the requested union after common censoring; unselected
samples are ignored except with temporal nulls, which check full source runs.
-missing common filters across all sources/conditions.
-zcensor keeps its global raw-volume rule. Save the final common censor vector.

Subject-based inference for runs, blocks, windows, and summaries:
Add confidence intervals and group/condition tests to the ISC estimates.
Use -nboot, -nperm/-exact, or -condition_contrast with -ncondperm/-condition_exact.
Resampling draws are shared across requested runs/blocks/windows/summaries.
Group FWE/FDR covers all these results x conditions x space. Condition FWE/FDR
covers all matched results x effects x space. With -atlas, voxel AND parcel
tests form one family; -roi_only counts each parcel once. Bootstrap CIs are pointwise.
Results: .selXXXXXX.infer.nii.gz, .inference.tsv, .inference_draws.tsv and
(with atlas) .inference_roi.tsv; see .results.tsv for the completion marker.
Observed admitted blocks stay fixed during resampling; incomplete components
or any invalid null invalidate that test cell. Paired conditions must have
identical coordinates and admitted blocks. BootN/BootValid report usable draws
(at least 10 for CI). Invalid inference cells have p/q=1 and InferValid=0.
Global FDR memory is budgeted; output maps use a temporary disk spool.

Temporal-surrogate tests for runs, blocks, windows, and summaries:
  3dInSync -window 30 -step 10 -run_starts 0,200 \
           -temporal_null timeshift -nnull 1000 -min_shift 10 \
           -whole_summary -prefix window_nulls -dataTableFile subjects.txt
Independent subject/run shifts or phases are generated on FULL original runs
before extracting windows/blocks. Never shift across a run join. Same draws
are reused across conditions, runs/blocks/windows/summaries and space. Draw 0 is the
original data. -min_shift is checked against each participating run length.
Supports individual windows/blocks, pooled segments (including mean centering),
component-first median/Fisher block summaries, and multi-run -whole_summary.
Fixed observed block support and require_all/drop_common apply to each draw.
TemporalISC/TP/TZ/TQ/TPFWE/TZFWE/TInferValid appear in the inference buckets.
Temporal FWE/FDR covers all requested runs/blocks/windows/summaries x conditions
x groups x space, separately from group/condition tests. -temporal_tail applies.
.temporal_draws.tsv records run seeds and shifts; phase factors use the seeded
THD_phase_set_factor generator. Phases preserve each run's DC and Nyquist.
All samples in participating runs must be finite and retained, including
samples outside requested windows. All-one censor masks are allowed; actual
censoring requires the explicit joint_shift option below. Nonparticipating
runs may be censored. A full-input summary makes every run participate.

Temporal-surrogate tests with censoring (explicit opt-in):
  3dInSync -window 30 -run_starts 0,200 -temporal_null timeshift \
           -temporal_censor joint_shift -nnull 1000 -prefix censored_windows \
           -dataTableFile subjects_with_Censor.txt
joint_shift moves each subject/run signal AND its source censor masks by
the same offset. Global -censor is incorporated into each source mask before
shifting. Intersect shifted masks across ALL subjects/conditions on every
draw, then reapply count/fraction and block-admission gates. Never compress
the timeline. Windows, block summaries, pooling and whole summaries work.
No-window calls use separate result buckets (one per run).
Retained TRs and admitted blocks can differ from those in the observed estimate.
Every failed null draw counts as an exceedance in conservative TP/TPFWE
bounds. No skipping or retrying. FWE uses the prespecified family including
unresolved cells; BH includes observed-invalid cells with p=1. TNullN reports
finite draws including identity; TInferValid indicates an estimable OBSERVED
cell here, not a complete-null cell. Z/q are derived from the p-value bounds.
.temporal_support.tsv reports per-draw/component common counts/fractions.
Its component coverage flag is diagnostic; pooling gates the combined count.
Check TNullN and the unresolved-maxima count: one unreliable component can
make family-wide inference very conservative. This loss is not hidden.
Excluded source frames may contain nonfinite/artifact values; own-retained
samples must be finite throughout each participating run. Use float32 storage.
Censored phase inference, -zcensor, -missing common, alternative censor
cohorts, and coverage weights are not supported by this first release.
Joint shifts assume a suitable runwise signal/mask null; they do not correct
arbitrary task- or motion-related informative missingness.

ROI estimates for runs, blocks, windows, and summaries:
  3dInSync -window 30 -step 10 -atlas parcels.nii.gz -roi_only \
           -whole_summary -prefix roi_windows -dataTableFile subjects.txt
-atlas retains voxelwise buckets and also estimates each mask-intersected
parcel mean time series using the same time intervals and estimator. -roi_only skips
voxelwise estimation and expands parcel results onto the atlas grid.
PREFIX.roi.tsv contains every ROI result/support brick with SelectionID,
Run, Stimulus, Condition, ROI, label, voxel count and value. Run=mixed denotes
a summary spanning runs (whole_input always uses Run=all).
PREFIX.bricks.tsv maps every file and zero-based brick selector to its label.
-save_matrix FILE writes ROI pair correlations for each run/block/window/summary,
including cross-group pairs, even with LOO summaries. Invalid pairs are nan, Valid=0.
Aggregate matrices use the same admitted blocks as the requested estimator.
These are descriptive r values; they are not 3dISC model bundles.
Atlas run/block/window analyses use float32; -float16 is ignored with a notice.
Source data are read once. One run/block/window/summary's result/support buffers
are resident at a time; scheduling metadata grows with the requested intervals.
Memory estimates include ROI matrices, full-grid outputs and worker storage.
Invalid output names, label collisions and overwrite conflicts fail before
BOLD loading. Only final Status: complete in results.tsv certifies the bundle.

3dInSync -check_table -window 30 -step 10 -run_starts 0,100 \
         -prefix movie_schedule -dataTableFile subjects.txt

For explicit intervals, repeat subject rows with these extra columns:
Subj Group Selection Segment Run StartTR StopTR InputFile
s01  A     Vis_all   b01     1   30      59     s01_movie.nii.gz
s01  A     Vis_all   b02     1   90      119    s01_movie.nii.gz
# Repeat the same interval rows for every other subject.
Run is one-based; StartTR/StopTR are zero-based, inclusive, within run.
A repeated Selection combines nonoverlapping segments. Sliding windows
stay inside each segment/run; short segments produce no windows (reported).
IDs/manifest order are canonical; original input row numbers are retained.
-censor can report retained counts without shifting any boundaries.
zcensor/nonfinite checks require image data and are reported as pending.
Xmat and optional Censor columns can supply run/block metadata (see below).
-check_table does not validate or run inference or pair-map exports.

Xmat-defined runs and blocks (optional):

One row per subject, or per subject/Condition:
Subj Group Xmat                  InputFile
s01  A     s01/X.nocensor.xmat.1D s01/bold.nii.gz
s02  A     s02/X.nocensor.xmat.1D s02/bold.nii.gz
# Include all subjects (at least three per group).

-xmat_blocks each|by_stim
                     each: one estimate per response-defined block.
                     by_stim: also aggregate blocks of each type per run.
                     Individual blocks are retained alongside aggregates.
-xmat_stims LIST      Exact comma-separated StimLabels [all]; design order.
-xmat_threshold F     REQUIRED for blocks: 0 < F <= 1 of full-design peak.
-xmat_runs LIST       One-based comma-separated runs [all].
-xmat_across_runs     With by_stim, aggregate each type across selected runs.

3dInSync -check_table -xmat_blocks by_stim -xmat_stims Vis,Aud \
         -xmat_threshold 0.5 -prefix blocks -dataTableFile subjects.txt

Blocks follow modeled response support, not original stimulus timings.
Selected stimuli need one finite, nonnegative column each. Overlapping
stimuli retain shared TRs; overlap counts and subject-by-stimulus tables
are printed. Censor holes never split blocks. A full design is required:
if Xmat is censored, add an XmatFull column naming its uncensored design.
Optional Censor files are intersected with GoodList and common -censor;
per-subject Censor files are also supported in ordinary whole-run ISC.
Source files must retain the full timeline (no subbrick selectors).
Xmat alone supplies run/TR/censor metadata without selecting blocks.
-window/-step may subdivide each block, but cannot be combined with by_stim.
Use manual intervals or Xmat block expansion to define the analysis periods.
Omit -check_table to estimate individual blocks AND the requested summaries.
No ISC estimation is performed by -check_table.

3dISC model bundles for runs, blocks, windows, and summaries:

-save_pairwise PREFIX  For run/block/window analyses, write PREFIX.isc/ with one
                     Fisher-z pair bucket, common-valid mask, support bucket,
                     data table and script per run/block/window/summary and ordered
                     condition pairing. Includes cross-group subject pairs.
-isc_model FORMULA    Shared 3dISC formula [1+(1|Subj1)+(1|Subj2)].
                     The default tests an intercept, not a group difference.
-isc_qVars LIST       Comma-separated exported numeric columns, e.g. Age1,Age2.
-isc_qVarCenters LIST Comma-separated finite centers, in qVars order. If omitted,
                     3dISC uses its normal centering. Requires -isc_qVars.
-isc_gltCode NAME WEIGHTS  Repeat for each GLT; quote the numeric weights.
                     Names must be unique. R checks model rank/GLT dimensions.
-isc_jobs N           Jobs for each generated fit [1], positive integer.
                     -isc_* options require a run/block/window analysis and -save_pairwise.

3dInSync -window 30 -step 10 -save_pairwise movie_models \
         -prefix movie_windows -dataTableFile subjects.txt
# Later, explicitly run the generated models:
sh movie_models.isc/run_all.sh

Model scripts are generated, never run automatically. run_all.sh stops on
failure; each script requires a completed jobs.tsv. Scripts work from another
working directory. They cd to the absolute bundle directory; after moving a
bundle update those paths. All dataset/table references inside it are local.
Xmat/Censor/interval-control columns are excluded from model covariates. Genuine
covariates retain both copies, e.g. Age1,Age2. Column collisions, unrepresentable
R table tokens and nonnumeric qVars fail before BOLD loading. Subject order is
lexical. GroupPair uses lexically sorted group labels; no contrast is inferred.
3dISC swaps subject IDs internally, but does not swap custom covariate copies.
They are pair-slot values. A symmetric model expression such as I(Age1+Age2)
must be chosen explicitly; no mean/difference/similarity transform is inferred.
Cross-condition r is corr(Subj1/cond1,Subj2/cond2), not an average of orientations.
Cross-condition jobs require matching original block/sample coordinates.
Export is pairwise even for LOO descriptions. Block admission requires every
modeled edge finite; aggregation then uses the same admitted blocks for all
edges. Job-specific support maps record actual retained counts and weights.
Fisher z is applied AFTER the final pair-r aggregate; exact endpoints are
clamped to +/-0.999999. Model masks require every modeled edge to be finite.
Zero-support jobs fail with an incomplete bundle; masked zero placeholders
must not be fitted. -roi_only exports parcel-mean pair maps on the atlas grid;
-atlas without -roi_only exports voxelwise pair maps. Outputs are NIfTI even
for 1D inputs. One result/condition-pair export job is held in memory at a time.
Separate fits neither test changes across windows nor correct across result buckets.
Joint repeated-window mixed models remain deferred; 3dInSync resampling tests are available.

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 supports whole-input, per-run, per-block and sliding-window ISC,
block summaries, subject-based and temporal-surrogate inference, and edge modes.
Additional ISFC and ISPS analyses remain candidates for explicit later modes.

References:

Selected methodological references and related ISC approaches.
The options above specify the methods implemented by 3dInSync.

* Hasson, Nir, Levy, Fuhrmann & Malach (2004), Science 303(5664):1634-1640.
  [original ISC] Intersubject synchronization of cortical activity during
  natural vision. https://doi.org/10.1126/science.1089506
* Hasson, Malach & Heeger (2010), Trends Cogn Sci 14(1):40-48. [ISC review]
  Reliability of cortical activity during natural stimulation.
  https://doi.org/10.1016/j.tics.2009.10.011
* Kauppi, Jaaskelainen, Sams & Tohka (2010), Front Neuroinform 4:5.
  [frequency-specific ISC, resampling inference] Inter-subject correlation of
  brain hemodynamic responses during watching a movie: localization in space
  and frequency. https://doi.org/10.3389/fninf.2010.00005
* Kauppi, Pajula & Tohka (2014), Front Neuroinform 8:2. [ISC Toolbox]
  A versatile software package for inter-subject correlation based analyses
  of fMRI. https://doi.org/10.3389/fninf.2014.00002
* Nastase, Gazzola, Hasson & Keysers (2019), Soc Cogn Affect Neurosci
  14(6):667-685. [ISC tutorial/best practices]
  Measuring shared responses across subjects using intersubject correlation.
  https://doi.org/10.1093/scan/nsz037
* Chen, Shin, Taylor, Glen, Reynolds, Israel & Cox (2016), NeuroImage
  142:248-259. [subject-wise resampling and false-positive control]
  Untangling the relatedness among correlations, Part I: nonparametric
  approaches to inter-subject correlation analysis at the group level.
  https://doi.org/10.1016/j.neuroimage.2016.05.023
* Chen, Taylor, Shin, Reynolds & Cox (2017), NeuroImage 147:825-840.
  [LME group analysis; basis of 3dISC] Untangling the relatedness among
  correlations, Part II: inter-subject correlation group analysis through
  linear mixed-effects modeling. https://doi.org/10.1016/j.neuroimage.2016.08.029
* Chen, Taylor, Qu, Molfese, Bandettini, Cox & Finn (2020), NeuroImage
  216:116474. [Bayesian multilevel ISC background]
  Untangling the relatedness among correlations, Part III: inter-subject
  correlation analysis through Bayesian multilevel modeling for naturalistic
  scanning. https://doi.org/10.1016/j.neuroimage.2019.116474
* Pajula & Tohka (2016), Comput Intell Neurosci 2016:2094601. [sample size]
  How many is enough? Effect of sample size in inter-subject correlation
  analysis of fMRI. https://doi.org/10.1155/2016/2094601
* Simony et al. (2016), Nature Communications 7:12141. [ISFC background]
  Dynamic reconfiguration of the default mode network during narrative
  comprehension. https://doi.org/10.1038/ncomms12141
* Prichard & Theiler (1994), Phys Rev Lett 73(7):951-954.
  [phase-randomized surrogates] Generating surrogate data for time series
  with several simultaneously measured variables.
  https://doi.org/10.1103/PhysRevLett.73.951
* Winkler et al. (2014), NeuroImage 92:381-397.
  Permutation inference for the general linear model.
  [permutation inference and exchangeability]
  https://doi.org/10.1016/j.neuroimage.2014.01.060


* 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 = Nov 17 2026 {AFNI_26.3.12:linux_ubuntu_24_64}