AFNI program: 1dXmatTool

Output of -help

1dXmatTool: manipulate AFNI X.xmat.1D design matrices

Split a multi-run 3dDeconvolve design into run-local matrices:
  1dXmatTool -infile X.xmat.1D -uncensored X.nocensor.xmat.1D \
             -split_runs -prefix split/X

Operations (one at a time; -describe and -validate may be combined):
  -describe / -show  Full-matrix and per-run rank, DF, censor/stimulus summary.
  -validate         As above; exit 2 for failed checks, 0 for pass.
  -for lss|reml     With validation: check per-run LSS trial-model ranks, or
                    full/per-run GLM rank and residual degrees of freedom.
  -rank_tol T       Relative singular-value cutoff on unit-norm columns
                    (default 1e-7). Duplicate pairs use 1-abs(cosine)<=T.
  -json FILE        Optional JSON report with describe/validate.
  -select_columns LIST  Zero-based column indices, e.g. 0..3,8,10.
  -select_labels LIST   Exact comma-separated ColumnLabels.
  -select_stimuli LIST  Exact comma-separated StimLabels.
  -select_groups LIST   baseline (-1), nuisance (0), stimuli (>0), or group IDs.
                    Selections combine by union; original column order stays.
                    Writes PREFIX.xmat.1D, .rows.1D and .columns.1D.
  -drop_glts        Required for selection when input contains GLTs.
  -compare FILE     Match unique column labels/full TR indices; distinguish
                    reorder, censor/run/stimulus changes and changed values.
                    Exit 2 for differences, 0 for equivalence (reordering OK).
  -atol A -rtol R   Comparison tolerance A+R*max(abs(a),abs(b)); default 1e-6.
  -export_manifest  Write PREFIX.trials.1D from an IM design plus explicit events.
  -events FILE      Header/table: Run Volume Condition [Item]; complete unique
                    keys; Run one-based, Volume zero-based within each run.
  -subject ID       Subject label for the manifest.
  -beta FILE        Single-run beta bucket, or use -beta_pattern for many runs.
  -beta_pattern P   One {run} placeholder, replaced by 01,02,... (quote it).
  -manifest_format manifest|selected  Default manifest: whole InputFile plus
                    Volume for 3dMVPA -trial_manifest. selected: InputFile[n]
                    for direct 3dMVPA/3dRSA/3dSRM tables. Files need not yet exist.
                    Conditions are supplied by you, never guessed from IM labels.
Inputs/splitting:
  -infile FILE       NIML-comment matrix from 3dDeconvolve.
  -split_runs        Extract runs, preserving values and column order.
  -prefix PREFIX    Output prefix; its directory must already exist.
Optional:
  -uncensored FILE  Matching full-row design, recommended with censoring.
                    Determines column support before censoring. Dimensions,
                    labels, stimuli, run starts and retained values must match.
  -runs LIST        One-based run numbers, e.g. '1,3..5' (default: all).
  -zero_tol T       Relative support threshold, 0 <= T < 1 (default: 1e-6).
                    A column's peak within a run must exceed T times its
                    global peak. Use 0 for exact nonzero support.
  -help             This help.

Outputs (r01 denotes the original, one-based run number):
  PREFIX.r01.xmat.1D    Run matrix with local GoodList, NRowFull, RunStart=0,
                       ColumnGroups and remapped stimulus/Basis metadata.
  PREFIX.r01.rows.1D   Row, SourceRow, RunTR, SourceTR (all zero-based).
  PREFIX.r01.columns.1D  Every input column, including dropped columns;
                       numeric columns only; labels in # ColumnLabel comments.
                       local Column/Stim/IMVolume are -1 when unavailable.
                       IMVolume is within the corresponding IM stimulus,
                       and is the LSS volume when there is one IM stimulus.
  PREFIX.runs.1D       Original run number, start TR, full length, retained
                       rows and columns; output paths are in # RunFiles comments.
Comment text escapes backslash, tab, newline and CR as \\, \t, \n and \r.
All mappings refer to the immediate input file. Matrix headers also record
XmatSource* indices and the support file/tolerance. No files are overwritten.
All selected runs are checked before writing. Existing outputs cause failure.

Policy:
* Requires explicit RunStart, NRowFull and GoodList. No timing is guessed.
* Drops columns inactive in the selected run; retains shared nuisance columns.
  Does not refit, normalize or demean. Values retain thd_xmat float precision;
  original double-precision text is not preserved beyond that precision.
* IM columns must belong to exactly one run. Zero/cross-run IM support, or
  loss of an IM column's support after censoring, is an error. Fully censored
  runs also fail. Without -uncensored, support is known only in retained rows.
* Rebuilds stimulus ranges; preserves column labels and per-stimulus Basis
  attributes. Drops GLTs and ColumnMasks (and records their removal).
* Extraction does not establish full rank or satisfy every downstream tool.
  3dLSS still requires exactly one IM stimulus and sufficient observations.

Example downstream use (run 1, full-length per-run scaled EPI):
  3dLSS -matrix split/X.r01.xmat.1D \
        -input pb03.SUBJ.r01.scale+orig -prefix LSS.r01
Use the matching run's FULL time series: 3dLSS applies the local GoodList.
Do not concatenate censored rows or feed the entire multi-run dataset.
This tool splits an existing design; it does not create new regressors.
This page auto-generated on Sat Oct 31 01:54:18 AM EDT 2026