3dSRM


Usage: 3dSRM [options]

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:

-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:

-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:

-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:

-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:

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:

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:

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:

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:

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:

-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:

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:

* 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:

  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}