AFNI program: 3dSRM

Output of -help


++ 3dSRM: AFNI version=AFNI_26.3.12 (Nov 17 2026) [64-bit]
++ Authored by: P Molfese

Usage: 3dSRM [options]                                         ~1~

Fit a Shared Response Model (SRM; Chen et al., NIPS 2015) to time-locked
data from several subjects, and measure how well it generalizes.

Each subject i contributes a matrix X_i (features x time). SRM learns one
shared response S (k x time) and, for each subject, a mapping W_i
(features x k, orthonormal columns) so that

      X_i  ~=  W_i S  +  noise

The subjects need not have the same number or arrangement of features.
Subject i's voxels (or EEG channels) are read out into the same k-dimensional
space, so no voxel-to-voxel correspondence across subjects is required.
Only the columns must correspond. The columns can be time points of a
stimulus every subject experienced at the same time (a movie, a story), or
items (trial or condition betas) matched across subjects by a label, which
is the right choice when trial order was randomized. See -axis. SRM is
meaningless for resting-state data.

Typical uses:
  * Subject-wise k x time series in a common space (the 'projected' output)
    for 3dRSA, 3dInSync, decoding, or a group t-test of a held-out score.
  * Dimension reduction that emphasizes shared responses. Noise can remain,
    and task-specific or individual differences can be lost.
  * Placing new subjects into an existing space, now or months later, from a
    saved model and without the original subjects' data (see -model_in).

Required input:                                             ~1~

  -dataTable @TABLE
  -dataTableFile TABLE
  -dataTable Subj Group InputFile s01 control s01_movie+tlrc ...

      TABLE needs Subj and InputFile columns, plus optional columns:
        Run    : with one row per Subj x Run, each subject's runs are
                 concatenated in time in the order the runs first appear.
                 Every subject must have the same set of runs, each of the
                 same length. See -run_column.
        Item   : item label, with -axis item. See -item_column.
        Xmat   : the subject's X.xmat.1D (from afni_proc.py or 3dDeconvolve),
                 when one InputFile holds all of the subject's runs, such as
                 afni_proc.py's errts. Its RunStart splits the input into
                 runs, and its NRowFull must equal the input's length. See
                 -concat. With -axis item it gives the items instead: see
                 'Items from afni_proc.py output' below. Either way each
                 subject's Xmat is summarized in numeric columns that
                 travel to scores.txt as covariates: Xmat.TR, Xmat.nrun,
                 Xmat.ntime, Xmat.ncensored, Xmat.frac_censored, Xmat.nstim.
        Censor : the subject's censor file (1 keep, 0 censored), covering all
                 of that subject's runs. See -cenmode.
        Mask   : a mask dataset for that subject, on that subject's own
                 grid. Subjects may then have different voxel counts and
                 different grids. A subject's Mask must be the same on all
                 their rows.
        Group  : subject group, used to label and compare scores. See
                 -group_column.
        others : any other column can be named in -score_by. Numeric
                 columns are carried to the output tables, so covariates
                 such as motion travel with the scores.

      InputFile is an AFNI dataset, or a .1D file. A .1D file is read as
      time x features (one row per time point, one column per channel or
      region), the usual AFNI orientation. Datasets and .1D files can be
      mixed in one table, which is how non-voxel data (EEG band power at TR
      resolution, parcel means) enter the same model. Every input must have
      the same number of time points.

  -nfeatures K[,K2,...]
                       Dimension k of the shared space. Required, except with
                       -model_in, which takes it from the model. K must not
                       exceed the smallest feature count or the number of
                       time points. Several values require -cv and produce a
                       comparison table (PREFIX.nfeat.txt) and no model
                       outputs; rerun with the chosen K for those.

Model options:                                              ~1~

  -prefix PREFIX       Output prefix [SRM].

  -algorithm ALG       prob : probabilistic SRM, fitted by EM [default].
                              Estimates a noise variance for every subject,
                              so noisier subjects (or noisier modalities)
                              count for less in S.
                       det  : deterministic SRM, alternating Procrustes
                              steps. Subjects are weighted by their feature
                              count and variance only.

  -niter N             Maximum iterations [500].
  -tol T               Stop when the relative change in the objective falls
                       below T [1e-7].

                       SRM converges slowly on real data, which is why the
                       defaults are generous. For 22 subjects hearing a story
                       (1000 voxels each, 15 components), the shared response
                       after 10 iterations, BrainIAK's default, differed from
                       the converged one by 38%, after 20 by 30%, after 100 by
                       15%, and after 200 by 4%. Full convergence (1e-13) took
                       about 550 iterations. -tol 1e-7 stops near 170 and
                       -tol 1e-8 near 250. A fit stopped earlier is not
                       wrong, only unconverged, and it depends on the seed.
                       Whether a converged or an earlier fit predicts held-out
                       data better is an empirical question: -cv answers it.
                       For a quick look, -niter 20 is enough.

  -seed S              Seed for the random starting W_i [1234567]. Until a fit
                       has converged, its subspaces depend on the seed.
                       Compare fits with rotation-invariant quantities, not
                       component by component.
  -nstart N            Fit from N different random starts and keep the one
                       with the best objective [1]. Starts run one after
                       another, so the cost is N times as much. The
                       objective of every start is in PREFIX.fit.txt: if they
                       agree to the tolerance you ran at, they found the same
                       optimum. If they differ by more, run longer first.
                       Only then is a difference evidence of a local optimum.
                       In tests, both models reached the same optimum from
                       every start on real data. One hard synthetic problem
                       (noise differing 6-fold between subjects) stalled the
                       deterministic model at a slightly worse stationary
                       point from one start, so N of 3 to 5 is cheap
                       insurance when the data are that uneven.

  -run_coupling L      shared : one W per subject for all of their runs
                                [default]
                       L >= 0 : a separate W for each subject and run, each
                                tied to a per-subject anchor W. The tie is a
                                prior worth L time points of data: L=0 fits
                                every run on its own, L equal to a run's
                                length weighs the anchor as much as that
                                run's data, and L much larger than the runs
                                is nearly 'shared'. Try values from about
                                0.2 to 2 times a typical run length. Requires
                                runs, and -axis time. The fit starts from the
                                shared-W fit (so it takes about twice as long),
                                and a very
                                large L stays close to it: use 'shared'
                                instead.

                                Runs not in the fit (held-out runs, new data)
                                use the anchor. See -cv_adapt. In-sample, a
                                smaller L always fits better, because a W per
                                run has more freedom; whether it generalizes
                                is what -cv shows. With L=0 the runs can fall
                                into different orientations of S.

