1dTrdm: labeled temporal representational-dissimilarity movies
OVERVIEW
--------
1dTrdm follows how the geometry of experimental conditions changes over
time. At each latency or time window, it averages independently estimated
observations into condition patterns and converts those patterns into a
representational dissimilarity matrix (RDM). The resulting RDM movie shows
when conditions become distinguishable, when a hypothesized organization
emerges, and whether an earlier representational geometry later recurs.
This organization is especially useful for EEG and MEG analyses. Each input
observation can be an epoched trial or independently estimated trial pattern,
with time along rows and sensors, source vertices, frequency features, or
other measurements along columns. The same contract can also describe ECoG,
intracranial recordings, time-resolved fMRI beta estimates, or any labeled
feature-by-time data. 1dTrdm operates on prepared numeric matrices: artifact
handling, epoching, baseline correction, and first-level trial estimation
remain in the acquisition/preprocessing software best suited to the modality.
There are four related questions the program can address:
1. RDM movie | What is the condition geometry at each time/window?
2. Model inference | When does that geometry match a labeled model RDM?
3. RDM dynamics | Does a representational geometry persist or recur?
4. Cross-time | Does a condition contrast generalize across times
crossnobis | when estimated in independent partitions?
The last two are symmetric descriptive RSA products. They are not classifier
train-time x test-time decoding. Subject sign flips or synchronized condition
relabeling provide corrected inference for the one-time fixed-model series;
cross-temporal inference is not performed in this release.
Usage:
1dTrdm -dataTable DATA.txt -time_axis TIME.txt -feature_axis FEAT.txt \
-metric corr|cosine|euclid|crossnobis -prefix OUT [options]
1dTrdm -dataTable DATA.txt -input_format labeled \
-metric corr|cosine|euclid|crossnobis -prefix OUT [options]
DATA.txt has one independently estimated observation per row:
Subj Observation Condition Partition InputFile
s01 tr0001 face run1 s01_tr0001.1D
Subj, Observation, Condition and InputFile are required. Observation IDs are
unique within subject. Partition is optional for ordinary RDMs and required
for crossnobis. InputFile is time rows x feature columns; every input must
have the same finite shape. Relative paths resolve beside DATA.txt.
TIME.txt is a strict four-column table with one row per input time sample:
time_index time_value time_unit time_label
0 -0.100 s -100ms
1 0.000 s 0ms
Indices are zero-based/contiguous, values finite/strictly increasing, one unit
applies to the axis, and labels are unique. FEAT.txt has at least one unique
feature_label column. Optional metadata are retained but never treated as
implicit adjacency; -feature_neighborhoods supplies the explicit graph.
LABELED OBSERVATION SHORTCUT
With -input_format labeled, each InputFile is a whitespace-delimited table:
time_value time_unit time_label Fz Cz Pz
-100 ms m100 0.2 0.5 0.1
-98 ms m098 0.3 0.4 0.2
The header may also be written as '# Columns: ...'. time_value and time_unit
are required. time_label is optional; absent labels inherit the established
axis, or are generated as numeric value plus unit (e.g., -100ms). Optional
time_index must be zero-based and contiguous; otherwise it is generated.
Every remaining column is a numeric feature. Column names must be unique
even ignoring case; feature identities match exactly, including case.
Subj and InputFile are reserved for the observation table. Names, time units,
and time labels must be nonempty single tokens. Values must be finite.
-time_axis and -feature_axis may each be omitted in this format. The first
observation establishes each omitted axis. Later files must have identical
time values/units and the same feature names; feature columns are reordered
by name. No time sorting, resampling, unit conversion, or missing-feature
filling is performed. Supplied axis files establish the canonical axes:
embedded values and any explicit time labels must agree with them.
The observation table still supplies Subj, Observation, Condition, Partition
(when needed), and InputFile. Outputs retain the resolved axes and sources.
NEIGH.txt is a strict two-column membership graph; overlaps are allowed:
Neighborhood Feature
left_temporal MEG0111
left_temporal MEG0121
posterior MEG0121
Each Feature must match FEAT.txt. Neighborhood and membership row order do
not affect results. No coordinate system or column adjacency is inferred.
Metrics:
corr 1 - Pearson correlation between condition patterns
cosine 1 - cosine similarity
euclid Euclidean distance
crossnobis crossvalidated squared Euclidean over independent partitions;
every subject x partition must contain every condition
Options:
-dataTable FILE observation table (required); columns are Subj,
Observation, Condition, optional Partition, and InputFile
-input_format numeric|labeled
numeric [default] requires separate time/feature axes;
labeled reads those axes from observation tables
-prefix OUT output filename prefix (required)
-window_width N samples per output window [1]
-window_step N samples between window starts [1]
-window_reduce mean|concat
mean features over samples [default], or concatenate
sample x feature values in time-major order
-center_conditions none|subject|partition
none [default]; subject is ordinary-RDM cocktail-blank
removal after condition averaging; partition applies
the same operation separately in every crossnobis fold
-feature_neighborhoods NEIGH.txt
add an explicit, possibly overlapping feature search;
NEIGH.txt has exactly Neighborhood Feature columns,
with one membership per row. Feature labels must occur
in FEAT.txt; row order and column adjacency are ignored.
-model_series_out independent|paired|loo
write an ordered model series for downstream 3dRSA.
independent averages all subjects and writes the existing
two-column fixed-model series. paired writes a Subj x Time
manifest pointing to each subject's own RDM movie. loo
writes a Subj x Time manifest whose model for each subject
is the mean RDM of every OTHER subject. Both require at
least two subjects; paired also requires subject matrices. All
three are all-feature bridges and reject neighborhoods.
-rdm_dynamics pearson|spearman
correlate each subject's RDM triangles across every
pair of output windows (representational recurrence)
-cross_time_crossnobis
for -metric crossnobis, estimate each condition dyad
across pairs of windows using ordered independent
partition pairs; diagonal equals the primary RDM
-model_mat MODEL.1D -model_conditions MODEL_CONDITIONS.1D
compare each subject/window RDM with one labeled fixed
condition-dissimilarity model and run temporal inference
-compare spearman|pearson
RDM-triangle comparison [spearman]
-temporal_null subjects|conditions
subjects [default] tests a population using synchronized
subject sign flips and the one-sample t of Fisher-z fits;
conditions applies one condition relabeling to every
subject/window and tests the fixed observed sample
-nperm N requested null draws [10000]; small groups are exact
-seed S random-draw seed [1234567]
-subject_matrices yes|no
also write each subject/window square matrix [yes]
-matrix_format numeric|labeled
square output format [numeric]. labeled writes a
Condition header and row labels for RDMs, or a Time
header and window labels for dynamics matrices.
Applies to subject, neighborhood, group and LOO
matrices; does not change long tables or input format.
-jobs N OpenMP workers when available [runtime default]
-quiet suppress informational messages
-help show this help
OUTPUTS
-------
Output file | Written when | Contents
-----------------------------------------|--------------------|-----------------------------
OUT.trdm.1D | always | subject x time x RDM dyads
OUT.trdm.meta | always | estimator/axis provenance
OUT.trdm.time.1D | always | windows and member bounds
OUT.trdm.conditions.1D | always | lexical condition axis
OUT.trdm.features.1D | always | input feature axis
OUT.trdm.counts.1D | always | observations per estimate
OUT.trdm.neighborhoods.1D | -feature_... | neighborhood RDM movie
OUT.trdm.neighborhood_axis.1D | -feature_... | graph memberships/axis
OUT_s####_<SUBJ>_t####.1D | matrices=yes | subject/window square RDM
-----------------------------------------|--------------------|-----------------------------
OUT.trdm.fits.1D | -model_mat | subject fixed-model fits
OUT.trdm.inference.1D | -model_mat | time-family p/q/max-FWE
OUT.model_series.1D | independent bridge | ordered RDM list for 3dRSA
OUT_group_t####.1D | independent bridge | group-mean fixed model RDM
OUT.paired_model_series.1D | paired bridge | Subj x Time own-RDM manifest
OUT.loo_model_series.1D | LOO bridge | Subj x Time held-out manifest
OUT_loo_s####_<SUBJ>_t####.1D | LOO bridge | mean RDM excluding that subject
-----------------------------------------|--------------------|-----------------------------
OUT.trdm.dynamics.1D | -rdm_dynamics | unique time x time recurrence
OUT_s####_<SUBJ>_dynamics.1D | dynamics+matrices | mirrored recurrence matrix
OUT.trdm.cross_time_crossnobis.1D | -cross_time_... | time x time x condition dyad
OUT.trdm.neighborhood_{fits,inference}.1D| graph + model | joint time x graph inference
OUT.trdm.neighborhood_dynamics.1D | graph + dynamics | recurrence within each graph
OUT.trdm.neighborhood_cross_time_...1D | graph + cross-time | crossnobis within each graph
With -matrix_format labeled, square files retain their usual filenames but
contain a labeled table, for example (illustrative distances):
# matrix_format labeled
# matrix_kind dissimilarity
# Columns: Condition face house tool
face 0 0.8 0.6
house 0.8 0 0.3
tool 0.6 0.3 0
Both axes carry the exact condition labels, with quoting when necessary.
Values use nine significant digits to preserve float precision, including
negative crossnobis estimates. Dynamics tables have matrix_kind similarity
and Time axes; their diagonal is similarity, not a zero RDM diagonal.
3dRSA reads these labeled condition matrices through -input_rdm for
nonspatial IS-RSA, or -model_rdm LABEL COLUMN beside fMRI InputFile entries
for classic/IS-RSA fusion. See 3dRSA examples 3 and 6 for both workflows.
Model-series manifests point to the selected format. Use numeric for
3dRSA -model_series, -model_series_subjects and -model_mat: those readers
still require numeric matrices in the declared analysis order.
MODEL_CONDITIONS.1D is a strict two-column table in MODEL.1D row order:
ConditionIndex Condition
0 face
Labels must match the observation conditions exactly; arbitrary model order
is realigned by label. Inference Effect is tanh(mean subject Fisher-z fit).
For the subject null Stat is its one-sample t; for the condition null Stat is
mean Fisher z. P is two-sided empirical. Q and PFWE span the complete time
family, or the complete time x neighborhood family when a graph is supplied;
PFWE uses one synchronized maximum-statistic null over every declared cell.
EXAMPLE 1: LABELED EEG TRIALS -> LABELED CONDITION RDMs
---------------------------------------------------
Keep trial identity and experimental design in eeg_observations.txt:
Subj Observation Condition InputFile
s01 trial001 face s01_face_01.1D
s01 trial002 house s01_house_01.1D
s01 trial003 tool s01_tool_01.1D
s01 trial004 face s01_face_02.1D
Add further trials/subjects as appropriate. Each subject needs every
condition. Paths resolve beside eeg_observations.txt. A trial file contains
one row per latency and one measurement column per sensor, for example:
time_value time_unit time_label Fz Cz Pz
-100 ms m100 0.2 0.5 0.1
0 ms zero 0.4 0.1 0.3
100 ms p100 1.2 0.7 0.2
These three rows illustrate the format; real epochs include every desired
sample. Use the same time values, units and labels in every trial. Reordered
sensor columns are matched by name; missing sensors are errors.
1dTrdm -dataTable eeg_observations.txt -input_format labeled \
-metric corr -matrix_format labeled -prefix eeg
The program averages trials within condition and subject, then compares
sensor patterns at each latency. eeg_s0000_s01_t0002.1D is a labeled
face/house/tool RDM for 100 ms. eeg.trdm.1D also records the explicit p100
label. Subject indices follow lexical subject order.
EXAMPLE 2: MEG WITH GENERATED TIME LABELS AND INDEPENDENT RUNS
----------------------------------------------------------
A prepared MEG observation can omit time_label and time_index:
# Columns: time_value time_unit MEG0111 MEG0121 MEG0131
-100 ms 1.2e-13 0.5e-13 -0.3e-13
0 ms 1.4e-13 -0.2e-13 0.7e-13
100 ms 2.1e-13 0.9e-13 0.1e-13
Generated labels are -100ms, 0ms, 100ms. Use consistently scaled channels;
mixing sensor types with different units requires upstream preparation.
For crossnobis, the observation table also identifies independent partitions:
Subj Observation Condition Partition InputFile
s01 trial001 face run1 s01_r1_face.1D
s01 trial002 house run1 s01_r1_house.1D
s01 trial003 tool run1 s01_r1_tool.1D
s01 trial004 face run2 s01_r2_face.1D
s01 trial005 house run2 s01_r2_house.1D
s01 trial006 tool run2 s01_r2_tool.1D
1dTrdm -dataTable meg_observations.txt -input_format labeled \
-metric crossnobis -matrix_format labeled -prefix meg
Every subject/partition must contain every condition; multiple trials per
cell are averaged within partition. Crossnobis here is crossvalidated squared
Euclidean distance, without estimated noise whitening. Negative estimates
are retained. Run labels must reflect independent estimates, not duplicate
copies of the same trial.
EXAMPLE 3: WINDOWS, SENSOR GROUPS, AND EXISTING AXIS FILES
------------------------------------------------------
For data sampled every 2 ms, this averages five samples per window and
advances one sample at a time (window options count SAMPLES, not ms):
1dTrdm -dataTable eeg_observations.txt -input_format labeled \
-metric corr -window_width 5 -window_step 1 -window_reduce mean \
-feature_neighborhoods sensor_groups.txt \
-matrix_format labeled -prefix eeg_windows
sensor_groups.txt explicitly names sensor membership, including overlaps:
Neighborhood Feature
frontocentral Fz
frontocentral Cz
centroparietal Cz
centroparietal Pz
Window labels become w0000, w0001, ...; the time sidecar preserves the
original sample bounds and mean time. Source-vertex or sensor-frequency
features work the same way: use unique column names such as lh_v001 or
Fz_alpha, with identical feature definitions across observations.
To enforce an existing axis convention, add -time_axis TIME.txt and/or
-feature_axis FEAT.txt. Embedded labels/values must agree. To keep legacy
numeric observations, omit -input_format labeled and supply both axis files.
Input and output formats are independent: labeled input can still write
numeric square matrices, and numeric input can write labeled matrices.
EXAMPLE 4: EEG/MEG RDM MOVIE -> fMRI RSA
--------------------------------------
First, turn an independently sampled EEG/MEG observation set into an ordered
fixed RDM series. The literal 'independent' assertion documents that these
subjects are not the subjects in the later fMRI analysis:
1dTrdm -dataTable meg_observations.txt \
-time_axis meg_time.txt -feature_axis meg_sensors.txt \
-metric crossnobis -center_conditions partition \
-model_series_out independent -prefix meg_rdm
Then use the generated ordered list as a time-resolved fixed model in 3dRSA:
3dRSA -mode RSA -dataTableFile fmri_conditions.txt \
-mask gray_mask+tlrc -model_series meg_rdm.model_series.1D \
-metric spearman -nperm 10000 -prefix meg_fmri_fusion
3dRSA then owns the joint time x ROI/searchlight inference family. If the
EEG/MEG and fMRI subjects overlap, use one of these dependent workflows.
Subject labels in the 1dTrdm and 3dRSA data tables must match exactly.
EXAMPLE 5: PAIRED EEG/MEG -> fMRI RSA (SAME SUBJECTS)
---------------------------------------------------
Each subject's EEG/MEG RDM is paired with that same subject's fMRI RDM:
1dTrdm -dataTable meg_observations.txt \
-time_axis meg_time.txt -feature_axis meg_sensors.txt \
-metric crossnobis -center_conditions partition \
-subject_matrices yes -model_series_out paired -prefix meg_rdm
3dRSA -mode RSA -dataTableFile fmri_conditions.txt \
-mask gray_mask+tlrc \
-model_series_subjects paired meg_rdm.paired_model_series.1D \
-metric spearman -classic_null subjects -nperm 10000 \
-prefix paired_meg_fmri_fusion
EXAMPLE 6: LEAVE-ONE-SUBJECT-OUT EEG/MEG -> fMRI RSA
-------------------------------------------------
Each fMRI subject is tested against the mean EEG/MEG RDM from every other
subject, so that subject never contributes to their own model:
1dTrdm -dataTable meg_observations.txt \
-time_axis meg_time.txt -feature_axis meg_sensors.txt \
-metric crossnobis -center_conditions partition \
-model_series_out loo -prefix meg_rdm
3dRSA -mode RSA -dataTableFile fmri_conditions.txt \
-mask gray_mask+tlrc \
-model_series_subjects loo meg_rdm.loo_model_series.1D \
-metric spearman -classic_null conditions -nperm 10000 \
-prefix loo_meg_fmri_fusion
The primary RDMs are subject-level. 1dTrdm does not estimate trial responses,
read raw FIF/SET/vendor formats, or implement decoding train/test
generalization. Cross-temporal outputs are descriptive in this release.
++ Compile date = Nov 17 2026 {AFNI_26.3.12:linux_ubuntu_24_64}