TRACE — Transcriptional Regulator-Modulated Reference Geometry

TRACE modulates the reference path of temporal single-cell conditional flow matching using transcription-factor regulon derivatives. It first couples retained population snapshots with balanced optimal transport, constructs PCHIP/Hermite reference paths, maps regulon activity derivatives into PCA coordinates with a ridge fit (Z pprox AW+b), calibrates their norms, and blends the mapped tangents with geometric PCHIP tangents before shape-preserving projection.

This is an initial code-only release. Input matrices, frozen TF-target prior, and third-party benchmark implementations are not included.

Submitted TRACE configuration

Parameter	Value
Optimization steps	4,000
TF steering coefficient (rho)	1.0
Ridge regularization (\lambda)	1.0
Latent PCA dimensions	30
Hidden layers / width	3 / 256
Activation / time encoding	SiLU / 8 Fourier frequencies
Learning rate / optimizer	0.001 / Adam
Batch size	128
Held-out repeats	5 (seeds 0–4)
ODE integration	50 Euler steps
OT	Balanced EMD, squared Euclidean cost

Files

• biochime_regulon_core.py — method core implementing TRACE
• benchmark_table.py — original neural field, OT, reference path and Euler integration helpers.
• run_trace_benchmark.py — simplified runner for linear CFM, PCHIP cubic CFM, TRACE, and paired regulatory permutations.
• tests/test_trace_core.py — numerical unit tests for spline, shape-projection and ridge helpers.

Install and test

python -m pip install -r requirements.txt
python -m unittest discover -s tests -v

Run a Gupta day-7 holdout

Provide the study-specific input files (not distributed with this initial release):

• inputs/gupta_hvg_matrix.npz containing X (cells × genes), t (biological time), var_names (gene names), and optionally used_scale.
• inputs/tcell_regulatory_prior_frozen29.csv with signed TF-target edges; see RegulonScorer for required columns and coverage rules.

python run_trace_benchmark.py \
  --mat inputs/gupta_hvg_matrix.npz \
  --prior inputs/tcell_regulatory_prior_frozen29.csv \
  --holdouts 7 \
  --steps 4000 --rho 1.0 \
  --folds 5 --ncomp 30 --batch 128 --ridge 1.0 \
  --candidate_source all --edge_weight_mode sign \
  --tag results/gupta_d7

The runner produces fold-level results, mean ± population-SD summaries, and TF coverage tables. For external experiments, keep --rho 1.0 fixed and provide Giles/DSM matrices with holdouts 8,15 and 8,28, respectively.

Reproducibility limitations

• The original uploaded src/ archive did not include the data preparation / NPZ construction scripts or frozen signed prior, so the exact 29-TF panel and initial gene selection cannot yet be independently recreated from this package.
• benchmark_table.ot_plan() attempts exact EMD but has an approximate fallback if EMD fails. Confirm whether the fallback was triggered in archived paper runs before claiming exact reproduction.
• This release does not yet reproduce all manuscript components (Slingshot curvature, external method baselines, interpolation-family ablations, or saved checkpoints).

Licensing

The present Hub metadata retains the repository's CC BY-NC-ND 4.0 designation, which restricts derivative works and may not be the desired license for software; confirm the final code license with the lab before public release.