Data options:                                               ~1~

  -mask MASK           A mask for every subject lacking a Mask column. All
                       such subjects then must share MASK's grid. Datasets
                       need a mask from one source or the other; .1D inputs
                       never do. Voxels with zero variance in any run (over
                       all samples, with -zscore all) are dropped for that
                       subject and counted in the log.

  -run_column NAME     Run column in the table [Run]. If absent, each subject
                       is a single run, unless -concat or an Xmat column
                       says where runs start inside each input.
  -concat SPEC         Run starts within each subject's one input, as in
                       3dDeconvolve and 3dTproject: the time-point index at
                       which each run begins, starting with 0, as a 1D file or
                       '1D: 0 300 600'. The same for every subject. For one
                       input per subject that holds several runs (afni_proc.py's
                       errts.SUBJ+tlrc, say); without it such an input is one
                       long run, so z-scoring and -cv would ignore the
                       boundaries. An Xmat column does the same per subject,
                       from RunStart (every subject must still have the same
                       runs). Not with a Run column.
  -group_column NAME   Group column in the table [Group]. Only used to label
                       the output tables.

  -zscore MODE         run  : z-score every feature separately within each run
                              before fitting [default with -axis time]
                       all  : z-score every feature over all of the subject's
                              samples together [default with -axis item:
                              betas from one GLM share a baseline]
                       none : use the data as given (it should already be
                              centered and scaled)

  -censor FILE         One common 0/1 vector with one value per input time
                       point. Retained time points are identical for all
                       subjects. Applied before z-scoring. -axis time only.
  -zcensor             Treat a subject's volumes that are all zero in the
                       mask as censored for that subject (afni_proc.py's errts
                       zeroes its censored volumes). -axis time only (an
                       all-zero item is always an error).

  Each subject's own censoring comes from any of: a Censor column (one 0/1
  file per subject, 1 = keep, covering all of the subject's runs in order,
  such as afni_proc.py's censor_SUBJ_combined_2.1D), the GoodList of an
  Xmat column, and -zcensor. What a censored time point becomes:

  -cenmode MODE        interp  : filled in, for that subject only, by linear
                                 interpolation between the nearest kept time
                                 points of the same run (the nearest one at a
                                 run's edge), as 3dTproject -cenmode NTRP.
                                 Everyone keeps every time point [default:
                                 every subject's projected series stays
                                 complete, ready for 3dInSync or 3dRSA].
                       drop    : the time point is dropped for EVERYONE. Each
                                 subject's censoring is then lost by all: 30
                                 subjects with 5% censored at random keep only
                                 about a fifth of the time points.
                       missing : that subject is left out at that time point
                                 only. The fit uses each subject where it was
                                 observed (deterministic: S at each time point
                                 is the mean of the subjects observed there;
                                 probabilistic: the posterior uses their
                                 precision only, and each subject's noise
                                 variance its own observed samples). Z-scoring
                                 is over observed samples. Scores use the
                                 samples where the subject, and someone else
                                 for the reference, were observed; segment
                                 matching skips windows that hold a missing
                                 sample. The more exact model, but PROJECTED
                                 series are 0 at a subject's missing time
                                 points. Each run needs at least
                                 3 observed time points per subject (and, with
                                 -run_coupling 0, k). With -run_coupling, each
                                 run's W uses its observed samples (the anchor
                                 fills in the rest). A saved model keeps how
                                 many subjects were observed at each time point,
                                 so -update_S adds new subjects (with or without
                                 missing points) correctly. -apply_W z-scores
                                 (or centers) the new data over observed samples
                                 and writes 0 at missing ones.
                       -censor (common to everyone) always drops. With
                       -model_in the model's timeline is fixed, so drop is an
                       error there.
  -zcensor_warn PCT    Warn for each subject with more than PCT percent of
                       its time points censored [20].

  3dSRM does not regress nuisance signals, filter, or change temporal
  alignment. Inputs should already be preprocessed and aligned to the
  stimulus. For EEG-derived inputs, the HRF and any lag must be handled
  before the data reach this program.

