---
license: cc-by-nc-nd-4.0
tags:
- single-cell
- temporal-dynamics
- flow-matching
- transcriptomics
---

# TRACE — Transcriptional Regulator-Modulated Reference Geometry

![TRACE method overview](figures/TRACE_method.png)


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.