Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion simplex/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,9 @@ class SimplexConfig:
in OTHER droplets (new barcode + UMI, random well), as `ambient_rate` x cell molecules;
`umi_sub_rate` adds per-read UMI substitution errors (uncorrected UMIs inflate support);
`reads_per_molecule_dispersion` makes read-family depth negative binomial (PCR jackpots; 0 = Poisson);
`reads_per_molecule_mean_light` sets a separate read-family mean for light chains.
`reads_per_molecule_mean_light` sets a separate read-family mean for light chains;
`expression_sigma` scales each cell's molecule means by a mean-1 lognormal factor (expression heterogeneity:
a few plasmablast-like cells own most molecules, hence most ambient copies).
- **Bookkeeping**: `write_read_truth` (also persist a per-read truth parquet —
expensive, off by default), `seed` (root seed for all per-stage RNG streams).
"""
Expand Down Expand Up @@ -89,6 +91,7 @@ class SimplexConfig:
tso_sub_rate: float = 0.0
tso_g_run_probs: list | None = None
tso_indel_rate: float = 0.0
expression_sigma: float = 0.0

_RATES=("recovery_rate","release_rate","molecule_survival_rate","rt_sub_rate","rt_indel_rate",
"sequencing_sub_rate","sequencing_indel_rate","index_hop_rate","rc_fraction","umi_sub_rate")
Expand Down Expand Up @@ -139,6 +142,7 @@ def validate(self, actual_n_cells=None, max_reads=3_000_000_000):
if self.ambient_rate<0: raise ValueError("ambient_rate must be >= 0")
if self.reads_per_molecule_dispersion<0: raise ValueError("reads_per_molecule_dispersion must be >= 0")
if self.junk_rate<0: raise ValueError("junk_rate must be >= 0")
if self.expression_sigma<0: raise ValueError("expression_sigma must be >= 0")
for r in ("barcode_sub_rate","tso_sub_rate","tso_indel_rate"):
if not (0.0<=getattr(self,r)<=1.0): raise ValueError(f"{r} not in [0,1]")
jl,jh=self.junk_length
Expand Down
10 changes: 8 additions & 2 deletions simplex/molecules.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
"survived":pl.Boolean,"cdna":pl.Utf8,"is_ambient":pl.Boolean}
def generate_molecules(cells,recovery_rate,molecules_per_chain_mean,release_rate,umi_length,rt_sub_rate,rt_indel_rate,seed,
release_rate_heavy=None,release_rate_light=None,molecules_per_chain_mean_light=None,
ambient_rate=0.0,junk_rate=0.0,junk_length=(80,300)):
ambient_rate=0.0,junk_rate=0.0,junk_length=(80,300),expression_sigma=0.0):
"""Simulate RT capture per cell/chain and split molecules into resident vs free (ambient).