Time-locked or item-indexed:                                ~1~

  -axis time           Columns are the time points of a stimulus presented
                       identically to everyone [default]. With one row per
                       Subj x Run, runs are concatenated.
  -axis item           Columns are items. The table has one row per Subj x
                       Item, whose InputFile is a single volume (or a
                       sub-brick selector such as betas+tlrc'[7]' or
                       betas+tlrc'[face#0_Coef]'), or a .1D file with one
                       row. Every subject must have every item exactly once,
                       in any row order; items are matched by label, not
                       position. Missing, repeated, or extra items are errors
                       that name the Subj and Item. A dataset that holds many
                       items is read once per subject, however many rows
                       select from it. An item that is zero everywhere in the
                       mask (usually a failed or missing estimate) is an error.

  -item_column NAME    Item-label column [Item]. Labels may not contain ':'.

  Items from afni_proc.py output. A table with one row per subject, an Xmat
  column (the X.xmat.1D of the regression) and InputFile the stats bucket
  (stats.SUBJ+tlrc, or the REML one), and no Item column, is expanded to one
  item per stimulus column of the Xmat: a condition with one column is one
  item named by its label (house), and one with several columns gives an
  item per column, named as 3dDeconvolve names it (face#0, face#1, ...: the
  trials of -stim_times_IM, or the lags of a TENT basis). Each reads the
  bucket's LABEL#n_Coef volume. In a table file '#' starts a comment only at
  the start of a word, so face#0 and stats+tlrc[face#0_Coef] can be written
  as they are, or quoted as a whole ("face#0"). The new rows carry
  the subject's other columns (Group, Mask, covariates), a Condition column
  (the stimulus label, for -fold_column Condition: leave one condition out),
  and, when every item's regressor lies inside one run, a Run column, so -cv
  run works on trials. -show_table prints the expanded table. The Xmat knows
  each trial's condition and order, not which stimulus it was: trial items
  match across subjects only if everyone had the same order; otherwise list
  the items in the table yourself.
  LSS trial betas and explicit stimulus identities:
  -lss                With -axis item, InputFile is an existing 3dLSS output
                      dataset, Xmat is the design used by 3dLSS, and Events
                      names an event-to-item table. This reads LSS betas; it
                      does not run 3dLSS or fit a GLM to raw BOLD data.

  The subject table has Subj Xmat Events InputFile, plus optional subject
  metadata (Group, Mask, covariates). Each Events file has a header with:
    Trial Item [Condition Repeat Run other_metadata ...]
  Trial is the ZERO-BASED LSS volume index, not a TR, onset, original Xmat
  column, or one-based trial number. Map every volume exactly once. Rows and
  columns may be reordered; all Events files must have the same columns.
  Item is the actual shared stimulus identity, not its presentation order.
  -item_column and -repeat_column select alternative metadata column names.
  Repeated items need matching repeats across subjects, as described below.
  Condition, if wanted, comes from Events: one IM regressor family can hold
  several experimental categories. Additional columns can define folds or
  score groups. Subject and event column names must not overlap. All paths
  are relative to the working directory, not the table's directory.

  The Xmat must describe exactly one -stim_times_IM family, as for 3dLSS.
  Its IM column count and the dataset's ordered LABEL#000, LABEL#001, ...
  labels must agree. Use the original, unselected LSS dataset. Renamed or
  selected datasets can instead use the explicit item-table method below.
  -xmat_stims is not used with -lss. Xmat summary covariates are retained.
  If neither table supplies Run (or -run_column's name), it is inferred as
  1, 2, ... only when every IM regressor lies wholly in one run, accounting
  for GoodList censoring. Otherwise supply Run explicitly for run CV.
  For separate per-run LSS datasets, supply the actual Run on each subject
  row (or in Events); each separate Xmat otherwise starts its runs at 1.
  Use -zscore run for separate run fits. No censor vector is applied to
  beta volumes. Trial mappings must be complete; use an explicit item table
  to analyze a common subset, keeping the same item/repeat keys for everyone.

  New way (s01.events.txt and s02.events.txt can have different trial orders):
    # lss_subjects.txt
    Subj Xmat          Events          InputFile
    s01  s01.X.xmat.1D  s01.events.txt  s01.LSS+tlrc
    s02  s02.X.xmat.1D  s02.events.txt  s02.LSS+tlrc

    # s01.events.txt
    Trial Item      Condition
    0     face_017  face
    1     house_042 house

    # s02.events.txt
    Trial Item      Condition
    0     house_042 house
    1     face_017  face
    # ...one row per remaining trial in EACH file...

    3dSRM -axis item -lss -dataTableFile lss_subjects.txt -show_table
    3dSRM -prefix task -axis item -lss -nfeatures 5 -cv run \
          -mask roi_mask+tlrc -dataTableFile lss_subjects.txt

  Old way (still supported; no -lss, Xmat, or Events columns):
    # explicit_items.txt
    Subj Item      Condition Run InputFile
    s01  face_017  face      1   s01.LSS+tlrc[0]
    s01  house_042 house     1   s01.LSS+tlrc[1]
    s02  house_042 house     1   s02.LSS+tlrc[0]
    s02  face_017  face      1   s02.LSS+tlrc[1]
    # ...one row per remaining item/repeat for every subject...

    3dSRM -prefix task -axis item -nfeatures 5 -cv run \
          -mask roi_mask+tlrc -dataTableFile explicit_items.txt

  These commands assume a full table with multiple runs and enough training
  items/voxels for 5 features; the two displayed trials only illustrate the
  mapping. Use held-out runs/items to evaluate alignment. LSS estimates may
  mix neighboring trial responses, so run-wise validation is a useful start.
  Identical Item labels must mean the same stimulus across people; neither
  the Xmat nor matching LSS volume numbers establishes stimulus identity.

  -xmat_stims LIST     Comma list of the stimulus labels to use [all].
  -repeat_column NAME  Repeat-label column [Repeat], used if present: it names
                       an item's repeats (1, 2, ... or early, late).

  Normalization. Betas from one GLM over all runs (the usual afni_proc.py
  analysis, including trial-wise betas from -stim_times_IM) share one
  baseline, so the default, -zscore all, z-scores each feature over all of
  the subject's items together. With betas from a separate GLM per run, use
  -zscore run, which works over the items of each of the subject's own runs
  (and needs a Run column). Each run then needs at least 3 items, and
  z-scores over fewer than about 10 are noisy (a warning says so).

  Runs. A Run column orders repeats and can define the -cv folds. Subjects
  need not share runs: when trial order was randomized, an item may be in run
  2 for one subject and run 3 for another (the folds then come from
  -fold_column).

  Repeats. An item measured more than once (separate betas: trial-wise, or
  one per run) gives a column per repeat, keyed Item:1, Item:2, ... in run
  order (runs ordered as they first appear in the table, as with -axis time)
  and then table order, so two repeats in the same run are numbered by their
  rows. A Repeat column names them instead (Item:R; see -repeat_column),
  which does not depend on row order. The model is free to use the repeats,
  and they are what within-subject reliability is computed from (see
  -reliability within). Every subject must have the same repeats of each
  item.

  What changes with -axis item: runs are not concatenated in time, there is
  no temporal adjacency, so 'match' becomes item identification (the held-out
  item must be the best correlate of its own counterpart among all items;
  the correlation is across the k components, so it is weak when k is a
  handful: compare k values with -nfeatures a,b,c),
  and the folds of -cv are runs, or the levels of -fold_column. When those
  differ between subjects for an item (randomized run order), each subject's
  folds are its own: -cv loso fits the group without the subject on every
  item; -cv run refits everyone on every item with each subject's own
  held-out items missing for that subject only (see -cenmode missing).
  Options about time are errors with -axis item, each saying what to do
  instead: -censor, -zcensor, -cv_blocks, -match_window, -time_labels,
  -repeated_stimulus, and -run_coupling. The
  outputs list the item keys: in the header of PREFIX.S.1D (one row per item)
  and as the volume labels of PREFIX.proj.SUBJ.

  -fold_column NAME    The table column whose levels are the folds of -cv run
                       [Run]. Naming a category column gives
                       leave-one-category-out: the model must then generalize
                       to a kind of item it never saw, a stricter test.

  -time_labels NAME FILE
                       With -axis time, one numeric label per retained time
                       point (0 = unlabelled), to score by stimulus content
                       such as speech/no speech or scene type. NAME is the
                       factor name for -score_by. May be given repeatedly.
                       One label per input time point also works (then
                       censored ones are skipped).

  Condition from the Xmat. With an Xmat column on the time axis, -score_by
  Condition labels each time point with the stimulus whose regressor, scaled
  to its own peak, is largest there, if it reaches -xmat_label_frac of that
  peak [0.5]; other time points, and censored ones, are unlabelled. The
  regressors are already convolved, so the labels follow the BOLD response.
  -xmat_stims chooses the stimuli here too.
  -xmat_label_frac F   See above [0.5].

  Which one? If every subject saw the same stimuli in the same order, time
  mode uses the full time series. If trial order differed, only item mode is
  valid. Time mode cannot align subjects whose events are not simultaneous.

Mapping new subjects into a saved model:                   ~1~

  Every fit writes PREFIX.srm. It holds the shared response S, the noise
  variances, and exactly how the data were put on the model's timeline (the
  censored time points, the run lengths, and the z-scoring). It does not hold
  any subject's W_i or data, so it is small and can be passed between sites.
  It is plain text (about 1.2 MB for 30 components and 1310 time points),
  written to a temporary name and renamed, so an interrupted run never leaves
  half a model. The numbers are stored with enough digits to be read back
  exactly, and a model that is read and then updated gives exactly the result
  that updating the original would have. The format is described in thd_srm.h;
  keys and sections this version does not know are skipped, and a file from a
  newer version is refused with a message, not misread. A damaged or
  truncated file is reported as such.

  -model_in MODEL.srm  Do not fit S. Instead estimate a W for every subject in
                       the table, against the S in MODEL.srm. Each subject
                       needs the same stimulus and the same number of time
                       points and runs the model was built from; this is
                       checked first, and the data are censored and z-scored
                       as the model's were. Their feature counts, masks, and
                       grids can be anything with at least k features.

                       The model defines -nfeatures, -algorithm, -seed,
                       -run_coupling, -censor, -zcensor, and -zscore; giving
                       any of them with -model_in is an error, and so is
                       -niter or -tol unless -update_S is given (they then
                       control that update). -cv loso is also an error,
                       since there is no group fit to leave anyone out of.
                       -cv none or -cv run are allowed, and mean something
                       different here: see below.

                       A subject who is already in the model is a warning
                       (their scores are optimistic: S contains them), and an
                       error with -update_S. A model made with -run_coupling
                       places new subjects with one W for all their runs,
                       unless -update_S, which gives them a W per run.

                       A model fit with -axis item needs -axis item here too
                       (and a time-axis model needs it absent). Each new
                       subject must have exactly the model's item keys, in
                       any table order (Item, or Item:n for repeats, as the
                       fit made them; a mismatch names the first missing or
                       extra key). -cv run then holds out the levels of
                       -fold_column (or Run) and scores item identification.
                       Those levels may differ between subjects (randomized
                       runs): S is fixed, so each subject's own held-out
                       items are simply left out of their own W.

  A new subject's W is fitted to their own data, so its fit to that data is
  flattering by construction. Use -cv run with -model_in: W is then estimated
  from all of the subject's runs but one (or blocks but one), and the subject
  is scored on the part left out. The scores are
  analogous to -cv loso on the original subjects, but use the full reference
  group rather than a reference group with one subject removed.

  -update_S            ** EXPERIMENTAL **
                       Let S absorb the new subjects, and write a new
                       PREFIX.srm that includes them. Without this option the
                       saved model is untouched and S does not move.
                       It is an approximation to a refit (see below), and its
                       behavior and the model file's sums may change.

                       The model keeps running sums of its subjects' projected
                       data (weighted by their noise variances), so S can be
                       updated from the new subjects alone, with no access to
                       the original data. This is the point of the model file:
                       a site can add its subjects to a shared model without
                       receiving or sending any subject's data.

                       What it is, and is not. The old subjects' W stay as
                       they were fitted; only S and the new subjects' W move.
                       That is an approximation to refitting everyone. The
                       subjects added together in one run are treated jointly,
                       so their order within the table cannot matter; subjects
                       added in different runs can matter, slightly (S differed
                       by about 3% between arrival orders in tests).

                       What it costs, measured on 22 subjects hearing a story
                       (30 components, fit on two runs, scored on a third by
                       the correlation of each subject's projected data with the
                       shared response from everyone else). Adding 1, 3, and 6
                       subjects to 21, 19, and 16 gave a drift of 0.003, 0.015,
                       and 0.038. Against refitting everyone from scratch, the
                       EXISTING subjects' scores were lower by 1.6%, 1.2%, and
                       5.0% (their W had not been refitted); the added subjects'
                       scores were no lower. Updating S brought it 16-25% closer
                       to the refit S than leaving it frozen, but did not raise
                       held-out scores above those of simply mapping the new
                       subjects into the frozen S. So the update keeps the
                       model's S current and the model growing; it is not a
                       substitute for a refit. The loss was 1-2% up to adding
                       about a sixth of the original subjects and 5% at a third,
                       so refit from the data when drift reaches a few percent.
                       These are one data set and one split: differences of
                       0.001 score of 0.13 are within noise.

                       The gauge of S is never changed by an update, so the
                       components and the projected series of earlier
                       analyses stay valid. Scores for the new subjects are
                       always computed BEFORE the update, from the model they
                       were not part of (-cv with -model_in).

                       The model file contains sums over subjects of
                       projected data. With only a few subjects those sums are
                       not anonymous, so treat a model built from fewer than
                       about five as if it contained their data.

                       An updated model is written to PREFIX.srm; it will not
                       overwrite the -model_in file unless it is the same name
                       and -overwrite is given.

  Without -update_S, adding subjects never changes old results.

