:orphan: .. _ahelp_3dInSync: ******** 3dInSync ******** .. contents:: :local: | Usage: 3dInSync [options] ============================================================== .. code-block:: none 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: =========================================================== .. code-block:: none -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: =========================================================== .. code-block:: none -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: =========================================================== .. code-block:: none 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: ========================================================== .. code-block:: none 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: =========================================================== .. code-block:: none 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: ========================================================= .. code-block:: none 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: ========================================================== .. code-block:: none 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}