File size: 3,676 Bytes
6f2eb62 4c4d79d 6f2eb62 9459e83 4c4d79d 9459e83 7513e2a 9459e83 4e1992c 9459e83 a4e77da 9459e83 4c4d79d 9459e83 4c4d79d f46de6a 4c4d79d 4e1992c 4c4d79d 59be5c2 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 | ---
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.
|