Applying a subject's W to other data from the same subject: ~1~

  To keep task labels out of alignment fitting and model selection, learn W
  on independent data, then apply each subject's W to their task data. The
  retained dimensions must capture information useful for the new task;
  success on the alignment stimulus alone does not establish that transfer.

  -apply_W PREFIX      Use the W datasets from an earlier -save_W run (the
                       PREFIX.W.SUBJ datasets and PREFIX.srm). For each table
                       subject, find their W, take the new InputFile data on
                       W's own grid and voxels (no mask needed or accepted),
                       z-score as the model did, and write the data in the
                       shared space (PREFIX.proj.SUBJ). The new data may have
                       any length, order, and -axis; nothing is fitted. A
                       subject in the table but not in the model is an error.
                       Subjects may differ in length from one another. A
                       feature with no variance in a run of the new data is
                       zeroed. With -zscore none in the earlier run, each
                       feature is centered on the new data, since the means
                       of the old data are not saved. -mask, -cv and -save_W
                       are errors here.

                       With -axis item, each subject is read from their own
                       rows, so subjects may have different items (a dropped
                       trial, randomized stimuli); each needs at least 3. The
                       projection's volumes (or the 1D header) carry the
                       item keys. If the model z-scored within runs and the
                       table has no Run column, the items are z-scored over
                       all of the subject's items instead, and this is said.

                       The projected series of different subjects can then go
                       to 3dRSA, 3dInSync, or a classifier. Independent fitting
                       avoids fitting the tested task labels, but normalization,
                       dimension reduction and the alignment sample still
                       affect the result. Test transfer on held-out task data.

                       Requires that the earlier run used -save_W.

