From 8c0a85e33b5b675b35423fc59216a652094579c8 Mon Sep 17 00:00:00 2001 From: Benjamin Nemoz Date: Wed, 18 Nov 2026 14:42:49 +0000 Subject: [PATCH] SimPlex: expression_sigma knob (per-cell expression heterogeneity, default off) Each cell's molecule means (both chains) are scaled by a mean-1 lognormal factor exp(sigma*Z - sigma^2/2) from its own "expression" RNG stream, so a few plasmablast-like cells own most molecules and hence most ambient copies. sigma=0 is bit-identical to before. Motivation (H2, diagnosis/simplex_v2d): in real princeps memory data a barcode's top heavy often comes from a heavy source spread over many barcodes (16-35% vs 0.5% in sim). sigma=2.5 reproduces this and the pooled < per-well precision reversal; jackpots (H1) and extra ambient light (H3) do not. Co-Authored-By: Claude Opus 5.5 --- simplex/config.py | 6 +++++- simplex/molecules.py | 10 ++++++++-- simplex/run.py | 6 +++++- simplex/tests/test_v2_knobs.py | 20 ++++++++++++++++++++ 4 files changed, 38 insertions(+), 4 deletions(-) diff --git a/simplex/config.py b/simplex/config.py index 73ecb48..684f2dd 100644 --- a/simplex/config.py +++ b/simplex/config.py @@ -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). """ @@ -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") @@ -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 diff --git a/simplex/molecules.py b/simplex/molecules.py index b5f0bcb..99f9d59 100644 --- a/simplex/molecules.py +++ b/simplex/molecules.py @@ -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 @@ -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 @@ -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) "Path": @@ -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 @@ -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, diff --git a/simplex/tests/test_v2_knobs.py b/simplex/tests/test_v2_knobs.py index 549b198..f1e9e43 100644 --- a/simplex/tests/test_v2_knobs.py +++ b/simplex/tests/test_v2_knobs.py @@ -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)