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}