Validation:                                                 ~1~

  An SRM fits every subject's data with nfeatures x voxels free parameters.
  Anything measured on the data it was fit to is optimistic. These options
  evaluate on data the fit never saw.

  -cv MODE             none : fit once to everything. Reported scores are
                              in-sample and are labelled as such [default].
                       run  : leave one run out. For each run, fit on the
                              other runs, then score every subject on the
                              held-out run (or -cv_blocks block). With
                              -model_in, S is fixed, and only each subject's
                              own W is refitted without the held-out run.
                       loso : leave one subject out. For each subject, fit S
                              on all OTHER subjects and every time point.
                              Then estimate that subject's W from their own
                              training runs and score them on a held-out run.
                              With cold starts, their held-out data touch
                              neither S nor any fitted W used for scoring, so
                              the score is a clean estimate of how well a new
                              person maps into an existing space. Folds
                              within the subject are leave-one-run-out, or
                              -cv_blocks contiguous blocks if there is one run.
                              Uses independent cold starts by default; costs
                              one full group fit per subject (-niter, -tol,
                              -nstart). Written projections are aligned to the
                              pooled fit AFTER scoring; this output alignment
                              itself depends on all subjects.

  -cv_blocks B         Contiguous time blocks used as folds in place of runs
                       when the data have a single run [2]. Time points near a
                       block edge are autocorrelated with the other side, so
                       scores are a little optimistic; separate runs are
                       better.
  -loso_start MODE     cold [default]: fit each leave-out model independently
                       on the other subjects, using -niter, -tol and -nstart.
                       Score in each leave-out model's own canonical basis.
                       legacy: reproduce the old full-model warm start, with
                       -loso_iter steps. WARNING: that start already contains
                       the held-out subject's influence and can inflate scores.
                       Requires -cv loso in fit mode (time or item axis).
  -loso_iter M         Iterations for -loso_start legacy only [5]. Ignored for
                       cold starts. More legacy iterations do not guarantee
                       independence from the held-out subject.

  -cv_metrics LIST     Comma list from: isc, match, r2 [all three].
                       isc   : correlation of the subject's projected held-out
                               data with the shared response estimated from the
                               other subjects, per component, and their mean
                               in Fisher-z space (returned as r).
                       match : time-segment matching accuracy (Chen et al.),
                               as in BrainIAK's SRM example. Each window of
                               -match_window TRs of the subject's projected
                               data is matched to the best-correlated window
                               of the others' shared response, among its own
                               counterpart and every window that does not
                               overlap it. With -axis item it becomes item
                               identification: each held-out item must be the
                               best correlate of its own counterpart among
                               all items. Chance is reported alongside.
                       r2    : fraction of the subject's held-out variance
                               reconstructed from W_i and that shared
                               response. On voxel data this is usually tiny
                               or slightly negative, because variance that is
                               specific to a subject dominates (about -0.001
                               for 5000 voxels of story data, where segment
                               matching reached 12% against 0.3% chance).
                               Use it to compare methods or settings on the
                               same data, not as a measure of fit; isc and
                               match are the informative scores.
  -match_window N      Segment length in TRs for 'match' [9].

  -cv_adapt FRAC       With -run_coupling L and -cv: the held-out run has no W
                       of its own, so it uses the anchor. FRAC in (0,1) instead
                       estimates that run's W from its first FRAC of samples,
                       tied to the anchor with the same L, and scores only the
                       rest. The samples used to estimate W are never scored.
                       isc, match, and r2 are then the run W's scores, and
                       isc_anchor, match_anchor, and r2_anchor beside them are
                       the anchor's on the same samples, so the comparison
                       shows whether a run-specific W helps.
                       The S of those first samples: with -cv loso, the group
                       fit's (it saw the run); with -cv run, the mean of every
                       subject's anchor projection of them, and every subject
                       gets a run W, so each is scored against the others'
                       run-W projections (and the anchor scores against the
                       others' anchors). PREFIX.proj stays the anchor's.
                       With -cv_fit and -balance both columns are averaged
                       over the fits that scored the subject, and under
                       -cv_fit reference the other groups' subjects (placed
                       in the reference fit's S) adapt as -cv loso does [0:
                       off].

Reliability, and comparing groups or conditions:            ~1~

  A low score for a group or a condition has three possible causes: its
  signal is unreliable, its signal is reliable but not shared with the others,
  or the model was built mostly from someone else. These options separate
  them.

  -score_by NAMES      Comma list of table columns (or -time_labels names)
                       whose levels define subsets of the columns. Every
                       -cv metric is computed separately for each level, for
                       every subject, so you get faces vs houses within each
                       subject and then within each group. The model is
                       still fitted to all samples. Needs -cv.
                       Where the levels come from:
                         -axis item: a table column (Category, or Condition
                           from an Xmat table), read on each subject's rows.
                         -axis time: a -time_labels NAME; Condition, from
                           each subject's Xmat (below); or a table column,
                           its value on each run's row (Run itself, say).
                       Within a level, isc and r2 use the subject's held-out
                       samples of that level, and matching is among them only:
                       windows that lie wholly inside the level, or the
                       level's items. Chance is reported for each level.
                       Per-subject columns (Group, covariates) are not
                       levels: scores.txt carries them already.

  -cv_fit MODE         How the -cv models are fit (the written model, S and the
                       maps, is always the fit to everyone):
                       pooled    : one model from everyone [default]
                       within    : one model per Group, fit only to that
                                   group, with -cv run or loso inside it.
                                   Asks: does this group have a shared
                                   response at all?
                       reference:LABEL
                                 : fit on group LABEL only, then place the
                                   other groups' subjects in that model (with
                                   their W estimated from their own training
                                   folds). Asks: do they use the reference
                                   group's space? Reference subjects are scored
                                   leave-one-subject-out, the others as new
                                   subjects. Reference members use N-1 training
                                   subjects; outside members use N. Both exclude
                                   the scored subject with cold starts, but the
                                   training sample sizes still differ.
                                   Needs -cv loso.
                       Held-out projections are rotated into the gauge of the
                       fit to everyone, so all subjects' stay comparable.
  -balance B           Groups of unequal size bias scores: a model built from
                       40 people maps its members better than one built from
                       12. With -balance, every group fit is repeated on B
                       random subsets the size of the smallest group (with
                       -cv_fit pooled: B subsets with that many from every
                       group), and each subject's scores are averaged over the
                       fits that scored it [off]. A group that is already the
                       smallest is fitted once. -seed sets the draws, which are
                       listed in PREFIX.balance.txt. A subject no subset drew
                       gets NA (a warning says so: raise B). With -balance the
                       projected outputs are the full fit's, in-sample: each
                       subject was scored by several models.

  -reliability LIST    Comma list from: within, split.
                       within : a subject's own reliability, computed from
                                repeats of the same stimulus (the same Item in
                                different runs; or with -axis time and
                                -repeated_stimulus, the runs). It is the
                                correlation of the two halves' patterns
                                (r_pattern across voxels, r_series across
                                time or items), with the Spearman-Brown
                                correction, in the subject's own voxel space
                                with no model involved. It bounds what the
                                shared-space score can reach. The halves are
                                the odd and the even repeats (or runs),
                                averaged; r_pattern needs 2 repeated items (or
                                time points), r_series 3. Per -score_by level
                                too (an item counts in its first repeat's
                                level). Needs -cv: it goes into scores.txt
                                (rel_pattern, rel_series, and rel_ratio =
                                isc / rel_pattern).
                       split  : group-level. Randomly split each group's
                                subjects in two, fit S to each half, and
                                compare them with a rotation-invariant
                                subspace similarity. A group with no stable
                                shared response gives halves that disagree.
                                The similarity is the mean cos^2 of the
                                principal angles between the two S (1 = the
                                same space). Halves are half the group
                                (rounded down) against the rest; a group needs
                                4 subjects. PREFIX.reliability.txt summarizes,
                                PREFIX.reliability_splits.txt lists each
                                split. Does not need -cv.
  -nsplit N            Number of random splits for 'split' [100]. Each is two
                       group fits, warm-started from the full fit.
  -repeated_stimulus   With -axis time: every run shows the same stimulus. The
                       runs are averaged for the fit (after z-scoring each), and
                       their agreement (odd runs against even runs) gives
                       'within'. The runs must keep the same time points. The
                       fit then has one run, so -cv uses -cv_blocks, and the
                       saved model describes the averaged run. With
                       -cenmode missing, each time point is averaged over the
                       runs where the subject was observed (missing only if
                       missing in every run), and 'within' uses the time
                       points both halves observed. With -score_by, the
                       levels are read on the runs before averaging and must
                       agree in every repeat (so Run itself is an error);
                       -time_labels may then also give one label per time
                       point of the stimulus. Not with -run_coupling (there
                       is no run left to have its own W).

  How to read them together (all subjects scored on held-out data):
    low within, low shared  : the group or condition is simply noisy.
    high within, low shared : each person is reliable but they do not
                              share a response, or the model does not
                              speak their language. Compare -cv_fit within
                              against reference.
    high within, high shared: SRM works for them.
  'Within' needs real repeats. Without them it is not estimated, and a low
  score cannot be attributed.

  -nperm P             Test group and condition differences in the scores by
                       permutation, written to PREFIX.tests.txt [0 = none]:
                         two groups : group labels permuted over subjects
                         two levels of a -score_by factor : level labels
                                      swapped within each subject
                         both : the group x level interaction, by permuting
                                the within-subject differences between groups
                       P must be at least 20. -seed applies. Subjects are the
                       exchangeable units; the folds of one subject are never
                       split. Every score is tested (isc, match or ident, r2;
                       overall and per level for the group test), with Welch's
                       t for groups and a one-sample t for differences; p is
                       two-sided, and p_fwe is family-wise over the rows of one
                       test (max-statistic). When the relabelings number P or
                       fewer, all of them are used (exact). For anything more
                       elaborate (covariates, three groups) take
                       PREFIX.scores.txt to R.

