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]
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.
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
-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]
-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
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: 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: 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: 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 = Sep 19 2026 {AFNI_26.2.09:linux_ubuntu_24_64}
