AFNI program: 3dShuffle

Output of -help

++ 3dShuffle: AFNI version=AFNI_26.2.05 (Aug 25 2026) [64-bit]
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}
This page auto-generated on Tue Aug 25 06:16:21 PM EDT 2026