For each chain (0, 1) independently: each cell captures the chain with probability
Expand Down Expand Up @@ -43,6 +43,10 @@ def generate_molecules(cells,recovery_rate,molecules_per_chain_mean,release_rate
and is free (`is_free=True`, routed to a random well) with `is_ambient=True`. Unlike release,
ambient ADDS molecules and moves a chain to a different barcode.

Expression heterogeneity (`expression_sigma`, default 0): each cell's molecule means (both chains) are scaled by
a mean-1 lognormal factor `exp(sigma*Z - sigma**2/2)` drawn from its own `"expression"` RNG stream, so a few
high-expressing cells (plasmablast-like) own most molecules, and therefore most ambient copies.

Junk axis (`junk_rate`, default 0): non-Ig library molecules (mispriming, primer artefacts) with a valid barcode.
`Poisson(junk_rate * n_cell_molecules)` molecules, each owned by the cell of a uniformly chosen cell molecule
(barcode, home well), random sequence of uniform length in `junk_length`, released like that cell's chains at
Expand All @@ -55,12 +59,14 @@ def generate_molecules(cells,recovery_rate,molecules_per_chain_mean,release_rate
is one row per `(cell_id, chain)` with `captured`/`n_molecules`, used by `truth.build_truth_cells`.
"""
rng=rng_for(seed,"molecules"); n=cells.height; frames=[]; status=[]
expr=(np.exp(expression_sigma*rng_for(seed,"expression").standard_normal(n)-expression_sigma**2/2)
if expression_sigma>0 else np.ones(n))
def _is_light(chain):
return cells[f"chain{chain}_locus"].is_in(["IGK","IGL"]).to_numpy() if n else np.array([],bool)
for chain in (0,1):
light=_is_light(chain)
mean=np.where(light, molecules_per_chain_mean if molecules_per_chain_mean_light is None else molecules_per_chain_mean_light,
molecules_per_chain_mean)
molecules_per_chain_mean)*expr
captured=rng.random(n)<recovery_rate
nmol=np.where(captured,np.maximum(rng.poisson(mean),1),0).astype(np.int64)
status.append(pl.DataFrame({"cell_id":cells["cell_id"],"chain":np.full(n,chain,np.int8),"captured":captured,"n_molecules":nmol}))
Expand Down
6 changes: 5 additions & 1 deletion simplex/run.py
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ def run(
tso_sub_rate: float = 0.0,
tso_g_run_probs: list | None = None,
tso_indel_rate: float = 0.0,
expression_sigma: float = 0.0,
quiet: bool = False,
verbose: bool = False,
) -> "Path":
Expand Down Expand Up @@ -201,6 +202,9 @@ def run(
Probabilities of 0, 1, 2, ... G after the TSO body (default: the fixed GGG).
tso_indel_rate : float, default 0.0
Share of reads with a 1-3 nt indel in the TSO body (shifts where the parser's fixed offset lands).
expression_sigma : float, default 0.0
Per-cell expression heterogeneity: both chains' molecule means are scaled by a mean-1 lognormal factor
``exp(sigma*Z - sigma**2/2)``. High expressors own most molecules and therefore most ambient copies.
quiet : bool, default False
Suppress the tqdm progress bars and drop logging to WARNING (silent run).
verbose : bool, default False
Expand Down Expand Up @@ -243,7 +247,7 @@ def run(
mols, chain_status=generate_molecules(cells, cfg.recovery_rate, cfg.molecules_per_chain_mean, cfg.release_rate, cfg.umi_length, cfg.rt_sub_rate, cfg.rt_indel_rate, cfg.seed,
release_rate_heavy=cfg.release_rate_heavy, release_rate_light=cfg.release_rate_light,
molecules_per_chain_mean_light=cfg.molecules_per_chain_mean_light, ambient_rate=cfg.ambient_rate,
junk_rate=cfg.junk_rate, junk_length=tuple(cfg.junk_length))
junk_rate=cfg.junk_rate, junk_length=tuple(cfg.junk_length), expression_sigma=cfg.expression_sigma)
logger.info("[4/9] generated %d molecules (%d free, %d ambient)", mols.height, int(mols["is_free"].sum()) if mols.height else 0,
int(mols["is_ambient"].sum()) if mols.height else 0); bar.update(1)
mols, reads=route_and_amplify(mols, cfg.wells, cfg.molecule_survival_rate, cfg.reads_per_molecule_mean, cfg.index_hop_rate, cfg.seed,
Expand Down
20 changes: 20 additions & 0 deletions simplex/tests/test_v2_knobs.py
Original file line number Diff line number Diff line change
Expand Up @@ -226,3 +226,23 @@ def test_read_structure_knobs_default_identical_and_effective():
after = m["read_seq"].str.slice(36, 2)
assert set(after.to_list()) <= {"GA", "GG", "GT", "GC", "AT", "GA"} or True
assert (m["read_seq"].str.len_chars() < a["read_seq"].str.len_chars()).mean() > 0.3 # shorter G-runs


# --- expression heterogeneity (H2: spreader heavies) -------------------------
def test_expression_sigma_zero_identical_and_heavy_tail_same_mean():
a, _ = generate_molecules(_cells(3000), 1.0, 6.0, 0.2, 10, 0.0, 0.0, 1)
b, _ = generate_molecules(_cells(3000), 1.0, 6.0, 0.2, 10, 0.0, 0.0, 1, expression_sigma=0.0)
assert a.equals(b)
c, _ = generate_molecules(_cells(3000), 1.0, 6.0, 0.2, 10, 0.0, 0.0, 1, expression_sigma=1.5)
per_a = a.group_by("origin_cell_id").len()["len"]; per_c = c.group_by("origin_cell_id").len()["len"]
assert abs(c.height / a.height - 1) < 0.15 # mean preserved
assert per_c.quantile(0.99) > 2 * per_a.quantile(0.99) # heavy tail of per-cell molecules
# both chains of a cell share its factor
hl = c.group_by("origin_cell_id", "chain").len().pivot(on="chain", index="origin_cell_id", values="len").drop_nulls()
assert np.corrcoef(np.log(hl["0"].to_numpy()), np.log(hl["1"].to_numpy()))[0, 1] > 0.5


def test_config_validates_hypothesis_knobs(tmp_path):
for bad in (dict(expression_sigma=-0.1),):
with pytest.raises(ValueError):
SimplexConfig(input_data="x", output_directory=str(tmp_path), **bad).validate(actual_n_cells=10)