:orphan: .. _ahelp_3dShuffle: ********* 3dShuffle ********* .. contents:: :local: | .. code-block:: none Usage: 3dShuffle [options] Permutation/randomization testing for AFNI datasets. Paired/repeated-measures and one-sample tests use sign flips. Independent two-sample tests shuffle group labels while preserving group sizes. By default, all inputs must be single-brick datasets on the same grid. With -brickwise, each -input takes one multi-brick dataset and each brick is treated like one dataset in the corresponding input list. Example 1 -- paired/repeated-measures t-tests: 3dShuffle \ -conditions 3 \ -cond_labels baseline endsleep longrec \ -input s01_base+tlrc s02_base+tlrc ... \ -input s01_end+tlrc s02_end+tlrc ... \ -input s01_ltr+tlrc s02_ltr+tlrc ... \ -contrast baseline endsleep \ -contrast baseline longrec \ -contrast endsleep longrec \ -method signflip \ -stat paired_ttest \ -sided 2sided \ -mode exact \ -mask sleep_group_mask+tlrc \ -prefix sleep_shuffle Example 2 -- one-sample t-test against zero: 3dShuffle \ -conditions 1 \ -cond_labels activation \ -input s01_activation+tlrc s02_activation+tlrc \ s03_activation+tlrc s04_activation+tlrc \ s05_activation+tlrc s06_activation+tlrc \ -method signflip \ -stat onesample \ -sided 2sided \ -mode exact \ -mask activation_group_mask+tlrc \ -prefix activation_shuffle Example 3 -- independent two-sample t-test: 3dShuffle \ -conditions 2 \ -cond_labels patient control \ -input pat01+tlrc pat02+tlrc pat03+tlrc \ pat04+tlrc pat05+tlrc \ -input con01+tlrc con02+tlrc con03+tlrc \ con04+tlrc con05+tlrc con06+tlrc \ -contrast patient control \ -method shuffle \ -stat twosample \ -sided 2sided \ -mode random \ -niter 10000 \ -seed 1234567 \ -mask patient_control_mask+tlrc \ -prefix patient_vs_control_shuffle Example 4 -- paired test with wildcard-expanded -input lists: Wildcards ('*' and '?') in a -input filename are expanded by 3dShuffle itself, the same as -setA/-setB in 3dttest++. Quote each wildcarded argument so the shell passes it through unexpanded, especially when it also carries a sub-brick selector like '[..]'. 3dShuffle \ -conditions 2 \ -cond_labels OLS REML \ -input 'OLSQ.*.HEAD[Vrel#0_Coef]' \ -input 'REML.*.HEAD[Vrel#0_Coef]' \ -contrast OLS REML \ -method signflip \ -stat paired_ttest \ -sided 2sided \ -mode exact \ -mask mask+tlrc. \ -prefix olsreml_shuffle Required options: -conditions N Number of repeated-measure conditions or one-sample input lists. -input dset ... One -input list per condition. Paired and one-sample lists must have equal counts; two-sample lists may have different counts. -brickwise Each -input must contain exactly one dataset. The program loops over that dataset's sub-bricks as the samples/subjects for that condition. For paired and one-sample tests, all inputs must have the same number of sub-bricks; for two-sample tests, groups may have different numbers of sub-bricks. -contrast A B For paired and two-sample tests, test A-B. A and B can be condition labels or 1-based condition indices. May be repeated. Not used with -stat onesample. -prefix PREFIX Output bucket dataset prefix. Labels: -cond_labels L1 ... LN Names for the N conditions. Used for contrasts and output sub-brick labels. Permutation options: -method signflip Required for paired and one-sample tests. Default. -method shuffle Required for two-sample tests. Group labels are exchanged while the original group sizes are fixed. -stat paired_ttest Paired t-statistic. Default. -stat onesample One-sample t-statistic against zero. Each input list is tested independently; do not use -contrast. -stat twosample Independent-group t-statistic for each contrast A-B. The default assumes equal variances (pooled t-test). -unpooled With -stat twosample, use the unequal-variance Welch t-statistic. This overrides the pooled assumption. -sided 1sided|2sided|bisided Default: 2sided. Same keywords as 3dClustSim, p2dsetstat and dsetstat2p use. With 1sided, the tested direction is positive. For contrasts, -contrast A B tests whether A > B; reverse the order to test B > A. For one-sample and two-sample group outputs, positive means group > 0. With bisided, each tail is corrected against its own max-statistic null: a positive voxel is ranked among the permuted maxima and a negative one among the permuted minima. As in 3dClustSim, each tail carries p/2, the same per-tail threshold 2sided applies, so the reported p is on the 2sided scale. Prefer bisided over 2sided when the two directions are not expected to behave alike -- an asymmetric null makes a single pooled |t| distribution misleading for one of them. -tails one|two Older spelling of -sided 1sided|2sided; still accepted so existing scripts keep working. -mode exact|random Exact enumerates all 2^N sign patterns for one-sample tests and all choose(NA+NB,NA) group assignments for two-sample contrasts. Random uses -niter draws. Default: exact when that is feasible, otherwise random. See 'Choosing exact versus random' below. -niter N Number of random sign-flip or shuffle iterations. Default: 10000. Ignored by -mode exact. -seed S Random seed for -mode random. Default: 1234567. Masking: -mask MASK Restrict analysis to nonzero voxels in MASK. This is strongly recommended for group analyses. -automask Use AFNI's automask procedure on the mean absolute value across every input dataset. Cannot be combined with -mask. WARNING: Statistical/effect maps generally do not have the intensity structure expected by automask, so the resulting coverage can be unreliable. Prefer a carefully constructed group mask with -mask. Masked voxels and voxels containing NaN/Inf in an automask analysis have statistic bricks set to 0 and p-value bricks set to 1. Output: Paired and one-sample tests produce 6 sub-bricks per test: CON_mean observed mean of A-B, or condition mean for onesample CON_t observed t-statistic. Tagged FITT when its degrees of freedom are fixed, for parametric reference only; do not use this brick for permutation inference. Welch contrast t bricks are not stat-coded because their degrees of freedom vary by voxel. A voxel whose inputs are identical across every dataset, with a nonzero effect, has no denominator and so an infinite t; it is stored as 1e20 and reported in a warning. Its permutation p-value is still bounded normally, but such voxels usually mean a constant region slipped inside the mask. CON_p_unc voxelwise empirical p-value (uncorrected) CON_p_fwe max-stat FWE-corrected empirical p-value CON_z_unc signed z equivalent of CON_p_unc, tagged FIZT so the AFNI GUI threshold slider shows a correct p-value readout. Uncorrected -- exploratory only. CON_z_fwe signed z equivalent of CON_p_fwe, tagged FIZT. *** THRESHOLD ON THIS BRICK FOR REPORTED RESULTS *** It is whole-brain FWE-corrected already; no further cluster correction is required. In both z bricks, |z| is the strength of the evidence and the sign is only the direction of the effect, so the AFNI slider (which ranks by |z|) removes the weakest voxels first. Voxels with no evidence sit at z = 0, the same value written outside the mask. The z is encoded so that AFNI's own FIZT reading of it -- which is two-sided -- reports back the empirical permutation p-value in these bricks. 3dPval on a z brick returns the matching p_unc/p_fwe value. With 1sided only the tested direction is inferable, so those z bricks are non-negative; use 2sided or bisided to see the opposite direction. Bisided z bricks are signed like 2sided ones. Each two-sample contrast produces 18 sub-bricks, in this order: GrpA_mean GrpA_t GrpA_p_unc GrpA_p_fwe GrpA_z_unc GrpA_z_fwe GrpB_mean GrpB_t GrpB_p_unc GrpB_p_fwe GrpB_z_unc GrpB_z_fwe CON_mean CON_t CON_p_unc CON_p_fwe CON_z_unc CON_z_fwe GrpA and GrpB are one-sample sign-flip tests against zero. CON is the shuffled two-sample test of A-B. Labels use the supplied condition and contrast names. Each six-brick family has its own max-stat correction. IMPORTANT resolution ceiling: With exact sign-flip enumeration, the smallest achievable p-value is 2/2^Nsubj for 2sided and bisided, and 1/2^Nsubj for 1sided. Bisided counts one tail and doubles it, so it shares the 2sided ceiling. Exact two-sample contrast resolution is likewise limited by the number of fixed-size assignments: choose(NA+NB,NA). With -mode random the floor is 1/(niter+1) instead, so the default -niter 10000 puts it at 1e-04 no matter how many subjects there are. Choosing exact versus random: Exact enumeration stores one number per relabeling in an int-indexed array, so the count must fit in 2147483647. That caps sign-flip tests at 30 subjects, and a balanced two-sample contrast near 33 datasets in total. Run time doubles with every subject added as well, so exact mode stops being practical long before the cap, at roughly N=18. Very little is lost by that. Exact mode earns its cost at SMALL N, where so few relabelings exist that the floor above genuinely constrains what can be reported: at N=6 that floor is 0.031, at N=10 it is 0.002. By N=15 there are 32768 sign patterns and a floor of 6e-05, already finer than -niter 10000 delivers, and both sit far below any threshold anyone applies. Past that point exact enumeration buys resolution that will never be used, at exponentially growing cost. Random sampling is statistically sound at every N, so use it whenever exact mode is slow. 3dShuffle warns when an exact run is large enough that random is the better choice, and falls back to random on its own when no -mode was given and the enumeration cannot be represented. The reverse also happens: if -niter is at least the total number of relabelings, the run switches to exact. Drawing 10000 samples from a group of 256 revisits some and misses others, so it costs 39 times as much as enumerating them and returns a noisier p-value. That switch is decided once for the whole run, and it compares -niter against the LARGEST relabeling count among the tests being computed. When one design mixes very different group sizes, a small test can therefore stay random even though -niter would have covered its relabelings many times over, because some other test in the same run needs the sampling. Those p-values are still valid -- sampled rather than enumerated. Run a test on its own if you want it enumerated exactly. Author: P. Molfese, August 2026 ========================================================================= * This binary version of 3dShuffle is NOT compiled using OpenMP, a semi-automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * However, the source code is compatible with OpenMP, and can be compiled with an OpenMP-capable compiler, such as gcc 8.x+, Intel's icc, and Oracle Developer Studio. * If you wish to compile this program with OpenMP, see the man page for your C compiler, and (if needed) consult the AFNI message board, and https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * However, it would probably be simplest to download a pre-compiled AFNI binary set that uses OpenMP! https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/index.html ++ Compile date = Aug 25 2026 {AFNI_26.2.05:linux_ubuntu_24_64}