| --- |
| license: cc-by-nc-nd-4.0 |
| tags: |
| - single-cell |
| - temporal-dynamics |
| - flow-matching |
| - transcriptomics |
| --- |
| |
| # 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 |
|
|
| ```bash |
| 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. |
|
|
| ```bash |
| 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. |
|
|
