3dMVPA


Usage: 3dMVPA [options]

Cross-validated classification, continuous decoding, and encoding in
ROIs or volume/surface neighborhoods. Preprocessing, intercepts, and model
coefficients are fitted separately inside every training fold.

Analysis modes and inputs:

-mode classify        Brain response patterns -> categorical labels.
-mode decode          Brain response patterns -> numeric targets.
-mode encode          Numeric stimulus/task features -> brain responses.

-dataTable @TABLE
-dataTableFile TABLE
-dataTable Subj Run Condition InputFile ...
                       One row per sample; a table can include many subjects.
                       Subj identifies the subject for each row. Choose CV
                       to match within-subject or held-out-subject prediction.
                       InputFile must select one sub-brick when its dataset
                       has more than one, except with -time_resolved.
                       A subject-level table with Xmat and whole-bucket
                       InputFile columns is expanded to the same sample
                       representation before analysis.
-testTable @TABLE      Optional independent test table. When supplied,
-testTableFile TABLE   -dataTable/-dataTableFile contains training rows only.
                       -testTable also accepts an inline table, with InputFile
                       last, just like -dataTable. Both tables must have the
                       same column names (order/case may differ), including
                       test targets for scoring. Both may use Xmat expansion.
                       Dataset paths retain the usual working-directory basis.
                       Explicit sample IDs must be unique across both tables;
                       omitted IDs are generated over the combined rows.
                       The same dataset/brick on both sides is an error
                       (including symlink aliases). Separate files alone do
                       not establish scientific independence.
                       Cannot accompany -trial_manifest, -partition_column,
                       -train_value, -test_value, or outer CV options. All
                       fixed-split tuning/inference restrictions below apply.
                       Prediction audits append Partition, SourceTable, and
                       SourceRow (one-based input data row, before expansion).
                       -show_samples also prints this provenance. Internal
                       MVPA_Partition/MVPA_SourceTable/MVPA_SourceRow columns
                       are reserved in two-table input.
-trial_manifest FILE   Alternative to -dataTable: one row per trial beta.
                       InputFile names a whole LSS or LSA beta bucket;
                       Volume is its zero-based sub-brick index. Supply
                       trial, run and target metadata explicitly. Optional
                       Xmat and XColumn must occur together; XColumn is
                       the zero-based original design-matrix column. These
                       indices are checked; metadata is retained unchanged.
                       No beta-label matching or Xmat expansion is applied.
                       Cannot accompany -dataTable, -dataTableFile, or
                       -xmat_stims.

-time_resolved         Classify independently at each latency of whole trial
                       datasets (GIFTI/NIML surfaces or volumes). One table
                       row = one trial, InputFile = whole epoch, no selectors.
                       All trials must share the same spatial domain and time
                       axis. Reuses fixed trial folds and neighborhoods; all
                       learned transforms and tuning refit at each latency.
                       Requires direct tables and -mode classify. No model,
                       coefficient/pattern export or -nperm in this version.
                       Temporal generalization/windows are not performed.
                       With no timing options, process every data column;
                       TimeIndex is zero-based and TimeSeconds is NA. No
                       physical times are inferred from dataset metadata.
-time_start SECONDS    Together with -time_step, label ALL input columns
-time_step SECONDS     using start + TimeIndex * step. Start must be finite;
                       step must be finite and positive. Infer the count
                       from the first trial; every other trial must match.
                       Both options require -time_resolved, must be supplied
                       together, and cannot accompany -time_axis.
