Simulated dose series#

Simulated dose series draw pseudobulk counts from known curves of expression along dose, with their truth; Simulated dose series with known curves explains them.

Simulated dose series: pseudobulk counts per cell type drawn from known curves of expression along dose, with the truth that estimates are compared with.

Whether a method finds the genes that respond to a dose, the shape of each response and the dose at which it starts can only be checked on data whose truth is known. The one published single-cell dose benchmark set the means of its responsive genes from the benchmark-dose equations of the US EPA, added the variation of 3 individuals per dose and compared tests on cells, without curves (Nault et al. 2022). simulate_dose_series() draws what the dose methods read, the counts of each replicate (an animal, or one donor’s cells in a well) in each cell type, with the effects of each replicate that muscat’s and scDesign3’s simulations also give (Crowell et al. 2020; Song et al. 2024); DoseTruth holds each gene’s true curve, EC50 and benchmark doses. The curves include shapes inside and outside the families of curves that BMDS (US EPA 2026), drc (Ritz et al. 2015) and DRomics (Delignette-Muller et al. 2023) fit, so that a method is not checked only on curves of its own form; Hill, sigmoid Emax and four-parameter log-logistic curves are one family (Kappenberg et al. 2023) (https://docs.nygen.io/CytePool/statistics/dose-response#simulated-dose-series).

References

Crowell HL, Soneson C, Germain PL, Calini D, Collin L, Raposo C, Malhotra D, Robinson MD (2020). muscat detects subpopulation-specific state transitions from multi-sample multi-condition single-cell transcriptomics data. Nature Communications 11, 6077. doi:10.1038/s41467-020-19894-4

Crump KS (1984). A new method for determining allowable daily intakes. Fundamental and Applied Toxicology 4, 854-871. doi:10.1016/0272-0590(84)90107-6

Delignette-Muller ML, Siberchicot A, Larras F, Billoir E (2023). DRomics, a workflow to exploit dose-response omics data in ecotoxicology. Peer Community Journal 3, e90. doi:10.24072/pcjournal.325

Kappenberg F, Duda JC, Schürmeyer L, Gül O, Brecklinghaus T, Hengstler JG, Schorning K, Rahnenführer J (2023). Guidance for statistical design and analysis of toxicological dose-response experiments, based on a comprehensive literature review. Archives of Toxicology 97, 2741-2761. doi:10.1007/s00204-023-03561-w

Nault R, Saha S, Bhattacharya S, Dodson J, Sinha S, Maiti T, Zacharewski T (2022). Benchmarking of a Bayesian single cell RNAseq differential gene expression test for dose-response study designs. Nucleic Acids Research 50, e48. doi:10.1093/nar/gkac019

Ritz C, Baty F, Streibig JC, Gerhard D (2015). Dose-response analysis using R. PLOS ONE 10, e0146021. doi:10.1371/journal.pone.0146021

Song D, Wang Q, Yan G, Liu T, Sun T, Li JJ (2024). scDesign3 generates realistic in silico data for multimodal single-cell and spatial omics. Nature Biotechnology 42, 247-252. doi:10.1038/s41587-023-01772-1

US EPA (2026). BMDS User Guide: continuous endpoints. Online documentation of BMDS Online, BMDS Desktop and pybmds 25.2. https://usepa.github.io/bmds-user-guide/continuous.html

cytepool.simulate_dose_series(doses, *, replicates=3, cell_types=2, cells=100.0, n_genes=1000, responsive=0.2, shapes=None, max_log2_changes=(0.5, 1.0, 2.0), biological_sd=0.25, donor_sd=None, composition=None, unit='ug/kg', metric='administered', rng=None)#

Draw a dose series of pseudobulk counts from known curves, with its truth.

Each cell type’s profile of each replicate sums the counts of a random number of cells. For cell type k, replicate s at dose d and gene g, with independent standard normal draws:

  • the expected counts of one cell at the vehicle, r = 0.1 exp(1.5 z_g + 0.5 z_gk), with z_g shared by the cell types, so that a gene is expressed at a similar level in each;

  • a factor v = exp(0.3 y_gk) on biological_sd and donor_sd, so that the genes’ SDs differ, log-normally;

  • the cells pooled, n ~ Poisson(cells c_k(d) exp(0.3 x_sk - 0.045)), with mean cells times the composition factor c_k(d), and the depth, e = exp(0.2 u_sk - 0.02), with mean 1;

  • the biological effect in log2 units, b = v (biological_sd eps_sgk + donor_sd eta_jgk), with eta shared by the replicates of donor j;

  • the counts, negative binomial with mean n e r 2^(f_gk(d) + b) and dispersion 0.5 / n, the sum of n cells of dispersion 0.5 each, so that profiles of fewer cells vary more beyond their counts; 0 where n = 0.

f is the gene’s true curve, a change in log2 expression from the vehicle that DoseTruth describes. A share responsive of the genes respond, rounded half up, the first of a random order of the genes, so that a larger share adds genes and keeps the others; their shapes follow the shares of shapes by the largest remainder (ties in the order given), the maximal changes max_log2_changes in turn within each shape, and rises and falls in turn within each shape and change, the first a rise, so that the counts of every shape, change and direction are exact. The dose of a 1.1-fold change of the hill, exponential, frechet and step curves is log-uniform from an eighth of the log10 span of the positive doses below the lowest to an eighth above the top dose, so that a tenth lies below the doses and a tenth above, and their EC50s follow from it; linear and power curves reach their maximal change at the top dose. Bells peak at a dose log-uniform over the positive doses, with an SD along log10 dose from 0.75 to 1.5 times the log10 gap between the positive doses on either side of the peak, so that nearly every bell exceeds half its peak at two or more doses, however the doses are spaced. Slopes are log-uniform from 0.5 to 4 (hill, frechet) and from 1 to 4 (power). Doses multiplied by a factor give EC50s, peak doses and benchmark doses multiplied by it.

The random draws come in independent streams: one for the levels the cell types share, and for each cell type one each for the genes’ levels and SD factors, the curves, the cells, the depths, the biological effects, the donor effects and the counts. A cell type’s curves, levels and SD factors therefore depend only on the seed, its position among the cell types, doses, n_genes, responsive, shapes and max_log2_changes: other replicates, cells, composition, biological_sd or donor_sd give the same genes, and so does adding a cell type, which compares designs on the same truth (https://docs.nygen.io/CytePool/statistics/dose-response#simulated-dose-series).

Parameters:
  • doses – The dose levels in unit, strictly increasing from 0, the vehicle, with at least two doses above 0, no two of which differ by less than 1e-8 of the dose.

  • replicates – The replicates of each dose: one number, or one per dose.

  • cell_types – How many cell types, named cell_type_1, cell_type_2, …, or their names.

  • cells – The expected number of cells pooled into a profile at a factor of 1 in composition: one number, or one per cell type. The Poisson mean of a profile is log-normal around it, with a median 4.4% lower and a coefficient of variation of 0.31, and counting the cells adds 1 / cells to the squared coefficient of variation.

  • n_genes – The genes, the same in every cell type, with ids gene_0001 to gene_1000 for 1,000 genes, padded with zeros to the width of n_genes.

  • responsive – The share of the genes that respond to dose: one number, or one per cell type; 0 gives a series without responses.

  • shapes – The shares of the curve shapes among the responsive genes, by name ("hill", "exponential", "linear", "power", "log_gauss_probit", "frechet", "step"), summing to 1; None gives 30% hill, 15% exponential, 5% linear, 10% power, 20% log_gauss_probit, 10% frechet and 10% step.

  • max_log2_changes – The maximal changes of the responsive genes, as sizes in log2 units, each above log2(1.1) = 0.1375: 1 is a 2-fold change. They come in equal shares, half rises and half falls.

  • biological_sd – The SD of a gene’s log2 expression between replicates of one dose from biological variation between animals or wells, the median over genes.

  • donor_sd – None (default) for one animal or donor per replicate. A number, 0 or more, for donors whose cells receive every dose, as when one donor’s cells are split across the doses in culture: the r-th replicate of each dose comes from donor r, and donor_sd is the SD of the donor’s effect, shared by the doses, the median over genes.

  • composition – For the cell types named, a factor per dose on the expected cells per profile, such as [1, 1, 1, 1, 1, 0.5] to halve a cell type at the top dose, or above 1 for one that expands; other cell types keep 1.

  • unit – The unit of the doses, recorded in the truth for DoseAxis.

  • metric – What the dose measures, one of "administered" (default), "nominal", "measured" and "internal", as DoseAxis takes it.

  • rng – A numpy.random.Generator, which the call draws the series’ seed from, so that calling again with it gives another series; an integer seed, which gives the same series as numpy.random.default_rng(seed); or None for a fresh, unseeded generator.

Returns:

The cube and its truth. The cube has the cell types as groups; the samples in dose order, replicates within, with sample_id d{k}_r{r} (k the dose’s position from 0 for the vehicle, r the replicate from 1, each padded with zeros), dose (0 for the vehicle), dose_group (d{k}, which sorts in dose order, the vehicle first) and donor; the layer counts; n_cells; and a provenance record of how it was simulated.

Raises:
  • TypeError – If an argument has the wrong type, or is or holds a numpy masked array.

  • ValueError – If a value is out of range or a per-dose or per-cell-type argument has the wrong length, a shape or a cell type of composition is unknown, the shares of shapes do not sum to 1, composition is 0 at every dose for a cell type, or the expected cells or counts of a profile exceed 2^53.

Example

>>> cube, truth = simulate_dose_series([0, 0.1, 1, 10], replicates=2, rng=1)
>>> cube.samples["dose_group"].tolist()
['d0', 'd0', 'd1', 'd1', 'd2', 'd2', 'd3', 'd3']
>>> table = truth.table("cell_type_1")
>>> int((table["shape"] != "flat").sum())
200

Used in: Dose response per cell type

Explained in: Choosing a method, Dose response, Cube files and provenance records

class cytepool.DoseTruth(doses, tables, *, unit, metric)#

The true curves of a simulated dose series, from simulate_dose_series().

For each cell type and gene, the curve of expression along dose: the true change in log2 expression from the vehicle (a log2 fold change) at any dose (curve()), the gene’s EC50, the dose that gives half the maximal change, and its benchmark doses (Crump 1984), the lowest dose at which the curve departs from the vehicle by a stated change, the benchmark response, at any change (benchmark_doses()) (https://docs.nygen.io/CytePool/statistics/dose-response#simulated-dose-series).

table() gives the parameters and two benchmark doses per gene, with the columns

  • feature_id: the gene;

  • shape: "flat" for a gene that does not respond, or one of "hill", "exponential", "linear", "power", "log_gauss_probit", "frechet" and "step" (the curves below);

  • max_log2_change: the signed maximal change in log2 expression: the plateau of the hill, exponential, frechet and step curves, the change at the top dose of the linear and power curves, and the peak (or trough) of the log_gauss_probit curve; 0 for flat;

  • ec50: the dose of half the maximal change (hill, exponential, frechet), or the dose of the step, where the change jumps from 0 to max_log2_change (step); NaN otherwise;

  • slope: the Hill slope (hill), the shape exponent (frechet) or the exponent (power), positive whatever the direction, which max_log2_change carries; NaN otherwise;

  • peak_dose and peak_width: the dose of the peak and the SD of the bell along log10 dose, in log10 units (log_gauss_probit); NaN otherwise;

  • counts_per_cell: the expected counts of one cell at the vehicle, for a replicate without biological effect and of average depth;

  • expression_sd: the SD of the gene’s log2 expression between vehicle replicates from biological and donor variation, before counting: the SD of true expression, not of observed log-CPM values, which counting widens most for genes with few counts;

  • bmd_expression_sd: the benchmark dose at a change of one expression_sd;

  • bmd_fold_change: the benchmark dose at a fold change of 1.1 in either direction, a rise of 10% or a fall of 9.1% (a change of log2(1.1) = 0.1375 in log2 expression), in true expression: the prior counts of log-CPM values compress the observed changes of genes with few counts, so for them an estimate on the observed scale targets a higher dose.

With M = max_log2_change, E = ec50, n = slope, P = peak_dose, w = peak_width and T the top dose, the change from the vehicle at dose d > 0 is

  • hill: M / (1 + (E/d)^n), the Hill equation, drc’s LL.4 and the sigmoid Emax model;

  • exponential: M (1 - 2^(-d/E)), BMDS’s exponential 4 model;

  • linear: M d / T;

  • power: M (d/T)^n, BMDS’s power model;

  • log_gauss_probit: M exp(-(log10(d/P) / w)^2 / 2), a symmetric bell along log dose, DRomics’ log-Gauss-probit model with the same level on both sides;

  • frechet: M 2^(-(E/d)^n), the Fréchet curve, drc’s Weibull type 1 with b < 0: flat at low doses, then a steep rise and a slow approach to the plateau, the Weibull curve 1 - exp(-(d/e)^n) of BMDS’s exponential 5 model turned end for end on a log-dose axis;

  • step: M where d >= E, else 0;

  • flat: 0;

and 0 at d = 0 for every shape. A benchmark dose is NaN where the curve never reaches the change: for flat genes; for hill, exponential and frechet curves when the change is |M| or more; for log_gauss_probit and step curves when it exceeds |M|. Linear and power curves reach any change, beyond the top dose when it exceeds |M|. A bell reaches a change twice, and the benchmark dose is the lower crossing.

Built by simulate_dose_series(), or from tables with the parameter columns, as table() gives them, so that a truth can be saved and read back: DoseTruth(truth.doses, {c: truth.table(c) for c in truth.cell_types}, unit=truth.unit, metric=truth.metric) rebuilds truth. Other columns of the tables, such as the benchmark doses, are ignored and computed again. Immutable.

Parameters:
  • doses – The dose levels of the series, as simulate_dose_series() takes them: strictly increasing from 0, the vehicle, with at least two doses above 0. The last is the top dose of the linear and power curves.

  • tables – Each cell type’s table, a Table, a mapping of column name to 1-D values or a pandas DataFrame, with the columns feature_id, shape, max_log2_change, ec50, slope, peak_dose, peak_width, counts_per_cell and expression_sd, and the same genes in the same order in every table.

  • unit – The unit of the doses, as DoseAxis takes it.

  • metric – What the dose measures, one of "administered", "nominal", "measured" and "internal", as DoseAxis takes it.

Raises:
  • TypeError – If an argument has the wrong type, or is or holds a numpy masked array.

  • ValueError – If doses are not as described, there is no cell type, a table lacks a column, its genes are repeated or differ from those of another table, a shape is unknown, or a parameter is not finite and above 0 where the shape uses it and NaN where it does not; max_log2_change must be 0 for flat genes and finite and not 0 otherwise, and counts_per_cell and expression_sd finite and above 0.

Example

>>> truth = DoseTruth(
...     [0.0, 0.1, 1.0, 10.0],
...     {
...         "hepatocyte": {
...             "feature_id": ["Cyp1a1", "Alb"],
...             "shape": ["hill", "flat"],
...             "max_log2_change": [2.0, 0.0],
...             "ec50": [1.0, np.nan],
...             "slope": [2.0, np.nan],
...             "peak_dose": [np.nan, np.nan],
...             "peak_width": [np.nan, np.nan],
...             "counts_per_cell": [0.5, 3.0],
...             "expression_sd": [0.25, 0.25],
...         }
...     },
...     unit="ug/kg",
...     metric="administered",
... )
>>> truth.curve("hepatocyte", at=[0.0, 1.0, 10.0]).round(4).tolist()
[[0.0, 1.0, 1.9802], [0.0, 0.0, 0.0]]
>>> truth.benchmark_doses("hepatocyte", log2_change=1.0).tolist()
[1.0, nan]

Used in: Dose response per cell type

Explained in: Dose response

property doses#

The dose levels of the series, from 0, the vehicle.

property unit#

The unit of the doses.

property metric#

What the doses measure, one of administered, nominal, measured and internal.

property cell_types#

The cell types, in the order of the cube’s groups.

table(cell_type)#

The true curve of each gene of a cell type, and its two benchmark doses.

One row per gene, in the cube’s feature order, with the columns that the class describes.

Raises:
  • KeyError – If the truth has no such cell type.

  • TypeError – If cell_type is not a str.

Explained in: Dose response

curve(cell_type, genes=None, *, at)#

The true change in log2 expression from the vehicle, at any doses.

Parameters:
  • cell_type – The cell type.

  • genes – Feature ids, a boolean mask or integer positions, as Cube.select takes features; None (default) gives every gene, in table order.

  • at – One dose, or (m,) doses, in the unit of the series, finite and at least 0.

Returns:

(genes, m) float64 log2 fold changes against the vehicle, with m = 1 for one dose.

Raises:
  • KeyError – If the truth has no such cell type or gene.

  • TypeError – If at is not real-valued, or an argument is or holds a numpy masked array.

  • ValueError – If at has more than one dimension or holds a dose that is not finite or is negative, or genes repeats a gene.

Explained in: Dose response

benchmark_doses(cell_type, genes=None, *, log2_change)#

The lowest dose at which each gene’s true curve departs from the vehicle by a change, in either direction: its benchmark dose at a benchmark response (BMR) of log2_change.

For a change c in log2 expression, the lowest dose d at which |f(d)| reaches c, f being the curve of curve(); NaN where the curve never does. The benchmark response is a change in log2 expression: a rise of 10%, BMDS’s relative deviation of 0.1, is np.log2(1.1), not 0.1, and the same change downwards is a fall of 9.1%. One SD of true expression at the vehicle is table(cell_type)["expression_sd"], which bmd_expression_sd uses, as bmd_fold_change uses log2(1.1).

Parameters:
  • cell_type – The cell type.

  • genes – Feature ids, a boolean mask or integer positions, as Cube.select takes features; None (default) gives every gene, in table order.

  • log2_change – The benchmark response as a change in log2 expression, above 0 and finite: one value for every gene, or one per gene selected.

Returns:

(genes,) float64 doses in the unit of the series.

Raises:
  • KeyError – If the truth has no such cell type or gene.

  • TypeError – If log2_change is not real-valued, or an argument is or holds a numpy masked array.

  • ValueError – If log2_change has neither one value nor one per gene, or is not finite and above 0, or genes repeats a gene.

Explained in: Dose response