Outputs:                                                    ~1~

  PREFIX.srm           The saved model (see above). With -model_in no new model
                       is written.
  PREFIX.S.1D          Shared response, time x k (one column per component).
                       Components are ordered by variance and sign-fixed, so
                       repeated fits are comparable up to noise.
  PREFIX.rho2.1D       Noise variance per subject (-algorithm prob).
  PREFIX.objective.1D  Objective per iteration. For prob it is the marginal
                       log-likelihood and rises; for det it is the summed
                       squared error and falls.
  PREFIX.fit.txt       One row per subject: features used, features dropped,
                       rho2, and the log of any censoring. With -update_S it
                       also gives the model's drift and number of updates.
  PREFIX.coupling.txt  With -run_coupling L: per subject and run, how far that
                       run's W is from the anchor (0 = identical, 2 =
                       orthogonal, as |W_ir - W_i|^2 / nfeatures) and the
                       gain in reconstruction R^2 over the anchor in the fit
                       data. Large deviations show where the subject's
                       mapping really moved.

  Unless -no_projected:
  PREFIX.proj.SUBJ     Each subject's data in the shared space, W_i' X_i.
                       With -cv run or loso these are the held-out
                       projections concatenated across folds; with -cv none
                       they are in-sample.
  -proj_format FMT     dset : a dataset with k x 1 x 1 voxels and one volume
                              per time point, directly usable as input by
                              3dInSync (per-component ISC) and 3dRSA [default]
                       1D   : time x k text file

  With -cv run or loso:
  PREFIX.scores.txt    One row per Subj x level of each -score_by factor (and
                       'all'), averaged over folds. Columns: Subj, Group,
                       Factor, Level, nsamp, isc, match (or ident), r2, and
                       with -reliability within: rel_pattern, rel_series, and
                       the ratio of the shared score to rel_pattern. Numeric
                       table columns are carried along. One score per subject
                       per condition is the right input for a group
                       comparison.
  PREFIX.scores_folds.txt
                       The same, one row per Subj x fold (x -score_by level,
                       with Factor and Level columns as in scores.txt).
  PREFIX.balance.txt   With -balance: the subjects of every fit.
  PREFIX.reliability.txt
                       With -reliability split: per Group, the subspace
                       similarity of the two halves over the splits (mean,
                       and 2.5 and 97.5 percentiles).
  PREFIX.reliability_splits.txt
                       With -reliability split: each split's two halves and
                       their similarity.
  PREFIX.tests.txt     With -nperm: the tests above, one row per score: Test,
                       Factor, Score, Contrast, N1, N2, effect, t, p, p_fwe,
                       nperm, exact.

  Optional, since they are large:
  -save_W              PREFIX.W.SUBJ: k volumes per subject, on that subject's
                       grid. These are the spatial maps of the components.
                       A .1D subject gets one row per column of the input;
                       the rows of dropped (constant) features are zero.
  -save_recon          PREFIX.recon.SUBJ: W_i S, the denoised reconstruction of
                       the subject's time series.
  -save_r2             PREFIX.r2.SUBJ: voxelwise reconstruction R^2 for each
                       subject (held-out under -cv). Maps on a common grid
                       can go to 3dttest++.