-time_axis SPEC        Optional explicit axis: a text FILE with finite,
                       strictly increasing SECONDS, one per line (comments #),
                       or a quoted AFNI inline vector, e.g.
                       '1D: 601%-0.100%0.001' (N%start%step). N is the number
                       of samples: 601 values from -0.100 to +0.500 seconds.
                       Explicit lists such as '1D: -0.1 0 0.075' also work.
                       Inline values use AFNI's float-vector precision.
                       Endpoint-only '..' ranges are not supported.
                       Negative pre-event times and irregular spacing allowed.
                       Count must match every trial's sub-brick count; this
                       explicit shared axis defines event-relative timing.
                       Output: PREFIX is a score bucket, one brick per latency
                       in axis order; PREFIX.temporal.1D contains ROI/center
                       scores, NFeat and NFold with TimeIndex (zero-based) and
                       TimeSeconds. Requested prediction/fold/tuning/selection
                       and PCA audits also prepend these two time columns.
                       No temporal significance or between-latency test is
                       implied by these descriptive held-out score curves.

-target_column NAME    Categorical classification or numeric decoding target.
-target_columns A,B    Multiple numeric decoding targets.
-design_columns A,B    Numeric predictors for encoding neural responses.
-score voxel|pattern  Encoding output: voxel [default] predicts each masked
                       voxel; pattern averages per-response metrics within
                       each ROI/searchlight, excluding undefined values.
-cv_column NAME        Leave one level of NAME out at a time. Choose this
                       (or -cv), -partition_column, OR a separate -testTable.
-mask DSET             Without -searchlight, positive values define ROIs and
                       a binary mask is one ROI. With -searchlight, nonzero
                       voxels define eligible centers and neighborhood voxels.
                       The mask and every sample must share a grid or exact
                       surface node-row domain. A surface searchlight may omit
                       this option to search every represented sample node.

Cross-validation:

-cv run|subject|item   Shorthand for -cv_column Run, Subj, or Item.
-cv_k K               Assign whole -cv_column groups to K balanced folds
                       instead of leave-one-group-out.
-within_column NAME    Build independent folds inside each NAME level.
                       For within-subject run CV, use Subj here.

-partition_column NAME One prespecified train/test split, for all modes.
                       Every row must have exactly one of the two values
                       below; both sets must be nonempty. Values are case-
                       sensitive. Cannot accompany -cv, -cv_column, -cv_k,
                       or -within_column. No automatic subject/run splitting.
-train_value LABEL     Training value [train]; requires -partition_column.
-test_value LABEL      Testing value [test]; requires -partition_column.
                       Only training rows fit preprocessing and the model;
                       only test rows contribute to scores. Prediction audits
                       retain training rows with NA predictions/folds.
                       All test classes must be represented in training;
                       class order comes from first appearance in training.
                       Tuned ridge/SVM require -inner_cv_column, with at
                       least two groups among training rows. Inner CV never
                       uses the reserved test rows.
                       Permutation blocks must lie entirely in one partition;
                       use a composite partition/block column if needed.
                       Full-data -save_coefficients is incompatible with a
                       reserved test set. Add -save_model for supported reuse.

Cross-condition/task/session transfer:

  -transfer_column NAME  Directional source -> destination analysis, for all
                         modes/estimators and ROI/volume/surface analyses.
                         Replaces outer CV/partition options. Every row must
                         belong to one of the two domains; no silent subsetting.
  -train_domain LABEL    Required source-domain value (case-sensitive).
  -test_domain LABEL     Required, distinct destination-domain value.
  -transfer_subjects within|disjoint  Required study design:
                         within: each subject has both domains; fit that
                         subject's source rows and test only their destination
                         rows. Other subjects never enter that fit or tuning.
                         disjoint: one pooled source fit; every destination
                         subject must be absent from source training.
  -transfer_items disjoint|allow  Default disjoint: no shared item identities
                         across domains, including across subjects. Use allow
                         for deliberate transfer on repeated stimuli/items.
                         Item IDs must identify the same stimulus globally;
                         unique row IDs alone cannot establish item novelty.
  -session_column NAME   Session identity column [Session], required for transfer.
  -transfer_sessions disjoint|allow  Default disjoint: no shared (Subj,Session)
                         keys across domains. Use allow for task/condition
                         transfer within the same session. Local session names
                         may repeat across different subjects.

Transfer needs explicit subject and item roles (Subj, Item/Trial, or role
options) plus session metadata. Sample IDs remain unique. Repeated dataset/
brick selections, including symlink aliases, are rejected even within a domain.
Overlap checks use supplied exact identities, not image-content comparisons.

One table may contain both domains; alternatively, -dataTable/-testTable must
contain only source/destination rows respectively, with the same columns.
Classification requires the same complete class-label set in each fit's two
domains. Numeric response/design columns retain their shared names and order;
values must be finite. Recode labels/align numeric units explicitly beforehand:
no automatic category mapping, response matching, registration or alignment.
Volume dimensions/view/space and real affine must match (1e-5 tolerance per
entry); surface node IDs/order must match. One shared mask defines features.

Only source rows fit nuisance adjustment, scaling, selection, PCA and models.
Tuning requires -inner_cv_column with multiple source groups per fit. Test
rows alone are scored. Permutation blocks must stay within domain AND subject
for within-subject transfer; use composite keys such as Subj_Task_Run.
Existing null/metric rules apply; transfer scores are not population inference.
-save_coefficients is incompatible. -save_model retains #27's ridge/volume
limits and requires ONE fit: save subjects separately for within-subject reuse.
-apply_model does not repeat these study-design/overlap checks on new samples.

PREFIX.transfer.1D records direction, policies, overlap counts, target/class
mapping and each sample's domain/role/fold/subject/item/session. Standard
prediction/fold audits remain available; training predictions are NA.
-validate_only prints the transfer design without fitting or writing files.

Sample roles:

-subject_column NAME   Subject role [auto-detect Subj].
-run_column NAME       Run role [auto-detect Run].
-item_column NAME      Item/trial role [auto-detect Trial or Item].
                       Item labels may repeat: equal labels mean the same
                       item identity, not a run-local trial counter. Run is
                       not automatically prepended. For distinct trials use
                       run-qualified IDs, e.g. s01_r01_t001, s01_r02_t001.
-fold_column NAME      Fold role [auto-detect Fold].
-sample_column NAME    Unique sample labels [auto-detect Sample; otherwise
                       row000001, ...]. Explicit Sample IDs must be unique
                       across all rows, including both train/test tables.
-xmat_stims LIST       Comma-separated X-matrix stimuli to expand [all].

Model options:

-method METHOD         Classify: centroid [default], ridge, svm, logistic,
                       lda_diag, lda_shrinkage. Decode: ridge [default], elastic_net,
                       pls, svr. Encode: ridge [default], elastic_net, pls,
                       banded_ridge. See continuous estimator options below.
                       Ridge classification fits one 0/1 response per class
                       with argmax decisions; exact ties choose the first
                       encoded class. Decisions are not probabilities.
-logistic_lambda L|auto  L2 softmax classification; positive penalty [1].
                       Binary and multiclass use one joint K-class model:
                       mean natural-log loss + L/2 * sum(weights squared).
                       Intercepts are unpenalized; no class weighting.
                       Every training split must contain every class.
                       Decisions are logits; probabilities sum to one.
                       Exact argmax ties use the first encoded class.
-logistic_lambda_grid L1,L2,...  Enables grouped nested penalty selection
                       [auto: 0.01,0.1,1,10,100]; cannot accompany numeric L.
                       Default inner objective: log_loss; also accepts brier,
                       ACC and BACC. Exact ties prefer larger lambda.
                       Uses -inner_cv_column/-inner_cv_k; composes with
                       nuisance adjustment, feature selection and PCA.
-logistic_tol T        Maximum absolute objective gradient [1e-6],
                       range [1e-12,1e-2]. Verified on every fit.
-logistic_max_iter N   L-BFGS iteration limit [1000]; nonconvergence fails.
                       Scale features for numerical stability. Solver storage
                       is about 152*K*(NFeature+1) bytes per worker, plus data.
                       -save_predictions adds ProbabilityClass0,... in the
                       printed class-label order; training-only rows are NA.
                       -save_fold_scores adds lambda, inner loss, convergence
                       diagnostics, held-out LogLoss and Brier.
                       Main score/permutation maps still use ACC/BACC.
                       Model-file, coefficient and pattern export remain ridge-only.
-svm_c C|auto          Native linear SVM only: positive cost [1]. Each
                       one-vs-rest model minimizes .5*(||w||^2+b^2) +
                       C*sum(max(0,1-y*(Xw+b))^2). The intercept b IS
                       penalized (constant feature = 1); no class weights.
                       Larger C penalizes margin violations more strongly.
                       Raw class margins are not probabilities; argmax wins,
                       exact ties choose the first encoded class.
-svm_c_grid C1,C2,... Positive distinct candidates; enables grouped nested
                       selection [auto default: 0.01,0.1,1,10,100]. Cannot
                       accompany numeric -svm_c. Uses -inner_cv_column and
                       -inner_cv_k; by default minimize 1-ACC/BACC (-metric)
                       over pooled inner held-out rows. Ties choose SMALLER
                       C. Every inner training set needs every class.
                       Scaling, selection and fitting repeat per permutation.
                       PREFIX.tuning.1D records all candidate losses.
-svm_tol T            Absolute projected-dual-gradient tolerance [1e-6],
                       range [1e-12,1e-2]. Deterministic cyclic coordinate
                       descent verifies final KKT residual for every class.
-svm_max_iter N       Maximum sweeps per class [10000]. Nonconvergence is
                       an error; increase this limit, rescale, or reduce C.
                       Fold audits append C, InnerNFold, InnerLoss, maximum
                       class SolverIterations and SolverResidual. SVM is
                       classification-only; descriptive coefficient export
                       currently remains ridge-only.
-shrinkage A           lda_shrinkage only: fixed covariance shrinkage in
                       (0,1] [0.1]. Use (1-A)*S + max(A,F)*T*I, where S is
                       pooled within-class covariance, T its mean variance,
                       and F the relative variance floor. No CV tuning.
-variance_floor F      LDA only: relative variance floor [1e-6], allowed
                       range [1e-12,1]. lda_diag floors each variance at
                       F*T. If all within-class variances are zero, T uses
                       overall training variance, then 1 for constant data.
-class_prior P         LDA only: equal [default] or empirical (training
                       class proportions). LDA needs more training rows
                       than classes in every outer fold. Slopes, means,
                       covariances and priors use training rows only.
                       DecisionClass scores are centered linear discriminants,
                       not probabilities; exact ties choose the first class.
                       Fold audits append Shrinkage, CovarianceScale,
                       VarianceFloor (absolute), and CovarianceForm.
-lambda L              Positive ridge penalty [1]. Slopes are penalized;
                       the training-fitted intercept is unpenalized.
                       Use -lambda auto for nested grouped selection.
-lambda_grid L1,L2,... Positive distinct candidates; enables nested tuning
                       [auto default: 0.01,0.1,1,10,100]. Cannot accompany
                       a numeric -lambda. One penalty per outer fold/unit
                       is shared across responses. Default: mean response
                       SSE / training-mean-baseline SSE on inner held-out
                       rows; exclude constant responses. Exact ties or no
                       informative responses select the largest penalty.
                       For classification, responses are class indicators:
                       default tuning uses normalized class-wise squared error.
                       Override with -tune_metric ACC/BACC. Inner training sets
                       contain every class, including under permutations.
-lambda_per_response  Continuous decode/encode only: select a separate lambda
                       for each response using grouped inner CV. Enables the
                       auto grid unless -lambda_grid is supplied; incompatible
                       with numeric -lambda. Shared lambda remains the default.
                       Each response minimizes its pooled inner -tune_metric
                       loss (default normalized_mse); ties/all-undefined losses
                       choose the largest lambda. Feature/PCA configurations
                       remain shared: their objective is the mean of response-
                       wise minimum losses, excluding undefined normalized-MSE
                       responses. Configuration ties choose smaller requested
                       feature count, then smaller requested PCA count.
                       PREFIX.tuning.1D and optional candidate/count audits
                       gain response-level losses, local lambda selections,
                       configuration losses and final selections. Fold/pattern
                       audits report each response's actual selected lambda.
                       Preprocessing, tuning and fitting repeat under nulls;
                       score aggregation/correction families do not change.
                       Pattern encoding gains independent voxel/node penalties
                       within each joint fit; singleton voxel encoding already
                       tunes one response. Coefficient export remains a separate
                       full-data shared-penalty fit requiring -coef_lambda.
                       Inner candidate fits still share factors across responses;
                       outer fits use up to min(NResponse,NLambda) factors.
                       Extra audit storage grows as outer folds * feature/PCA
                       configurations * lambdas * responses, per worker.
-inner_cv_column NAME Inner grouping column [outer -cv_column].
                       Required explicitly with tuned fixed partitions.
-inner_cv_k K          Balance whole inner groups into K folds [default:
                       leave one group out]. Every outer training set must
                       contain at least two inner groups (or K if given).
                       Shared by all candidate searches. Preprocessing is
                       refitted within every inner split.
                       PREFIX.tuning.1D records all candidate losses;
                       fold audits append selected penalties and losses.
-distance D            Centroid only: euclidean [default], correlation, cosine.
-tune_metric NAME      Inner-CV selection objective, independent of -metric.
                       Requires a lambda/C or feature-count search.
                       default: normalized_mse for ridge (including classify);
                       logistic uses log_loss; others use ACC/BACC from -metric.
                       Classification accepts ACC, BACC, and (ridge only)
                       normalized_mse. Decode/encode accepts normalized_mse,
                       MSE, RMSE, MAE. Logistic also accepts log_loss and brier,
                       pooled over inner held-out rows; see conventions below.
                       ACC/BACC minimize 1-score on pooled inner held-out rows.
                       Continuous errors pool rows within each response, then
                       average responses equally; RMSE takes each response's
                       square root before averaging. These errors retain target
                       units, so differently scaled targets affect selection.
                       normalized_mse divides each response's SSE by SSE of
                       the inner-training-mean baseline, excluding zero-baseline
                       responses. All excluded: NaN loss and deterministic tie
                       fallback. Other losses must be finite; failed fits abort.
                       BACC averages recalls over classes present in pooled
                       inner tests, not equally over folds. Exact ties prefer
                       fewer requested features, then larger lambda/smaller C.
                       Outer scores, permutation tails and feature ranking rules
                       do not change when the tuning objective changes.
-save_tuning FILE      Optional common candidate audit for any nested search.
                       Includes objective, candidate ID, count, penalty, pooled
                       test size, valid components, loss and selected flag.
                       Existing PREFIX.tuning.1D and feature_tuning.1D remain.

-pca_components K     Fit centered, unwhitened PCA in every training split.
-pca_components_grid K1,K2,... Tune distinct positive component counts
                       jointly with feature counts and lambda/C in inner CV.
                       Order: nuisance -> scale all inputs -> select -> PCA
                       -> estimator. PCA always centers using training means,
                       including with -scale none. In encode mode it projects
                       design predictors, never response voxels. Defaults off.
                       Counts clip to numerical rank and NTrain-1, separately
                       in each split. Rank threshold is 64*DBL_EPSILON*
                       max(NTrain,NFeat)*largest eigenvalue. Rank zero gives
                       one zero model input and reports zero components.
                       Ties: smaller feature count, smaller requested PCA
                       count, then larger lambda / smaller C. Refit PCA in
                       every permutation. PREFIX.pca.1D reports observed
                       fold ranks and sample variances; PREFIX.pca_tuning.1D
                       reports all nested candidates and inner count ranges.
-save_pca_loadings FILE  Optional observed fold component loadings and means,
                       with original feature IDs. Coordinates are AFTER
                       nuisance/scaling/selection, not raw input weights.
                       Largest absolute loading is positive; tied eigenspaces
                       have no unique basis. Memory scales as folds * input
                       width * maximum retained count, per worker.
                       PCA cannot yet accompany -save_coefficients.
                       Correlation-distance centroid with one retained PC is
                       degenerate; Euclidean is the default distance.

-select_features K     Retain the top K predictors per training split.
-select_features_grid K1,K2,... Tune distinct positive counts in grouped
                       inner CV, jointly with lambda/C when tuned. These
                       options are mutually exclusive; default is all features.
                       Counts are capped at each unit's available width.
                       Every training split needs at least two samples.
                       Classification: rank between-class / total variance
                       (eta squared). Decode/encode: mean squared Pearson
                       correlation over nonconstant response columns.
                       Constant features score zero; exact ties use the lower
                       original input-column index. Zero-score features can
                       fill the requested count; scores are not significance.
                       Order: nuisance OLS, scaling of ALL original columns,
                       supervised selection, optional PCA, model fit.
                       sample_center acts before selection and PCA.
                       Selection is refitted in every inner/outer split and
                       permutation. Never select once before cross-validation.
                       Default: ridge tunes normalized squared loss; logistic
                       tunes log_loss; other
                       classifiers use 1-ACC/BACC from -metric. -tune_metric
                       overrides the objective. Ties prefer smaller counts,
                       then smaller PCA counts (if enabled), then largest
                       lambda / smallest C. With constant ridge
                       responses, normalized_mse uses that rule (loss is NaN).
                       Encoding selects design columns, shared across the
                       current unit's responses; it does not select output voxels.
                       Writes PREFIX.features.1D with observed outer-fold
                       original voxel/node IDs or design names, ranks, scores,
                       requested/effective counts. With inner CV, also writes
                       PREFIX.feature_tuning.1D with all count/penalty losses.
                       With PCA these losses condition on its selected count.
                       Existing penalty audits condition on both counts.
                       NFeat in existing maps/tables remains the input width.
                       Fixed partitions need explicit -inner_cv_column for a
                       count grid. Incompatible with -save_coefficients.

-nuisance_columns C1,C2,... Numeric covariates for predictor-side OLS.
                       Fits intercept and slopes using training rows only,
                       subtracts their prediction, then applies -scale.
                       Repeats inside every inner/outer split and null fit.
                       Adjusts neural predictors in classify/decode; design
                       predictors in encode. Targets and scores retain their
                       original units; this is not target residualization,
                       incremental R2, or a causal/conditional effect test.
                       Covariates must be known for training AND test rows.
                       Supply numeric dummy columns for factors, omit one
                       level and do not add an intercept column. Each training
                       design must have full rank and ntrain > ncovariates+1.
                       Cannot reuse target/design columns as nuisances.
                       With -nperm, all covariate values must be identical
                       within each -permute_within block. Exchangeability
                       within those blocks remains the user's assumption.
                       General residual permutations are not implemented.
                       -save_coefficients is unavailable with this option
                       because that export lacks nuisance-fit parameters.
-scale S               feature_zscore [default], sample_center, run_center,
                       or none. All learned values are training-fold only.
                       run_center requires a run role and cannot be applied
                       to a run absent from that fold's training data.
-metric M              balanced_accuracy [default] or accuracy. This selects
                       the SCORE map; the ROI table reports both.
                       Continuous modes default to cross_validated_r2 and
                       also accept pearson, spearman, MAE, RMSE. R2 uses
                       each fold's training response mean as its baseline.
                       All five metrics are saved per target; encoding
                       pattern summaries weight responses equally. Undefined
                       scores are NaN in tables and zero in maps; NVALID
                       reports the primary metric's defined response count.

Continuous estimator options:

  -method elastic_net    Independent response fits for decoding/encoding.
  -enet_alpha A          Positive penalty strength [1].
  -enet_alpha_grid A,...  Nested candidates (at least two distinct values).
  -enet_l1_ratio R       L1 fraction in [0,1] [0.5]; 0=ridge, 1=lasso.
  -enet_l1_ratio_grid R,...  Nested mixing-ratio candidates.
                         Objective per response: SSE/(2*NTrain) + A*R*L1 +
                         A*(1-R)*L2/2; intercept unpenalized. No target scaling.
                         Alpha differs from ridge's unnormalized lambda:
                         at R=0, equivalent ridge lambda=NTrain*A.
                         Grids form the Cartesian product in supplied order,
                         alpha first, mixing ratio second. No multitask penalty.
                         Original-feature sparsity requires no PCA. Nuisance
                         adjustment/scaling/feature selection remain fold-local.
                         Sparse weights are predictive selections, not voxel
                         activations, significance, or stable causal effects.

  -method banded_ridge   Encoding only; shared group-penalty vector over responses.
  -feature_groups FILE   Two-column table with exact header: Group Column
                         One row per -design_columns entry, in that order.
                         Every design column belongs to exactly one named group.
                         These are predictor groups, not sample/CV groups.
  -banded_penalties FILE Table header lists group names in first-appearance
                         order. Each row is one positive penalty vector.
                         One row fixes penalties; multiple rows enable nested
                         selection. Duplicate vectors/incorrect group order fail.
                         Objective: SSE + sum_g lambda_g*||beta_g||^2;
                         intercept unpenalized; no group-size normalization.
                         -scale applies within training folds before penalties;
                         default z-scoring is per column, not per group.
                         Selection/PCA are excluded to preserve group identity.
                         Group score variance/covariance audits are descriptive:
                         correlated groups do not have unique causal contributions.

  -method pls            Supervised NIPALS PLS1/PLS2 regression (decode/encode).
  -pls_components K      Requested components [2].
  -pls_components_grid K,...  Nested component-count candidates.
                         Training-center X/Y after predictor preprocessing;
                         responses are NOT scaled. Use regression deflation
                         of both X and Y by each X score, unit X weights.
                         Initial score is the largest-variance residual Y column;
                         exact ties use its original column order.
                         Counts clip to min(NTrain-1,NFeat) and exhausted rank/
                         covariance; constants give a mean-only fit. NIPALS
                         weight-iterate change must converge, or the fit fails.
                         Multiple responses are joint within one fit unit:
                         decoding targets, or the ROI/searchlight neural pattern.
                         Voxel/node encoding instead fits each response alone;
                         these response domains need not give the same prediction.
                         Nested losses average response-wise losses equally;
                         component fitting itself uses unscaled response covariance.

  -method svr            Linear squared epsilon-insensitive SVR, decoding only.
  -svr_c C               Positive loss weight [1].
  -svr_c_grid C,...      Nested C candidates.
  -svr_epsilon E         Nonnegative tolerance in original target units [0.1].
  -svr_epsilon_grid E,...  Nested epsilon candidates; Cartesian C/epsilon grid.
                         Objective per response: (||beta||^2+intercept^2)/2 +
                         C*sum(max(0,abs(y-prediction)-E)^2). Intercept IS
                         penalized (constant feature=1); loss is not divided by N.
                         No target centering/scaling; separate response fits.
                         Deterministic signed dual coordinate descent verifies
                         the maximum absolute dual KKT residual. This differs
                         from classification SVM and nonsquared epsilon loss.
                         Voxelwise encoding is not exposed pending cost assessment.

  -reg_tol T             Solver tolerance [1e-7], range 1e-12 through 1e-2.
  -reg_max_iter N        Iteration limit [10000]. Failure to converge is an error.
                         Elastic net checks max absolute KKT; SVR checks dual
                         KKT; PLS checks weight-vector change. Banded ridge uses
                         a direct solve and reports normal-equation residual.
                         These residuals have different meanings/units.

For these four estimators, parameters are selected jointly inside grouped inner
CV using -inner_cv_column/-inner_cv_k and -tune_metric. The default is normalized
MSE; MSE, RMSE and MAE are supported. Exact ties prefer smaller requested
feature/PCA counts, then FIRST candidate in supplied order (also when all
normalized losses are undefined). A fixed split with tuning needs explicit
-inner_cv_column. Do not use ridge -lambda options for these estimators.

Automatic observed audits (also restored after permutations):
  PREFIX.regression.1D             Outer fit diagnostics and response metrics.
  PREFIX.regression_scores.1D      Pooled held-out per-response scores.
  PREFIX.regression_candidates.1D  All nested candidates and solver diagnostics.
  PREFIX.sparse_features.1D        Elastic net: original IDs, weights, zero flags.
  PREFIX.group_contributions.1D    Banded ridge: training group-score variance
                                  and covariance with total predicted score.
Candidate parameters are recorded in audit headers. Candidate is one-based;
generic pipeline Penalty fields contain that candidate ID for these methods.
For elastic net, coefficients use fold-preprocessed predictor units. Selected
means a nonzero coefficient; selected-out predictors are explicitly zero.
PLS diagnostics distinguish requested/effective components. Saved fitted-model,
coefficient-refit, and activation-pattern exports remain ridge-only.

Inference uses the existing exchangeable-row null: decoding shuffles complete
response rows; encoding shuffles complete design rows within the declared
blocks. Every preprocessing stage, candidate search and fit is repeated. MAE/
RMSE use the lower tail; correlations/CV-R2 use the upper tail. Blocking is not
an autocorrelation model; nuisance values must be constant within each block.

Permutation inference:

  -nperm N               Run N synchronized label/row relabelings [0: off]. The
                         identity is included. If the allowed group has at
                         most N distinct relabelings, it is enumerated exactly.
  -permute_within COL    Relabel only among rows sharing COL. Required
                         with -nperm; use 'none' only for an explicitly
                         unrestricted null. -block_column is an alias. Choose a
                         column that fully identifies the exchangeability unit,
                         such as Run, Subj, Fold, or a composite block column.
  -seed S                Monte-Carlo relabeling seed [1234567]. Exact tests do
                         not depend on this value. Classification must leave
                         every CV training fold with all target classes.
                         Continuous modes shuffle whole target rows (decode)
                         or design rows (encode), holding neural rows fixed.
                         All attribute columns move together; blocks and CV
                         metadata stay fixed. Rows must be exchangeable under
                         this null; serial time-series dependencies require
                         an appropriate design, not unrestricted row shuffling.
                         Preprocessing, tuning, and fitting repeat per null.
                         Each decoding target has a separate spatial family;
                         encoding tests its voxel or mean-pattern score.
                         MAE/RMSE use the lower tail; other metrics the upper.
                         PREFIX.inference.1D reports all continuous results.
                         Buckets add NULL_MEAN, ABOVE_NULL, PVAL/ZSCR/QVAL,
                         PFWE/ZFWE, and NNULL_VALID per target. ABOVE_NULL is
                         positive for improvement, including lower errors.
                         Undefined observations have neutral p=1 and z=0;
                         undefined nulls count conservatively as exceedances.

Classification uses the selected metric's upper-tail label-permutation null.
The same relabeling slot drives every ROI/searchlight center. Output adds the
empirical score above null-chance, PVAL/ZSCR, BH QVAL, and max-statistic
PFWE/ZFWE bricks. ZSCR and ZFWE carry AFNI FIZT statistical codes.

Spatial and output options:

-roi_sel LIST          Restrict positive mask values with an AFNI int-list.
                       This option cannot be combined with -searchlight.
-searchlight NBHD      Classify a moving volumetric neighborhood at every
                       nonzero mask voxel. NBHD is a radius in mm or one of
                       SPHERE(r), RECT(a,b,c), RHDD(r), or TOHD(r).
                       OpenMP builds use one workspace per worker; set
                       OMP_NUM_THREADS to control the worker count.
-surf SURFACE          Make -searchlight a geodesic surface searchlight on
                       this mesh (.gii/.asc/.ply/...). With -surf, NBHD must
                       be one positive radius in mm. Inputs and an optional
                       mask must be NIML/GIFTI datasets with identical dense
                       or sparse node-row domains. The output preserves sparse
                       node indexes. Requires a build with SUMA support.
-prefix PREFIX         Output dataset prefix [MVPA].
                       Without inference the dataset contains SCORE, NFEAT,
                       and NFOLD. -nperm adds ABOVE_CHANCE, PVAL, ZSCR,
                       QVAL, PFWE, and ZFWE before NFEAT and NFOLD.
                       ROI analysis also writes PREFIX.roi.1D with SCORE,
                       ACC, BACC, NFEAT, and NFOLD for every ROI.
-save_patterns PPREFIX Ridge decode/classify: descriptive activation patterns
                       from each OUTER TRAINING fit, using that fold's selected
                       lambda/features/PCA. No full-data refit or held-out
                       covariance. Supports fixed/two-table partitions.
                       A=Cov(X,S)*pinv(Cov(S,S)), where S is fitted training
                       scores (not targets), X is all neural inputs after
                       nuisance/scaling, before selection/PCA. Covariances
                       are centered sample covariances (NTrain-1).
                       Patterns use transformed feature units per score unit;
                       discarded features can have nonzero patterns through
                       correlation. Class scores use 0/1 ridge coding and are
                       not probabilities. Normalization is JOINT over outputs;
                       binary class patterns are opposite half-contrasts.
                       Pseudoinverse cutoff: 64*DBL_EPSILON*max(NTrain,NOutput)
                       *largest score eigenvalue. Rank zero yields zero maps
                       with ScoreRank=0 (no defined score direction).
                       Writes PPREFIX.patterns.1D, .pattern_covariance.1D and
                       PPREFIX.unit_ID.fold_N maps (N is one-based), one brick
                       per target/class, at the original voxel/node IDs.
                       Folds and overlapping units stay separate; many maps
                       can be produced. No pattern p-values, causal claims,
                       or automatic fold averaging. With -nperm only restored
                       observed patterns are exported. Other estimators and
                       encode mode are not supported by this option.
                       These patterns differ from raw predictive weights.
-save_coefficients CPREFIX  Ridge only: separate descriptive full-data refit.
                       Writes CPREFIX.coefficients.1D and .preprocessing.1D.
                       Encoding without searchlights writes CPREFIX maps: one
                       brick per design column plus REFIT_INTERCEPT. Other
                       analyses write CPREFIX.unit_ID per ROI/searchlight: one
                       brick per decoding target/class (encoding: per design
                       column plus intercept). Weights occupy neural feature/
                       response voxels/nodes, preserving sparse node IDs.
                       Overlapping neighborhoods retain separate models;
                       this can create many datasets and large audit files.
                       TSV identifies unit, feature, response, map and brick;
                       intercepts and all fitted preprocessing are retained.
                       y = intercept + sum(preprocessed_X * coefficient).
                       Weights use the requested -scale predictor units;
                       responses are unscaled (class responses: 0/1).
                       feature_zscore uses full-data population SD; sample_
                       center subtracts each row mean; run_center subtracts
                       full-data subject/run means recorded in preprocessing.
                       These are descriptive predictive weights, NOT held-out
                       scores, activation/Haufe maps, or significance tests.
                       Correlated features and scaling affect weight values.
-coef_lambda L         Positive full-data refit penalty [fixed -lambda].
                       Required with tuned CV; never changes CV penalties,
                       scores, predictions or permutation inference.
-save_predictions FILE Write one held-out prediction row per sample and
                       spatial unit, including sample metadata, test fold,
                       observed/predicted class labels, and every class
                       decision value. Rows never tested are retained as NA.
-save_fold_scores FILE Write ACC and BACC for every fold and spatial unit,
                       with stratum and train/test sample counts. These two
                       audit tables are opt-in because searchlight tables
                       can be very large.
-save_confusion FILE   Classification only: truth-row confusion counts and
                       per-class recall for each spatial unit, pooled and
                       by CV fold, subject, and CV stratum. CountClassN
                       columns follow the # Class label dictionary.
                       Subjects use the resolved subject role; strata use
                       -within_column (All when absent).
                       CVFoldID is a zero-based fold index; CVStratum is
                       separate so labels containing '/' remain unambiguous.
-save_probability_scores FILE
                       Logistic only: held-out LogLoss and Brier, pooled and
                       by fold, subject and stratum. Means weight rows equally.
                       LogLoss uses natural logs of true-class probabilities,
                       evaluated stably from logits without clipping.
                       Brier sums K squared probability errors before averaging
                       rows: range [0,2], including binary (both classes summed).
-save_calibration FILE Logistic only: one-vs-rest reliability bins per class,
                       pooled across held-out rows. Ten equal-width bins:
                       [lo,hi), last includes 1; counts, mean probability and
                       observed class frequency; empty bins are NA.
                       This assesses raw probabilities; no calibration transform
                       is fitted. Pooling can hide subject/fold differences.
                       Probability scores and bins are descriptive, with no
                       probability-loss inference or population inference.
-save_summary_scores FILE
                       Classification only: ACC/BACC for the same groups,
                       plus equal-subject and equal-stratum averages.
                       Pooled ACC weights samples equally; pooled BACC
                       weights present true classes equally. Equal-group
                       rows average group scores, excluding empty groups.
                       Missing true classes have NA recall and are omitted
                       from that group's BACC. Summaries use original held-
                       out predictions without refitting; they are descriptive
                       and do not establish population inference. Both new
                       audits are opt-in and can be large for searchlights.
-show_table            Print the canonical table after input conversion.
-show_samples          Print resolved datasets, bricks, and sample roles.
-show_folds            Print every training/test row in every fold.
-validate_only         Read and resolve the actual analysis inputs, print
                       all three reports above plus class/fold counts and
                       spatial coverage, then exit without fitting models
                       or writing result/audit files. Redirect stdout to
                       save this report. Errors return nonzero status.
                       Checks include selected beta values (finite inside
                       the selected ROIs/neighborhoods), numeric targets,
                       grids/node domains, and outer/inner training folds.
                       Values are checked after AFNI loading/conversion;
                       readers may repair bad floats. This is not a raw
                       file-integrity check.
                       Repeated dataset/brick selections are warnings.
                       Permutation block metadata is checked, but nulls
                       are not generated or validated. Output paths and
                       solver convergence are not tested. Supplied labels
                       and XColumn provenance are not proof of correct
                       event mapping, anatomical QC or run independence.
-quiet                 Suppress informational and progress messages.
-progress M            auto, bar, line, or off [auto]. Auto uses an updating
                       bar on a terminal and 10% milestone lines when stderr
                       is redirected. Counts completed analysis locations
                       (ROIs, searchlight centers, or encoding voxels/nodes),
                       with throughput, elapsed time and approximate ETA.
                       Each location includes all folds, tuning and requested
                       permutations; a single large ROI can take a while
                       before its first update. -quiet overrides this option.

Saved models (ridge v1; logistic v2):

-train_only           Fit all labeled input rows and export -save_model.
                       No test table, partition, outer CV or test labels.
                       Supports ridge classify/decode and logistic classify.
                       Tuning requires -inner_cv_column: fit preprocessing
                       inside each inner split, select parameters, then fit
                       all rows. Inner scores are model-selection results,
                       not independent performance estimates. Run separately
                       per subject unless pooling subjects is intentional.
                       Writes PREFIX.training.1D (fit counts/penalties), plus
                       requested tuning/selection/PCA audits. No score maps,
                       held-out predictions, permutations or pattern export.
                       -validate_only checks inputs without fitting/writing.
-save_model FILE       Export a ridge or logistic fitted model. Requires
                       -train_only, -partition_column or -testTable, with
                       volume ROIs/searchlights. With a fixed partition only
                       training rows enter the model; no full-data refit.
                       Stores ordered voxel features and image grid/space,
                       target/class labels, nuisance column names/OLS fit,
                       fitted scaling, feature selection, PCA and estimator state
                       including response-specific penalties. Observed state
                       is saved after permutation restoration. All units are
                       kept in memory until the model is published atomically.
                       Export excludes encoding, surface inputs, ordinary multi-
                       fold CV exports, run_center and -save_coefficients.
                       Supported scales: none, feature_zscore, sample_center.
3dMVPA -apply_model FILE -dataTableFile NEW_TABLE -prefix OUT
                       Standalone: -apply_model must be first. Also accepts
                       -dataTable @FILE, -sample_column and -subject_column.
                       No other analysis/fitted-setting overrides are allowed.
3dMVPA -apply_model FILE -apply_dset DSET -prefix OUT
                       Alternative to a table: predict every sub-brick of an
                       AFNI HEAD/BRIK or NIfTI dataset. Optional selectors
                       preserve order and original zero-based brick indices,
                       e.g. 'cleaned+orig[10..$]' or 'cleaned.nii.gz[8,12,9]'.
                       Cannot combine with table input or role overrides.
                       Models requiring nuisance columns need table input.
                       GIfTI/surface saved models are not yet supported.
                       NEW_TABLE has InputFile (one volume/brick per row) and
                       the saved nuisance columns, if any. Targets are optional.
                       If supplied, observed classes must be known and numeric
                       targets finite. Neither is used to make predictions.
                       Inputs must match saved dimensions/view/space and real
                       IJK-to-DICOM affine (absolute tolerance 1e-5 per entry).
                       The saved voxel order is used; no mask is redefined.
                       Writes OUT.applied.1D: unit/sample/response predictions,
                       predicted class and optional observed target. Class
                       scores (Prediction) are ridge 0/1 outputs, NOT
                       probabilities, or logistic logits. Logistic adds a
                       Probability column: softmax over all trained classes.
                       Probabilities sum to one per ROI/sample but calibration
                       on a new data domain is not guaranteed. Exact
                       ties choose the first stored class. Never fits, tunes,
                       computes held-out scores or performs inference. Using
                       training rows here does not make predictions held-out.
                       Output is long form: one row per ROI x class x sample
                       (or ROI x continuous response x sample). A labeled
                       mask trains one model per positive ROI value, using
                       all its voxels; a binary mask trains one ROI model.
                       -apply_dset appends SourceBrick, BrickLabel, TimeSeconds.
                       TimeSeconds uses original dataset time metadata (NA
                       without a recognized time axis), not stimulus timing.
                       Whole-run baseline/nuisance cleanup is external; apply
                       comparable cleanup to training and application data.
                       All stage parameters and labels are versioned data;
                       unsupported versions or malformed models are rejected.
                       Grid checks cannot establish anatomical registration or
                       acquisition compatibility; no registration is performed.

Training block means and predicting an unlabeled run:

3dTstat -mean -prefix block01.nii.gz 'cleaned.r01.nii.gz[8..11]'
# blocks.1D: Subj Run Condition InputFile; one mean image per block.
# rois.nii.gz: positive integers identify distinct, nonoverlapping ROIs.
3dMVPA -train_only -mode classify -dataTable @blocks.1D \
       -target_column Condition -mask rois.nii.gz -method logistic \
       -logistic_lambda 1 -save_model decoder.mvpa -prefix training
3dMVPA -apply_model decoder.mvpa -apply_dset cleaned.r03.nii.gz \
       -prefix predictions
# predictions.applied.1D: ROI x class x TR logits and probabilities.
# For ridge scores instead, replace -method logistic -logistic_lambda 1
# with -method ridge -lambda 1 and use a different model/prefix.
# Optional tuning: -logistic_lambda auto -inner_cv_column Run;
# ridge uses -lambda auto -inner_cv_column Run. Each inner training
# split must contain every class. Averaged-block tuning does not measure
# single-TR prediction accuracy; independent labeled TRs are needed for that.

Standalone paired model comparisons:

3dMVPA -compare_predictions A.pred.1D B.pred.1D -prefix CMP
                       Compare two -save_predictions audits without refitting.
                       Must be the first option; only -prefix may follow.
                       Supports classification or continuous decode/encode;
                       compare the same targets and spatial unit definitions.
                       Matches complete unit/response/sample domains, including
                       training-only rows, regardless of audit row order.
                       Subject/run/item/input-fold, test fold/stratum, observed
                       outcomes and tested status must agree. Continuous runs
                       must have identical training-mean baselines for CV-R2.
                       Available spatial metadata must also agree. Source
                       table paths/row numbers are recorded, not identity keys.
                       Use stable explicit -sample_column IDs if input tables
                       are reordered. No silent intersection or missing pairs.
                       Writes CMP.comparison.1D and CMP.paired_predictions.1D.
                       Reports pooled, fold, subject and stratum scores: ACC/
                       BACC, or Pearson/Spearman/CV-R2/MAE/RMSE per response.
                       DeltaBminusA is B-A; ImprovementB is positive when B
                       improves (A-B for MAE/RMSE, B-A for other metrics).
                       Undefined metrics/differences stay NA. Pooled scores
                       use all held-out rows, not an average of fold scores.
                       Only saved predictions are used; original fits, image
                       registration and ROI definitions cannot be verified.
                       Descriptive only: no p-values, confidence intervals,
                       population inference, spatial maps or model selection.

Preparing trial betas:

Trial-beta fMRI analyses take response maps, not raw BOLD. A short LSS route:

  1. afni_proc.py: preprocess all runs onto a common grid; inspect alignment,
     censoring and masks. Retain each run's full-length scaled EPI.

  2. Build an IM design with 3dDeconvolve (directly or via afni_proc.py).
     For LSS, put ALL trials in one -stim_times_IM stimulus; keep category
     labels separately. In afni_proc.py, use -regress_stim_types IM and
     -regress_3dD_stop to write X.xmat.1D and X.nocensor.xmat.1D without
     fitting the full GLM. Choose timing/basis/nuisance options for your study.
     Alternative LSA route: fit the IM GLM with 3dDeconvolve/3dREMLfit and
     select each trial's actual _Coef brick; skip the LSS steps below.

  3. 1dXmatTool: check and split the multi-run DESIGN before running 3dLSS.
     From the results directory (Bash syntax):

       mkdir -p split lss tables
       1dXmatTool -infile X.xmat.1D -uncensored X.nocensor.xmat.1D \
                  -validate -for lss
       1dXmatTool -infile X.xmat.1D -uncensored X.nocensor.xmat.1D \
                  -split_runs -prefix split/X

     Local censoring and trial-column mappings are preserved in the split
     matrices and .rows.1D/.columns.1D tables. Review failed checks first.

  4. 3dLSS: fit each run separately. Adapt run list and EPI filenames:

       for run in 01 02 03 04; do
           3dLSS -matrix split/X.r${run}.xmat.1D \
                 -input pb03.s01.r${run}.scale+orig \
                 -mask mask_epi_anat.s01+orig -prefix lss/LSS.r${run}.nii.gz
       done

     The scale-block number (pb03 here) depends on your afni_proc.py blocks.
     Use FULL-length per-run EPI; 3dLSS applies the local GoodList censoring.

  5. 1dXmatTool -> 3dMVPA: map trials to estimates, then inspect the folds.
     Supply events.1D with Run Volume Condition [Item]: Run is one-based;
     Volume is the zero-based LSS volume within that run, in IM-column order.
     Category labels come from the trial log, not the single IM stimulus name.

       1dXmatTool -infile X.xmat.1D -uncensored X.nocensor.xmat.1D \
                  -export_manifest -events events.1D -subject s01 \
                  -beta_pattern 'lss/LSS.r{run}.nii.gz' -prefix tables/lss
       3dMVPA -mode classify -trial_manifest tables/lss.trials.1D \
              -target_column Condition -cv_column Run \
              -mask mask_epi_anat.s01+orig -validate_only

     To write InputFile[volume] rows for -dataTable instead, add
     -manifest_format selected to the export command. Add numeric targets
     or design predictors by matching trial identities for decode/encode.
     LSS can mix neighboring trials: keep separately estimated runs together
     in CV. Fold-local MVPA preprocessing cannot undo upstream dependence.

Numbered examples:

Run-CV examples (1, 2, 4, 5, 7-9) fit each subject independently with
-cv_column Run -within_column Subj; provide at least four runs per subject.
Each classification run contains every class. Run IDs include the subject
(s01_r01, s02_r01), so permutation blocks never mix subjects.
For held-out-subject prediction, replace those two options with -cv_column
Subj; if tuning, also use -inner_cv_column Subj and enough training subjects.
Replace filenames and column names with your data.
Use -validate_only with an analysis command to inspect inputs before fitting.

samples.1D has one row per trial; InputFile selects one beta brick. For example:

  Subj Run     Item     Condition Rating Arousal Motion Luminance Contrast Shape InputFile
  s01  s01_r01 s01_t001 face      4.2    2.1     0.1    0.8       0.3      1.2   s01/lss/LSS.r01.nii.gz[0]
  s01  s01_r01 s01_t002 house     2.3    1.4     0.2    0.4       0.7      0.5   s01/lss/LSS.r01.nii.gz[1]
  s02  s02_r01 s02_t001 face      3.8    2.5     0.2    0.8       0.3      1.2   s02/lss/LSS.r01.nii.gz[0]
  s02  s02_r01 s02_t002 house     2.7    1.6     0.1    0.4       0.7      0.5   s02/lss/LSS.r01.nii.gz[1]

Include all trials/runs for each subject. Item denotes item identity; it
need not be unique per row. If each trial is a distinct item, use IDs such
as s01_r01_t001 and s01_r02_t001 (trial numbering can restart per run), or
continue s01_t001, s01_t002, ... across runs. Reusing s01_t001 in two runs
is accepted but identifies the same item for Item-based grouping or transfer
overlap checks. Preserve that identity when a stimulus item truly repeats.
Sample is different: it identifies an observation and must be unique even
when Item repeats. If Sample is omitted, unique row IDs are generated.
Condition is categorical; Rating/Arousal are numeric targets; Motion is a
numeric nuisance covariate. Luminance/Contrast/Shape are numeric encoding
predictors. Include only columns your command needs. All maps/masks must
share the feature grid.
rois.nii.gz is a labeled ROI mask (a binary mask is one ROI); brain.nii.gz is
a binary search mask. Paths are relative to the current working directory.
Pooled scores summarize held-out samples; they are not population inference.

1. Classification: ROI baseline and error audits.

  3dMVPA -mode classify -dataTable @samples.1D \
         -target_column Condition -cv_column Run -within_column Subj -mask rois.nii.gz \
         -method centroid -scale feature_zscore -metric balanced_accuracy \
         -save_predictions class_roi.pred.1D -save_confusion class_roi.confusion.1D \
         -prefix class_roi

Each subject/run is held out once. Read class_roi.roi.1D and the confusion table.

2. Classification: volume searchlight with permutation inference.

  3dMVPA -mode classify -dataTable @samples.1D \
         -target_column Condition -cv_column Run -within_column Subj -mask brain.nii.gz \
         -searchlight 'SPHERE(5)' -method svm -svm_c 1 -scale feature_zscore \
         -metric balanced_accuracy -nperm 5000 -permute_within Run -seed 314159 \
         -prefix class_search

The radius is 5 mm. Within-run shuffling must suit your experiment's null.
Maps include BACC, PVAL and PFWE; use ZSCR/ZFWE for positive-only AFNI thresholds.
Without -nperm, scores describe prediction performance without significance.

3. Classification: separate training/test tables and nested ridge tuning.

  3dMVPA -mode classify -dataTable @training.1D -testTable @testing.1D \
         -target_column Condition -mask rois.nii.gz -method ridge \
         -lambda auto -inner_cv_column Run -tune_metric BACC \
         -scale feature_zscore -save_predictions class_test.pred.1D \
         -save_tuning class_test.candidates.1D -prefix class_test

Tables have the same columns and distinct sample/brick identities. Reserve
whole runs/sessions/subjects as appropriate; training needs multiple inner
Run groups and every class. This fit pools training rows across subjects;
only test rows are scored. For one table, use -partition_column Split with
train/test values (example 6).

4. Decoding: predict two continuous attributes from ROI patterns.

  3dMVPA -mode decode -dataTable @samples.1D \
         -target_columns Rating,Arousal -cv_column Run -within_column Subj -mask rois.nii.gz \
         -method ridge -lambda_per_response -inner_cv_column Run \
         -scale feature_zscore -metric cross_validated_r2 \
         -save_predictions decode_roi.pred.1D -prefix decode_roi

Each target gets its own training-selected penalty. Inspect CVR2, correlation
and errors in decode_roi.continuous.1D; negative CVR2 is possible.

5. Decoding: searchlight with nuisance adjustment, selection and PCA.

  3dMVPA -mode decode -dataTable @samples.1D -target_column Rating \
         -cv_column Run -within_column Subj -mask brain.nii.gz -searchlight 'SPHERE(5)' \
         -method ridge -lambda auto -inner_cv_column Run \
         -nuisance_columns Motion -scale feature_zscore \
         -select_features 50 -pca_components 5 -prefix decode_search

Training-only order: nuisance OLS -> scaling -> selection -> PCA -> ridge.
Counts clip to available features/rank. Motion must be a valid, full-rank
covariate in every training split. Nuisance adjustment acts on neural inputs.

6. Decoding: fixed holdout, save the fitted pipeline, apply to new samples.

  3dMVPA -mode decode -dataTable @partitioned.1D -target_column Rating \
         -partition_column Split -mask rois.nii.gz -method ridge \
         -lambda auto -inner_cv_column Run -scale feature_zscore \
         -save_model rating.mvpa -save_predictions decode_test.pred.1D \
         -prefix decode_test
  3dMVPA -apply_model rating.mvpa -dataTableFile new_samples.1D \
         -prefix rating_new

partitioned.1D adds Split=train/test to the sample table. Only training rows
fit the saved pipeline, pooled across subjects. New samples need matching
grids, but no Rating column.
rating_new.applied.1D contains predictions; application never refits or scores.

7. Encoding: stimulus features predict each voxel’s response.

  3dMVPA -mode encode -dataTable @samples.1D \
         -design_columns Luminance,Contrast,Shape -cv_column Run -within_column Subj \
         -mask brain.nii.gz -score voxel -method ridge -lambda 1 \
         -scale feature_zscore -metric cross_validated_r2 -prefix encode_voxel

Scaling acts on design predictors. Output maps score each voxel's held-out
prediction; use beta coefficients as InputFile responses, not t-statistics.

8. Encoding: ROI pattern scores with response-specific regularization.

  3dMVPA -mode encode -dataTable @samples.1D \
         -design_columns Luminance,Contrast,Shape -cv_column Run -within_column Subj \
         -mask rois.nii.gz -score pattern -method ridge -lambda_per_response \
         -inner_cv_column Run -scale feature_zscore \
         -save_tuning encode_pattern.candidates.1D -prefix encode_pattern

Each response voxel gets a penalty; pattern scores average defined voxel
metrics within each ROI. This is not correlation between spatial patterns.

9. Encoding: test the feature-to-response association by permutation.

  3dMVPA -mode encode -dataTable @samples.1D \
         -design_columns Luminance,Contrast,Shape -cv_column Run -within_column Subj \
         -mask brain.nii.gz -score voxel -method ridge -lambda 1 \
         -scale feature_zscore -nperm 5000 -permute_within Run -seed 314159 \
         -prefix encode_perm

Whole design rows shuffle within Run; predictor columns move together.
Use only when those rows are exchangeable. See encode_perm.inference.1D
and PVAL/PFWE maps; this is not a population test across subjects.

Output tables use .1D with # Columns: headers and mixed text/numeric fields;
read them as tables. Explicit -save_* filenames are honored as given.

10. Cross-condition generalization: visual -> auditory within each subject.

  3dMVPA -mode classify -dataTable @transfer.1D -target_column Condition \
         -transfer_column Task -train_domain visual -test_domain auditory \
         -transfer_subjects within -transfer_items allow \
         -transfer_sessions allow -mask rois.nii.gz -method ridge \
         -lambda auto -inner_cv_column Run -scale feature_zscore \
         -save_predictions transfer.pred.1D -prefix transfer

transfer.1D adds Task and Session, with canonical Item IDs. This example
intentionally permits repeated items and same-session transfer. Each subject
needs both tasks and multiple source Run groups. Inspect transfer.transfer.1D.
For held-out-subject transfer use -transfer_subjects disjoint, with entirely
different destination subjects. Reverse the domain values in a separate run
with a new prefix to test the reverse direction; results need not be symmetric.

11. Classification: tune class probabilities and assess calibration.

  3dMVPA -mode classify -dataTable @samples.1D -target_column Condition \
         -cv_column Run -within_column Subj -mask rois.nii.gz \
         -method logistic -logistic_lambda auto -inner_cv_column Run \
         -save_predictions logistic.pred.1D -save_fold_scores logistic.fold.1D \
         -save_probability_scores logistic.scores.1D \
         -save_calibration logistic.calibration.1D -prefix logistic

Nested selection minimizes held-out log loss. Inspect probability scores and
reliability bins alongside ACC/BACC; probabilities need not be well calibrated.
Use -tune_metric brier to select lambda by squared probability error instead.

12. Sparse continuous decoding (elastic net):

  3dMVPA -mode decode -dataTable @samples.1D -target_columns Rating,Arousal \
         -cv_column Run -within_column Subj -mask rois.nii.gz \
         -method elastic_net -enet_alpha_grid .01,.1,1 \
         -enet_l1_ratio_grid .25,.75,1 -inner_cv_column Run \
         -metric cross_validated_r2 -save_predictions sparse.pred.1D \
         -prefix sparse

Inspect sparse.sparse_features.1D alongside held-out response scores. Different
folds may choose different voxels when features are correlated.

13. Named feature-space encoding (banded ridge):

For -design_columns Visual1,Visual2,Semantic1,Semantic2, groups.1D contains:
  Group    Column
  visual   Visual1
  visual   Visual2
  semantic Semantic1
  semantic Semantic2

penalties.1D lists explicit candidate vectors, with the same group order:
  visual semantic
  0.1    10
  1      1
  10     0.1

  3dMVPA -mode encode -dataTable @samples.1D \
         -design_columns Visual1,Visual2,Semantic1,Semantic2 \
         -cv_column Run -mask brain.nii.gz -score voxel \
         -method banded_ridge -feature_groups groups.1D \
         -banded_penalties penalties.1D -inner_cv_column Run -prefix banded

14. Joint-target supervised components (PLS regression):

  3dMVPA -mode decode -dataTable @samples.1D -target_columns Rating,Arousal \
         -cv_column Run -within_column Subj -mask rois.nii.gz \
         -method pls -pls_components_grid 1,2,4 -inner_cv_column Run \
         -metric RMSE -save_predictions pls.pred.1D -prefix pls

Response units affect the joint PLS components. Report those units and inspect
retained counts in pls.regression.1D; PLS is distinct from unsupervised PCA.

15. Epsilon-insensitive behavioral prediction (linear SVR):

  3dMVPA -mode decode -dataTable @samples.1D -target_column Rating \
         -cv_column Run -within_column Subj -mask rois.nii.gz \
         -method svr -svr_c_grid .1,1,10 -svr_epsilon_grid 0,.1,.5 \
         -inner_cv_column Run -tune_metric MAE -metric MAE \
         -save_predictions svr.pred.1D -prefix svr

Epsilon has Rating's units. Compare aligned held-out predictions with the
ridge baseline; changing the loss does not guarantee improved prediction.

16. Time-resolved MEG/EEG source classification:

One row per individual trial (not an evoked condition average), with one
scalar source map per GIFTI data column, all on the same node domain:

  Subj Run Sample   Condition InputFile
  s01  r1  trial001 face      trial001.lh.func.gii
  s01  r1  trial002 house     trial002.lh.func.gii
  ... (all trials from all runs for this subject)

latencies.1D contains one event-relative time in seconds per data column,
e.g. -0.100, -0.099, ... on separate lines. Export matching scalar source
orientations, vertex indexes/order, and event alignment for every trial.
Process hemispheres separately unless explicitly constructing a shared domain.

  3dMVPA -mode classify -dataTable @trials.1D \
         -target_column Condition -cv_column Run -method ridge \
         -mask lh.rois.niml.dset -time_resolved -time_axis latencies.1D \
         -save_predictions lh.predictions.1D -save_fold_scores lh.folds.1D \
         -prefix lh.decoding.niml.dset

To process all latencies without specifying the number of samples, replace
-time_axis latencies.1D above with:

         -time_start -0.100 -time_step 0.001

The count comes from the input columns; all trials must have the same count.
Alternatively, omit -time_axis entirely and keep just -time_resolved to
process every column with TimeIndex=0,1,2,... and TimeSeconds=NA. This does
not infer event-relative timing from GIFTI or volume metadata.

For regularly sampled trials, replace -time_axis latencies.1D above with:

         -time_axis '1D: 601%-0.100%0.001'

This is AFNI's N%start%step syntax: 601 samples starting at -0.100 seconds,
with a 0.001-second step, ending at +0.500 seconds (both endpoints included).
For -0.100 through 0 seconds at the same spacing, use:

         -time_axis '1D: 101%-0.100%0.001'

A range like '1D: -0.100..0' does not specify the step and is not accepted.
The generated sample count must match every trial's number of data columns.

For geodesic searchlights add -surf lh.white.gii -searchlight 10; the mask
then defines eligible nodes (or omit it to use every represented node).
Use a matching mesh with coordinates in mm and a SUMA-enabled build.

The output bucket has one score map per latency; exact times and spatial-unit
scores are in lh.decoding.niml.dset.temporal.1D. Trial folds are reused, but
each latency gets independent training-only preprocessing, tuning and fits.
Run subjects separately for individual curves/maps, or use explicit subject
strata/held-out-subject CV to match the intended generalization question.
Condition averages cannot substitute for trial-level cross-validation.
No across-time inference is performed; significance at one time and not another
does not establish a difference between those times.

References:

Selected methodological references; cite the papers relevant to your analysis.
The options above specify 3dMVPA's objectives, scaling and inference contracts.

* Cox (1996), Comput Biomed Res 29:162-173. [AFNI]
  AFNI: software for analysis and visualization of functional magnetic
  resonance neuroimages. https://doi.org/10.1006/cbmr.1996.0014
* Norman, Polyn, Detre & Haxby (2006), Trends Cogn Sci 10:424-430. [MVPA]
  Beyond mind-reading: multi-voxel pattern analysis of fMRI data.
  https://doi.org/10.1016/j.tics.2006.07.005
* Kriegeskorte, Goebel & Bandettini (2006), PNAS 103:3863-3868. [searchlights]
  Information-based functional brain mapping.
  https://doi.org/10.1073/pnas.0600244103
* Varma & Simon (2006), BMC Bioinformatics 7:91. [nested cross-validation]
  Bias in error estimation when using cross-validation for model selection.
  https://doi.org/10.1186/1471-2105-7-91
* Hoerl & Kennard (1970), Technometrics 12:55-67. [ridge regression]
  Ridge regression: biased estimation for nonorthogonal problems.
  https://doi.org/10.1080/00401706.1970.10488634
* Zou & Hastie (2005), J R Stat Soc B 67:301-320. [elastic net]
  Regularization and variable selection via the elastic net.
  https://doi.org/10.1111/j.1467-9868.2005.00503.x
* Friedman, Hastie & Tibshirani (2010), J Stat Softw 33(1):1-22.
  Regularization paths for generalized linear models via coordinate descent.
  https://doi.org/10.18637/jss.v033.i01 [penalized regression/logistic models]
* Hsieh et al. (2008), ICML:408-415. [linear SVM dual coordinate descent]
  A dual coordinate descent method for large-scale linear SVM.
  https://doi.org/10.1145/1390156.1390208
* Ho & Lin (2012), J Mach Learn Res 13:3323-3348. [linear SVR]
  Large-scale linear support vector regression.
  https://www.jmlr.org/papers/v13/ho12a.html
* Dupre la Tour, Eickenberg, Nunez-Elizalde & Gallant (2022),
  NeuroImage 264:119728. [banded ridge encoding]
  Feature-space selection with banded ridge regression.
  https://doi.org/10.1016/j.neuroimage.2022.119728
* Wold, Sjostrom & Eriksson (2001), Chemom Intell Lab Syst 58:109-130.
  PLS-regression: a basic tool of chemometrics. [PLS regression]
  https://doi.org/10.1016/S0169-7439(01)00155-1
* Jolliffe & Cadima (2016), Philos Trans R Soc A 374:20150202. [PCA]
  Principal component analysis: a review and recent developments.
  https://doi.org/10.1098/rsta.2015.0202
* Haufe et al. (2014), NeuroImage 87:96-110. [activation patterns]
  On the interpretation of weight vectors of linear models in multivariate
  neuroimaging. https://doi.org/10.1016/j.neuroimage.2013.10.067
* Winkler et al. (2014), NeuroImage 92:381-397.
  Permutation inference for the general linear model.
  [permutation inference and exchangeability]
  https://doi.org/10.1016/j.neuroimage.2014.01.060
* Stelzer, Chen & Turner (2013), NeuroImage 65:69-82.
  Statistical inference and multiple testing correction in classification-based
  multi-voxel pattern analysis (MVPA): random permutations and cluster size
  control. [MVPA searchlight inference background]
  https://doi.org/10.1016/j.neuroimage.2012.09.063
* Phipson & Smyth (2010), Stat Appl Genet Mol Biol 9:39.
  Permutation P-values should never be zero: calculating exact P-values
  when permutations are randomly drawn. [nonzero permutation p-values]
  https://doi.org/10.2202/1544-6115.1585
* Nichols & Holmes (2002), Hum Brain Mapp 15:1-25. [permutation/max-FWE]
  Nonparametric permutation tests for functional neuroimaging:
  a primer with examples. https://doi.org/10.1002/hbm.1058
* Benjamini & Hochberg (1995), J R Stat Soc B 57:289-300. [FDR]
  Controlling the false discovery rate: a practical and powerful approach
  to multiple testing. https://doi.org/10.1111/j.2517-6161.1995.tb02031.x

-- P Molfese, December 2026

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