Dose designs#

Whether a dose series supports tests in each cell type, checked before anything is fitted; Checking a dose design explains it.

Whether a dose series supports tests in each cell type, checked before anything is fitted.

A dose analysis compares each dose with the vehicle, the samples given no dose, and judges each difference against the variation between replicates given the same dose. check_dose_design() says what each cell type (group) of a cube supports, and returns a DoseDesignReport (https://docs.nygen.io/CytePool/statistics/dose-response#dose-design-check):

  1. Samples. A design sample enters a cell type as it enters the cell type’s fit in limma_voom: with at least min_cells cells there, when the cube records cells, some counts, and at least min_counts counts summed over all features. Filtering can leave a dose group without a sample in some cell types, as dreamlet’s documentation warns for the time points of an ordered covariate (Hoffman et al. 2026).

  2. Dose groups. The distinct doses of the design’s samples, the vehicle (dose 0) first. In a cell type, a dose group that keeps no sample is dropped. The replicates of a dose group are its samples or, when the design has random intercepts, the fewest levels of a random intercept’s grouping among them, such as the animals whose samples it holds.

  3. The dose-group model. The design’s terms, an intercept, and an indicator of each treated dose group that keeps a sample, on the samples used. Its rank, by R’s qr() rule, gives the residual degrees of freedom. A dose group is estimable, comparable with the vehicle apart from the design’s other terms, when its column lies outside the span of the other columns (Searle 1971), which R’s qr() and limma’s nonEstimable report with the column placed last. Random intercepts are checked on these samples as Design.check checks them.

  4. The batch. A dose group is confounded with a processing batch, such as a lane or a plate, when its difference from the vehicle is also a difference between batches: it is estimable, and not once the batches join the model. Batches of a single sample are pooled into one first, since such a batch cannot be told apart from its sample’s own deviation; a sample alone in its batch, when it is the only one, joins no batch. A batch that coincides with the condition breaks the control of false positives, which summing the counts within each batch restores (Lun and Marioni 2017). The rule finds exact confounding only: a batch that is unbalanced across the doses without confounding them belongs in the design too.

Statuses:
  • "refused": no dose analysis. Every sample was left out; the design, or the cell type, has no vehicle sample; no treated sample is left; no treated dose group is estimable; or the random intercepts cannot be estimated beside the dose groups.

  • "descriptive": curves that describe the means of the dose groups, without p-values or bounds. No estimable treated dose group has two replicates, so no dose has a replicate; the model leaves no residual degrees of freedom; or a batch is confounded with an estimable dose group, unless the design has the batch as a random intercept and the vehicle and each such group span two or more batches.

  • "inferential": tests with p-values, and curves with bounds.

ETAP’s design minimums:

With rules="etap_2024", the report lists the design minimums of EPA’s Transcriptomic Assessment Products (US EPA 2024) that samples show, each met or not: at least eight doses and a vehicle, spaced by half a log10 down from the highest dose, the lowest a full log10 below the second lowest (Sec. 3.4.1.3); at least four animals of each sex in each dose group (Sec. 3.4.2); and, per cell type and sex, at least two passing samples at each dose level and three passing vehicle samples (Sec. 3.4.5.2), passing being the cell type’s filter of samples. A step counts as half a log10 within 0.05 of 0.5, and as a full log10 within 0.05 of 1. ETAP excludes a dose level with fewer than two passing samples and goes on, so such a level is listed without changing the rules’ status; any other unmet minimum makes the status a deviation.

References

Hoffman GE, Lee D, Bendl J, Prashant NM, Hong A, Casey C, Alvia M, Shao Z, Argyriou S, Therrien K, Venkatesh S, Voloudakis G, Haroutunian V, Fullard JF, Roussos P (2026). Efficient differential expression analysis of large-scale single-cell transcriptomics data using Dreamlet. Nature Communications 17, 9597. doi:10.1038/s41467-026-75680-8

Lun ATL, Marioni JC (2017). Overcoming confounding plate effects in differential expression analyses of single-cell RNA-seq data. Biostatistics 18, 451-464. doi:10.1093/biostatistics/kxw055

Searle SR (1971). Linear Models. Wiley, New York.

US EPA (2024). Standard Methods for Development of EPA Transcriptomic Assessment Products (ETAPs). EPA/600/X-23/083, US Environmental Protection Agency, Office of Research and Development. doi:10.23645/epacomptox.25365496

cytepool.check_dose_design(cube, design, *, dose, batch=None, rules=None, sex=None, min_cells=10, min_counts=0, groups=None)#

Check what a dose series supports in every cell type of a cube.

For every cell type (group), before anything is fitted: the samples that the cell type’s fit in limma_voom() would use, with the same min_cells and min_counts; the samples, cells and counts each dose group keeps; the dose groups that the design’s other terms, or a processing batch, make impossible to compare with the vehicle; the residual degrees of freedom; and a status, inferential, descriptive or refused, with the reason (the module documentation gives the rules). With rules="etap_2024", the design minimums of EPA’s Transcriptomic Assessment Products, each met or not (US EPA 2024). https://docs.nygen.io/CytePool/statistics/dose-response#dose-design-check explains the check.

Parameters:
  • cube – A cube with a counts layer, as limma_voom() takes.

  • design – A Design of the terms other than dose, such as Design(cube.samples, "~ 1") or "~ sex", with random intercepts if the analysis has them, whose sample table has a sample_id column with cube sample ids and the dose column; its rows may be some of the cube’s samples, in any order. The check adds the dose groups itself, so a design whose terms use the dose column or the axis’s columns ({column}_treated, {column}_s1, …) is refused. The dose groups are the distinct doses of all the design’s samples, so check a screen of several compounds one compound at a time, with a design of that compound’s samples and the vehicle’s.

  • dose – The DoseAxis whose column holds each sample’s dose, 0 for the vehicle. The dose groups are the distinct doses of the design’s samples.

  • batch – A column of the design’s samples that names each sample’s processing batch, such as a lane, plate or run, read as labels whatever their type; None for none.

  • rules – "etap_2024" to list the design minimums of EPA’s Transcriptomic Assessment Products, each met or not, or None.

  • sex – With rules, and only then: the column of the design’s samples that holds each sample’s sex; a study of one sex has a single value there.

  • min_cells – The fewest cells a sample needs in a cell type, as in limma_voom(). Ignored when the cube does not record cell numbers.

  • min_counts – The fewest counts, summed over all features, a sample needs in a cell type, as in limma_voom().

  • groups – A group id or a list of them; all groups by default.

Returns:

The tables of the cell types, their dose groups, samples and, with rules, the minimums, with Design.check() of the design.

Raises:
  • TypeError – If cube is not a Cube, design not a Design, dose not a DoseAxis, an option has the wrong type, the dose column does not hold real numbers, or groups or min_cells is or holds a numpy masked array.

  • ValueError – If the design has random effects that are not random intercepts, has no sample_id column, names samples the cube does not have or names a sample twice; if its terms use the dose column or the axis’s columns; if the dose, batch or sex column is missing or holds a missing value; if a dose is not finite or is negative, or two doses differ by less than 1e-8 of the dose; if rules names no rule set, rules is given without sex or sex without rules; or if an option is out of range.

  • KeyError – If a group is not in the cube.

Used in: Dose response per cell type

Explained in: Choosing a method, Dose response

class cytepool.DoseDesignReport(summary, doses, samples, minimums, design_check, settings)#

What each cell type of a dose series supports, from check_dose_design().

Tables, one row per cell type checked, or per cell type and dose group or sample, in the order of the cube’s groups (or of groups), doses ascending:

  • summary: group_id; status, "inferential", "descriptive" or "refused"; reason, why the cell type is not inferential, empty when it is; n_dose_groups, the dose groups that keep a sample, the vehicle included, and n_dose_groups_dropped, those that keep none; n_dose_groups_estimable, the treated dose groups that the design can compare with the vehicle, which with the vehicle are the dose groups a curve can use; n_samples_used and n_samples_left_out; df_residual, the residual degrees of freedom of the dose-group model, NaN when no sample is used; and, with a rule set, rules_status, "met" or "deviation".

  • doses: group_id; dose, in the axis’s unit; n_samples_used and n_samples_left_out; n_cells_min, when the cube records cells, and total_counts_min, over the samples used (NaN for a group that keeps no sample); estimable, whether the design can compare the treated dose group with the vehicle apart from its other terms (False for the vehicle, the reference, and for groups that keep no sample); and, with a batch, confounded_with_batch, whether the group’s difference from the vehicle is also a difference between batches (False for groups that are not estimable). A design that has the batch as a random intercept compares such groups against the variance between batches, so they do not make the cell type descriptive when the vehicle and each of them span two or more batches.

  • samples: group_id; sample_id; dose; n_cells, when the cube records cells; total_counts, the counts summed over all features, which min_counts reads; used; and reason, why the sample was left out, empty when used.

  • minimums: with a rule set, one row per minimum, met or not, and None without: group_id, None for a minimum of the design; sex, None for a minimum of the doses; minimum, "dose_levels", "dose_spacing", "sexes", "animals_per_sex_and_dose", "passing_samples_per_dose" or "passing_vehicle_samples"; section, of the rule set’s document; required and observed, as text; met; and when_unmet, what the rule set does when the minimum is unmet.

design_check is Design.check() of the design given, and settings the settings of the check, the dose axis as DoseAxis.to_dict() gives it. https://docs.nygen.io/CytePool/statistics/dose-response#dose-design-check explains how to read the report.

Built by check_dose_design(). Immutable.

Raises:
  • TypeError – If summary, doses or samples is not a Table, minimums is neither a Table nor None, design_check is not a DesignReport, or settings is not a mapping that JSON can write.

  • ValueError – If settings holds a NaN or an infinity.

Explained in: Dose response

property summary#

One row per cell type, with its status, the reason, its dose groups and its samples.

property doses#

One row per cell type and dose group, with its samples, cells and counts, and whether it is estimable.

property samples#

One row per cell type and design sample, used or left out, and why.

property minimums#

One row per minimum of the rule set checked, met or not, or None without one.

property design_check#

Design.check() of the design given.

property settings#

The settings of the check as a new dict, with dose, the axis as DoseAxis.to_dict() gives it, which DoseAxis(**settings["dose"]) rebuilds, and batch, rules, sex, min_cells, min_counts and groups, as given.

status(group=None)#

The status of a cell type: "inferential", "descriptive" or "refused".

Parameters:

group – A group id; may be left out when the report checked one group.

Raises:
  • ValueError – If group is left out and the report checked several.

  • KeyError – If the report did not check group.

Explained in: Dose response

rules_status(group=None)#

Whether a cell type meets the minimums of the rule set checked: "met" or "deviation".

A deviation means that a minimum of the design, or the minimum of passing vehicle samples of the cell type, is unmet; dose levels that the rule set excludes for want of passing samples are listed in minimums and leave the status unchanged.

Parameters:

group – A group id; may be left out when the report checked one group.

Raises:
  • ValueError – If no rule set was checked, or group is left out and the report checked several groups.

  • KeyError – If the report did not check group.

Explained in: Dose response