Resources:                                                  ~1~

  -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.
  -no_compress         Hold every subject's data whole (voxels x T), as
                       before -compress became the default. The results are
                       the same up to rounding; it needs far more memory.
  -compress            [the default when every subject has more features
                       than time points (or items), outside -model_in and
                       -apply_W; given explicitly, it is used regardless]
                       Hold each subject as an exact T x T (at most) factor
                       R of its prepared data X, with R'R = X'X (its Gram
                       matrix: see below), instead of
                       voxels x T. Everything the fit and -cv do with X goes
                       through X'X, and W always lies in the span of X, so
                       S, the scores, the projections, rho2 and the model
                       are those of -no_compress, up to rounding (about
                       1e-7; the fit starts where the uncompressed one would).
                       Subjects are read, censored, z-scored and compressed
                       one at a time, so the data are never all in memory:
                       for whole-brain naturalistic data this is the
                       difference between tens of GB and a few. -save_W and
                       -save_recon read each subject again at the end (W on
                       the voxels is X M, M small). With -nstart > 1 only
                       the first start is the uncompressed one's, so the
                       best of several starts can differ from -no_compress.
                       -save_r2 notes each scored fold's W and reference
                       and makes the voxelwise R^2 when the subject is read
                       again. Item reliability (-reliability within) is made
                       from each subject's voxels before they are
                       compressed. -cenmode drop with -zcensor reads every
                       subject once more first, to find the zero volumes.
                       Not with -model_in or -apply_W (they hold only the
                       new subjects).
                       Saves memory when subjects have more features than
                       time points (or items).
  -progress M          auto, bar, line, or off [auto].
  -quiet               Suppress progress and informational diagnostics.
  -show_table          Print the parsed table and exit.

  Memory, compressed (the default when subjects have more features than time
  points): one subject's data while it is read, plus one input on its full
  grid as floats, plus each subject's factor (at most T x T x 4 bytes).
  With -no_compress: the sum over subjects of voxels x time x 4 bytes, plus
  voxels x k x 4 bytes per subject for W, plus the larger of the copies -cv
  run makes of the largest fold (about (T - shortest run + longest run) / T
  of the data; -cv loso and -model_in copy one subject at a time) and one
  input being read. The estimate is printed when it is over half of
  physical memory, or whenever -memory_limit is given. For example, 22
  subjects, 161k voxels, three runs (526, 452, 332 TRs), k = 50, -cv run:
  3.7 GiB and 3.9 min by default; 38.0 GiB and 6.6 min with -no_compress.
  Most of the time goes to reading, and then to matrix products, run
  subject-parallel under OpenMP.

  A Gram matrix is X'X for data X (voxels x time points): entry (s,t) is the
  dot product of the brain patterns at time points s and t, summed over
  voxels, so it is T x T however many voxels there are.
  When every subject has at least T+k voxels (T time points), the fit forms
  each subject's (T+k) x (T+k) Gram matrix once and iterates on that, so an
  iteration costs about (T+k) x T x k per subject instead of voxels x T x k,
  and W is formed from the data at the end. This adds (T+k)^2 x 8 bytes per
  subject. The fit is the same either way, up to rounding. Setting
  AFNI_SRM_KERNEL to VOXEL or GRAM forces one path (for testing).

Examples:                                                   ~1~

  Replace the sample dataset names below with your own inputs. Inline
  -dataTable entries go last in the command; keep the trailing backslashes
  on every line except the last row. For -dataTableFile, save the displayed
  header and rows as plain text, without backslashes or shell quotes.
  Time-series examples assume synchronized movie runs, with enough time
  points and retained voxels for the requested number of features, including
  in each training fold. These illustrate commands, not guaranteed biological
  results. Numerical checks and held-out scores on the alignment stimulus
  do not establish cross-task transfer or anatomical localization.

  Example 1: Fit, with held-out run scores

  3dSRM -prefix movie_srm -nfeatures 50 -cv run \
        -mask brain+tlrc \
        -dataTable Subj Group   Run InputFile \
                   s01 control r1  s01_r1+tlrc \
                   s01 control r2  s01_r2+tlrc \
                   s02 control r1  s02_r1+tlrc \
                   s02 control r2  s02_r2+tlrc

  This writes movie_srm.srm for Examples 3 and 6. Example 8 shows how to
  choose the number of features before fitting a final model.

  Example 2: Native-space responses projected into shared features

  3dSRM -prefix native_srm -nfeatures 30 -cv loso \
        -dataTableFile native.txt

  Choose a mask for each subject that includes the system you want to study,
  independently of the held-out effects. Grids and voxel counts may differ
  across people. Within a person, their runs and mask must already be aligned
  to the same anatomy and grid; the +orig suffix alone does not ensure this.

  Contents of native.txt (at least 3 subjects for leave-one-subject-out):
    Subj Run Mask          InputFile
    s01  r1  s01_mask+orig s01_r1+orig
    s01  r2  s01_mask+orig s01_r2+orig
    s02  r1  s02_mask+orig s02_r1+orig
    s02  r2  s02_mask+orig s02_r2+orig
    s03  r1  s03_mask+orig s03_r1+orig
    s03  r2  s03_mask+orig s03_r2+orig

  SRM learns weighted combinations of these voxels from corresponding movie
  responses. It does not label FFA, estimate a spatial warp, or move activity
  to matching anatomical coordinates. Output locations index shared
  components; they are not a brain grid for voxelwise cluster inference.

  Example 3: Place new subjects in the model from Example 1 and score them

  The new subjects must have experienced the same movie runs, with the same
  time-point correspondence as in Example 1.

  3dSRM -prefix new_subj -model_in movie_srm.srm -cv run \
        -mask brain+tlrc \
        -dataTable Subj Run InputFile \
                   s03 r1  s03_r1+tlrc \
                   s03 r2  s03_r2+tlrc \
                   s04 r1  s04_r1+tlrc \
                   s04 r2  s04_r2+tlrc

  Example 4: Item-indexed betas, scored by category, controls as reference

  3dSRM -prefix faces -axis item -nfeatures 20 -cv loso \
        -mask brain+tlrc -score_by Category -cv_fit reference:control \
        -balance 50 -nperm 5000 \
        -dataTableFile betas.txt

  Sample rows from betas.txt:
    Subj Group   Item      Category Run InputFile
    s01  control face_017  face     r1  s01_betas_r1+tlrc[0]
    s01  control face_023  face     r1  s01_betas_r1+tlrc[1]
    s01  control house_042 house    r1  s01_betas_r1+tlrc[2]
    s01  control face_017  face     r2  s01_betas_r2+tlrc[0]
    s01  control face_023  face     r2  s01_betas_r2+tlrc[1]
    s01  control house_042 house    r2  s01_betas_r2+tlrc[2]
    s05  patient house_042 house    r1  s05_betas_r1+tlrc[0]
    s05  patient face_017  face     r1  s05_betas_r1+tlrc[1]
    s05  patient face_023  face     r1  s05_betas_r1+tlrc[2]
    s05  patient face_023  face     r2  s05_betas_r2+tlrc[0]
    s05  patient house_042 house    r2  s05_betas_r2+tlrc[1]
    s05  patient face_017  face     r2  s05_betas_r2+tlrc[2]

  These are excerpts: include all subjects and items in the actual file.
  Use at least 3 control subjects for LOSO, enough subjects for the group
  comparison, and enough training items and voxels for 20 features.
  Item labels match stimuli across subjects even when volume order differs.
  The reference-group comparison requires -cv loso. These are comparisons
  of held-out alignment scores, not voxelwise face-minus-house activation
  tests. Controls use N-1 reference subjects, patients use all N. Balancing
  group sizes does not remove this training-size difference.
  For separate GLMs per run, add -zscore run (at least 3 items in each run).

  Example 5: Test whether movie-derived features transfer to a visual task

  Use independent visual/movie data from the same subjects and masks that
  cover the visual system of interest. The common ventral_temporal mask
  below assumes anatomically aligned inputs; for native-space inputs use
  per-subject masks as in Example 2. A story fit in an auditory mask does
  not establish a useful alignment for a face/house task.

  Fit the movie runs with -save_W, using a new prefix:

  3dSRM -prefix movie -nfeatures 50 -save_W -mask ventral_temporal+tlrc \
        -dataTable Subj Run InputFile \
                   s01 r1  s01_r1+tlrc \
                   s01 r2  s01_r2+tlrc \
                   s02 r1  s02_r1+tlrc \
                   s02 r2  s02_r2+tlrc

  Register each subject's task data to their movie data before estimating
  or resampling the betas. Matching grid headers is necessary but does not
  establish anatomical alignment. Apply W to the corresponding voxels.
  Quote selectors in an inline table so the shell passes the brackets.
  The rows below are excerpts: add the remaining trials and subjects.

  3dSRM -prefix task -axis item -apply_W movie \
        -dataTable Subj Item      InputFile \
                   s01 face_017  's01_task+tlrc[0]' \
                   s01 face_023  's01_task+tlrc[1]' \
                   s01 house_042 's01_task+tlrc[2]' \
                   s02 house_042 's02_task+tlrc[0]' \
                   s02 face_017  's02_task+tlrc[1]' \
                   s02 face_023  's02_task+tlrc[2]'

  Each output trial is a K-component vector, W_i' times that subject's
  prepared voxel pattern. No task mapping is fitted and no anatomical
  activation map is relocated. The saved normalization is applied to the
  NEW betas: here, with no Run column, each voxel is z-scored across items.
  These features do not retain the original beta amplitude units. With
  -zscore none in the saved fit, application still centers the new data.

  Evaluate cross-subject classification or RSA on independent task data,
  keeping test labels out of alignment/mask/K selection. Compare against
  anatomical alignment and a dimension-matched baseline. Good movie scores
  alone do not show that face/house information transfers. For claims about
  FFA location or activation amplitude, use an independent localizer and
  evaluate that anatomical/amplitude question explicitly.

  Example 6: Add another site's subjects to the model from Example 1

  As in Example 3, these subjects saw the same movie runs. -update_S updates
  the shared response using the new subjects; the original data stay local.
  This is an approximate update with the old W fixed. Here -cv run scores
  new subjects against the pre-update S; it does not validate the updated S.

  3dSRM -prefix movie_v2 -model_in movie_srm.srm -update_S -cv run \
        -mask brain+tlrc \
        -dataTable Subj Run InputFile \
                   s05 r1  s05_r1+tlrc \
                   s05 r2  s05_r2+tlrc \
                   s06 r1  s06_r1+tlrc \
                   s06 r2  s06_r2+tlrc

  Example 7: Allow each run its own W, tied to the subject's anchor

  Supply at least THREE synchronized runs per subject: each run-CV fit
  needs two remaining runs for run-specific W. Compare with a shared-W fit
  on the same three-run table. Adaptation uses the first quarter of the
  held-out run; adapted and unadapted scores both use the remaining samples.
  With K=50 and -cv_adapt 0.25, each run needs at least 200 retained samples
  before any subject-specific missing samples in the adaptation portion.

  3dSRM -prefix movie_rc -nfeatures 50 -run_coupling 200 -cv run \
        -cv_adapt 0.25 -mask brain+tlrc \
        -dataTable Subj Group   Run InputFile \
                   s01 control r1  s01_r1+tlrc \
                   s01 control r2  s01_r2+tlrc \
                   s01 control r3  s01_r3+tlrc \
                   s02 control r1  s02_r1+tlrc \
                   s02 control r2  s02_r2+tlrc \
                   s02 control r3  s02_r3+tlrc

  Example 8: Choose k using held-out scores

  Save the table from Example 1 as subjects.txt to reuse it across commands:
    Subj Group   Run InputFile
    s01  control r1  s01_r1+tlrc
    s01  control r2  s01_r2+tlrc
    s02  control r1  s02_r1+tlrc
    s02  control r2  s02_r2+tlrc

  3dSRM -prefix scan -nfeatures 10,20,30,50,80 -cv run \
        -mask brain+tlrc -dataTableFile subjects.txt

  Inspect scan.nfeat.txt, then rerun Example 1 with the chosen -nfeatures
  value and a fresh prefix to write the model and projected data. Those
  scores were used for model selection; evaluate the chosen setting on an
  additional independent split for a final predictive claim.

Reading the results:                                        ~1~

  * Components are coordinates in a learned representation, not named brain
    regions. Do not match component numbers across independently fitted
    models or interpret component locations as anatomical coordinates.
  * Reconstruction R^2 is invariant to a consistent orthogonal rotation.
    Component-wise ISC is not; do not assume all scores are rotation-invariant.
    The default cold LOSO fits use their own canonical basis for scoring.
  * Under default -cv loso, the group reference excludes the scored subject.
    -loso_start legacy does not provide that independence. Training sample
    size, noise and convergence still matter for group comparisons.
    -cv run evaluates held-out runs of subjects included in training.
  * To compare groups, use -cv_fit and -balance. A pooled model is built more
    from the larger or less noisy group and maps that group better, with
    nothing to do with the groups differing in function.
  * The model fits samples in proportion to their variance, so a condition
    with a large response can dominate and a weak one be fitted poorly even
    in everyone. Score by condition, and check that a weak condition is weak
    in 'within' too before reading it as a failure of SRM.
  * If you will RSA the aligned task data, align on other data (-apply_W),
    or score with held-out folds. SRM maximizes cross-subject agreement of
    its own columns, which inflates their shared structure.
  * Larger k always fits the training data better. Choose k by held-out
    score, not by training fit.

Scope boundary:                                             ~1~

  Version 1 fits and validates SRM on time-locked or item-indexed columns,
  maps new subjects into a saved model and optionally updates the model's S
  from them, carries a fitted W to other data, allows a separate run-wise W
  tied to a subject anchor, and scores reliability by subject, group, and
  condition. Not yet provided: a prior on S that depends on condition,
  exact (data-based) refitting from a model alone, searchlight or
  atlas-parcel looping, robust SRM, and time-lagged or convolved fusion
  of EEG with fMRI. The fitting library
  (thd_srm) is written so that these can be added without changing the
  options above.


 =========================================================================
* This binary version of 3dSRM 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}


This page auto-generated on Tue Nov 17 08:44:40 PM EST 2026