Dose responses#

Which genes respond to a dose in each cell type, by moderated tests of one model of the dose groups, with the fitted spline and its band, multiple contrast tests of the doses, the gate that decides which genes count as responding and the lowest dose from which each gene responds; Which genes respond to dose explains the tests.

Which genes respond to a dose in each cell type, by moderated tests of one model of the dose groups.

dose_response() tests a dose series in every cell type (group) of a cube that supports tests, in one call (https://docs.nygen.io/CytePool/statistics/dose-response#dose-response-tests):

  1. The check. check_dose_design() says which cell types support tests, which only description and which nothing, and which dose groups each keeps; only cell types that support tests are fitted.

  2. One model of the dose groups per cell type. The design holds the terms other than dose, such as "~ 1" or "~ sex"; an intercept and an indicator of each treated dose join them, so that the coefficient theta_k of dose d_k is the difference of its mean from the vehicle’s at the other terms. The model is fitted by limma_voom() (Law et al. 2014), the default, limma_trend() or dream_voom() (Hoffman and Roussos 2021), with their expression filter, normalization and empirical Bayes moderation (Smyth 2004).

  3. The tests, as contrasts of that one fit, so that every test of a gene uses its one moderated variance: spline, whether the gene responds at all, along a natural cubic spline of dose (Desquilbet and Mariotti 2010; Harrell 2015); nonlinearity, whether the spline departs from a straight line along the dose axis; linear_trend, the slope of a straight line along the axis; and dose_groups, whether any dose group differs from the vehicle, the one-way analysis of variance of the dose groups with moderated variances: the moderated counterpart of the ANOVA gate of NTP’s genomic dose-response approach, which at least one gene must pass for a data set to be analysed further (NTP 2018). When named, three multiple contrast tests refer the largest of several correlated moderated t-statistics to the multivariate t distribution: dunnett, each dose against the vehicle (Dunnett 1955); williams, the Williams-type test of the vehicle against the pooled top doses (Bretz 2006); and mcp, the MCP step, the multiple comparison procedure, of MCP-Mod (multiple comparison procedure and modelling): the contrasts that best detect each of a few candidate shapes (Bretz, Pinheiro and Branson 2005; Pinheiro et al. 2014).

  4. The gate, which decides which genes count as responding: one test of any response at a stated false discovery rate, after the dose-blind expression filter (Bourgon, Gentleman and Huber 2010), with any fold change in the null hypothesis of each dose against the vehicle by TREAT (McCarthy and Smyth 2009).

  5. On demand, the lowest effective dose of each gene the gate passes: the lowest dose called by stage-wise testing (Heller et al. 2009; Van den Berge et al. 2017).

The spline:

In each cell type the spline is fitted by least squares to the means of the dose groups that the cell type compares, each weighted by its samples: with Z the columns at those doses, an intercept first, and N the samples of each group, the coefficients are A mu, A = (Z’NZ)^-1 Z’N. The rows of A after the intercept’s sum to zero, so each coefficient is a contrast of the theta_k. Without observation weights or other terms, these are the coefficients of the spline fitted to the samples themselves, which the limma User’s Guide fits for a time course (section 9.6.2); with voom’s weights or other terms, the means are those of the weighted fit, and the spline passes through them by least squares. The basis is placed once, on the doses of the design’s samples, so that knots and curves compare across cell types.

Adjustment for multiple testing:

adjusted_p_value adjusts the p-values of one cell type and test by Benjamini-Hochberg (Benjamini and Hochberg 1995), as limma’s topTable does, and adjusted_p_value_across_groups adjusts them over every cell type that ran the test, stacked into one family. The tests of each dose against the vehicle are adjusted within the cell type and dose only. A multiple contrast test’s p_value is already adjusted for the gene’s contrasts (single-step, Hothorn, Bretz and Westfall 2008), and its adjusted p-values adjust it across genes. The gate adjusts its p-values by Benjamini-Hochberg within each cell type; a gate with a fold change first takes, for each gene, the smallest of its doses’ TREAT p-values times the doses (Bonferroni), so that a gene counts once.

References

Law CW, Chen Y, Shi W, Smyth GK (2014). voom: precision weights unlock linear model analysis tools for RNA-seq read counts. Genome Biology 15, R29. doi:10.1186/gb-2014-15-2-r29

Hoffman GE, Roussos P (2021). Dream: powerful differential expression analysis for repeated measures designs. Bioinformatics 37, 192-201. doi:10.1093/bioinformatics/btaa687

Smyth GK (2004). Linear models and empirical Bayes methods for assessing differential expression in microarray experiments. Statistical Applications in Genetics and Molecular Biology 3, article 3. doi:10.2202/1544-6115.1027

Desquilbet L, Mariotti F (2010). Dose-response analyses using restricted cubic spline functions in public health research. Statistics in Medicine 29, 1037-1057. doi:10.1002/sim.3841

Harrell FE (2015). Regression Modeling Strategies, 2nd edition. Springer, Cham. doi:10.1007/978-3-319-19425-7

NTP (2018). NTP research report on National Toxicology Program approach to genomic dose-response modeling. NTP Research Report 5. National Institute of Environmental Health Sciences. doi:10.22427/ntp-rr-5

Tukey JW, Ciminera JL, Heyse JF (1985). Testing the statistical certainty of a response to increasing doses of a drug. Biometrics 41, 295-301. doi:10.2307/2530666

Benjamini Y, Hochberg Y (1995). Controlling the false discovery rate: a practical and powerful approach to multiple testing. Journal of the Royal Statistical Society B 57, 289-300. doi:10.1111/j.2517-6161.1995.tb02031.x

Dunnett CW (1955). A multiple comparison procedure for comparing several treatments with a control. Journal of the American Statistical Association 50, 1096-1121. doi:10.1080/01621459.1955.10501294

Bretz F (2006). An extension of the Williams trend test to general unbalanced linear models. Computational Statistics and Data Analysis 50, 1735-1748. doi:10.1016/j.csda.2005.02.005

Bretz F, Pinheiro JC, Branson M (2005). Combining multiple comparisons and modeling techniques in dose-response studies. Biometrics 61, 738-748. doi:10.1111/j.1541-0420.2005.00344.x

Pinheiro J, Bornkamp B, Glimm E, Bretz F (2014). Model-based dose finding under model uncertainty using general parametric models. Statistics in Medicine 33, 1646-1661. doi:10.1002/sim.6052

Hothorn T, Bretz F, Westfall P (2008). Simultaneous inference in general parametric models. Biometrical Journal 50, 346-363. doi:10.1002/bimj.200810425

Heller R, Manduchi E, Grant GR, Ewens WJ (2009). A flexible two-stage procedure for identifying gene sets that are differentially expressed. Bioinformatics 25, 1019-1025. doi:10.1093/bioinformatics/btp076

Van den Berge K, Soneson C, Robinson MD, Clement L (2017). stageR: a general stage-wise method for controlling the gene-level false discovery rate in differential expression and differential transcript usage. Genome Biology 18, 151. doi:10.1186/s13059-017-1277-0

Bourgon R, Gentleman R, Huber W (2010). Independent filtering increases detection power for high-throughput experiments. Proceedings of the National Academy of Sciences 107, 9546-9551. doi:10.1073/pnas.0914005107

McCarthy DJ, Smyth GK (2009). Testing significance relative to a fold-change threshold is a TREAT. Bioinformatics 25, 765-771. doi:10.1093/bioinformatics/btp053

cytepool.dose_response(cube, design, *, dose, tests=None, spline_df=None, candidates=None, gate=None, analysis=limma_voom, batch=None, groups=None, min_cells=10, min_counts=0, rng=None, **options)#

Test which genes respond to a dose in every cell type of a cube.

For every cell type (group) of the cube that supports tests: one moderated fit of the dose groups, the vehicle and the doses that keep samples there, by analysis, and four tests as contrasts of it (the module documentation gives the model):

  • "spline": whether the gene responds at all, by the F-test of a natural cubic spline of dose fitted to the means of the dose groups, with a jump from the vehicle to the lowest dose (the axis’s dose_treated column, for a dose column named dose) when the vehicle is a group of its own. Read it first.

  • "nonlinearity": whether the spline departs from a straight line along the axis, by the F-test of its restricted cubic columns after the first; with the vehicle in its own group, the line runs through the treated doses.

  • "linear_trend": the slope of a straight line fitted to the means along the axis, by a moderated t-test, as a change in log2 expression per log10 unit of dose on a log10 axis (of dose plus the offset, with the vehicle on the axis) or per unit of dose on a linear one. With the vehicle in a group of its own, the line runs through the treated doses only, so a gene that jumps at the lowest dose and then stays flat has a slope near 0, and the vehicle’s difference is tested by spline and dose_groups; with the vehicle on the axis, it runs through every dose, the regression on log dose of Tukey’s trend test (Tukey, Ciminera and Heyse 1985).

  • "dose_groups": whether any dose group differs from the vehicle, by the F-test of every dose against the vehicle, the one-way analysis of variance of the dose groups with moderated variances: the moderated counterpart of the ANOVA gate of NTP’s genomic dose-response approach (NTP 2018).

Each dose against the vehicle is also tested, in the table "each_dose". https://docs.nygen.io/CytePool/statistics/dose-response#dose-response-tests explains the tests and how to read them.

Three multiple contrast tests run when named, each two-sided, with one error rate for the gene’s contrasts (the single-step max-t test, from the multivariate t distribution on the gene’s df) and Benjamini-Hochberg across genes:

  • "dunnett": each dose against the vehicle (Dunnett 1955).

  • "williams": the Williams-type test (Bretz 2006), the vehicle against the mean of the top one, two or more doses, weighted by the cell type’s samples, which detects changes that grow in dose order. It is not Williams’ (1971) trend test of BMDExpress and NTP’s rules, which compares each dose with the vehicle after fitting means that change in dose order.

  • "mcp": the MCP step of MCP-Mod, multiple comparison procedure and modelling (Bretz, Pinheiro and Branson 2005; Pinheiro et al. 2014): the optimal contrasts of the candidates for the cell type’s doses and samples.

None runs by default: on 20,000 genes of the vehicle and 7 doses in three replicates, on two threads, Dunnett’s test and the MCP step each added about 10 s to the 0.9 s of the default tests and the Williams-type test 23 s; with 3 doses the MCP step took 0.6 ms per gene and the other two under 0.1 ms. Each gene’s covariance of its doses’ estimates, voom’s weights included, sets the contrasts’ correlation, so limma’s approximate standard errors (contrast_standard_errors="limma") are refused with them. Under dream the multivariate t takes the smallest df of the gene’s doses, an approximation: contrasts that combine doses can have fewer. https://docs.nygen.io/CytePool/statistics/dose-response#dose-response-contrasts explains them.

The gate decides which genes count as responding: one test of any response at a stated false discovery rate, Benjamini-Hochberg within each cell type, after the expression filter, which does not read the doses (Bourgon, Gentleman and Huber 2010). Its calls are the table "gate", with passes_gate; the genes it passes are those whose doses DoseResponseResult.lowest_effective_doses() calls. A fold change enters the null hypothesis of each dose against the vehicle by TREAT (McCarthy and Smyth 2009), and a gene passes when its change beyond the fold change at one dose or more is called: the smallest of its doses’ TREAT p-values times the doses (Bonferroni), then Benjamini-Hochberg. The gate takes the place of BMDExpress’s prefilter, the step that picks the genes that go on to curves: BMDExpress’s default prefilter takes an unadjusted Williams p-value and cuts the estimated fold change, where the gate adjusts its p-values and puts any fold change inside the test. It is not the ANOVA gate of NTP’s and EPA’s rules, a test of the data set that at least one gene must pass before the set is analysed further. With 2 replicates per dose, a cell type of 1,000 null genes had a gene pass the default gate at 5% FDR in 10% to 16% of simulated series, against 7% with 3 replicates (https://docs.nygen.io/CytePool/statistics/dose-response#dose-response-gate): permutation_check() runs the gate again with the doses permuted and tests whether the true doses pass more genes.

The design is checked first by check_dose_design(), with batch, groups, min_cells and min_counts, and the check is kept as the result’s design_report: cell types that it calls descriptive or refused are listed with its reason and not fitted. A cell type tests the dose groups that keep a sample there and that the design can compare with the vehicle; a test that its dose groups cannot estimate, such as a spline of more columns than its doses support, is not run there, with the reason.

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 for dream_voom, 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. Its terms may not use the dose column or the axis’s columns, and it may not name contrasts: dose_response adds the dose groups and tests them itself.

  • dose – The DoseAxis of the series. The dose groups are the distinct doses of the design’s samples.

  • tests – A test name, or a list of them, among "spline", "nonlinearity", "linear_trend", "dose_groups", "dunnett", "williams" and "mcp"; None runs the first four that the design supports, leaving out in each cell type a test of the same hypothesis as another, which happens when the dose groups are few. "spline" and "linear_trend" need two doses on the axis (the treated doses when the vehicle is a group of its own, every dose when it is on the axis), "nonlinearity" a spline of two columns or more, and "mcp" two treated doses; a cell type that compares one treated dose does not run "mcp", with the reason. The gate’s test, the spline by default, also runs when tests does not name it, and decides which genes pass the gate and whose lowest effective doses are called: tests="williams" runs the spline too, and gate={"test": "williams"} makes the Williams-type test decide.

  • spline_df – The number of spline columns, at least 1 and at most the doses on the axis minus 1; None gives 2 when the axis holds 4 doses or more, and 1 otherwise. The knots are placed by DoseAxis.spline_basis() with its rule "levels", in the restricted cubic form.

  • candidates – The CandidateShapes of "mcp", with a beta_scale of at least the top dose; None spreads the default shapes over the design’s doses, CandidateShapes.spread(dose, design.samples). Given only with "mcp", in tests or as the gate’s test. A shape that does not change at a cell type’s doses is left out there, with the reason in the record.

  • gate – None for the default gate, the spline test at 5% FDR, or a mapping of its settings: "test", a test of any response, "spline" (the default), "dose_groups", "dunnett", "williams" or "mcp", which runs whether tests names it or not, with "dose_groups" the default when fewer than two doses are on the axis, where it asks the spline’s question; "fdr", the false discovery rate of the calls, between 0 and 1 (0.05); and "fold_change", a fold change above 1, up or down, that a gene’s change from the vehicle must exceed at one dose or more, by TREAT, which the gate records as the test "each_dose". gate=result.gate gives a result’s gate back.

  • analysis – limma_voom() (by default), limma_trend() or dream_voom(); a design with random intercepts needs dream_voom.

  • batch – A column of the design’s samples that names each sample’s processing batch, which the check uses to find dose groups confounded with it. It is checked, not modelled: a batch to adjust for belongs in the design.

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

  • min_cells – The fewest cells a sample needs in a cell type, as in limma_voom(); for the check and the fits.

  • min_counts – The fewest counts, summed over all features, a sample needs in a cell type, as in limma_voom(); for the check and the fits.

  • rng – A numpy random generator, an integer seed, or None, for the Monte Carlo error of the multiple contrast tests’ p-values. dose_response takes one seed, the integer given or one drawn from the generator, and records it in settings["seed"]; each cell type and test draws from a generator seeded by it, the cell type’s name and the test, so that rng=<recorded seed> gives the same p-values whatever the other cell types, the other tests named and the threads. Tests of two contrasts or fewer use no random numbers.

  • **options – The analysis’s other options, such as prior_weights, quality_weights, robust, expression_filter, contrast_standard_errors, n_threads (which the multiple contrast tests also follow), prior_count (limma_trend) or df_method (dream_voom); their values are checked by the analysis.

Returns:

The tables of every cell type tested, the summary, the design check, each cell type’s fit, the settings and a provenance record.

Warns:

RuntimeWarning – As the analysis warns, such as when sample quality weights cannot be estimated in a cell type.

Raises:
  • TypeError – If analysis is not one of the three functions, an option is one the analysis does not take or one that dose_response sets (contrasts, f_tests, adjust_across_groups), tests, spline_df, candidates, gate or one of its settings, or rng has the wrong type, or an argument is of a type that check_dose_design() or the analysis refuses.

  • ValueError – If tests names no test or a test twice, or names a test that the design cannot support; spline_df is below 1 or above the doses on the axis minus 1, or given without two doses on the axis; candidates are given without "mcp" or with a beta_scale below the top dose; a multiple contrast test is named with contrast_standard_errors="limma"; gate has a setting it does not know, a test that is not a test of any response or that the design cannot support, an FDR outside (0, 1), or a fold change that is not finite and above 1, given with another test than "each_dose" or with dream_voom, or "each_dose" without one; rng is a negative seed; the design names contrasts, has random intercepts with an analysis of limma or none with dream_voom; the sample table already holds a column of the name of a dose group’s indicator; or as check_dose_design() and the analysis raise.

  • 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.DoseResponseResult(summary, tables, fits, design_report, provenance, *, cube=None, design=None)#

The dose tests of every cell type of a cube, from dose_response().

Tables, by cell type and test (table()), one row per gene tested, in the cube’s feature order:

  • "spline", "nonlinearity" and "dose_groups": F-tests, with feature_id, symbol (when the cube’s feature table has one), average_log2_cpm, f_statistic, df (its denominator degrees of freedom), p_value, adjusted_p_value (Benjamini-Hochberg over the cell type’s genes), adjusted_p_value_across_groups (over every cell type that ran the test) and standardized_f_statistic, the F-statistic on infinite denominator degrees of freedom with the same p-value. The numerator degrees of freedom are in the cell type’s entry of provenance["groups"] (f_test_df1).

  • "linear_trend": the analysis’s table of a contrast, whose log2_fold_change is the slope of the straight line, the change in log2 expression per log10 unit of dose on a log10 axis (of dose plus the offset, with the vehicle on the axis) or per unit of dose on a linear one, with standard_error (not for dream), average_log2_cpm, t, p_value, adjusted_p_value, adjusted_p_value_across_groups and log_odds; dream adds df and z_statistic.

  • "dunnett", "williams" and "mcp": multiple contrast tests, each gene as a whole, with feature_id, symbol, average_log2_cpm, contrast (the contrast with the largest \|t\|, such as "10 - vehicle", "3 to 30 - vehicle" or a candidate shape’s name: for the MCP step, the candidate whose contrast best matches the observed changes, not a fitted shape, since the shapes’ contrasts are strongly correlated and fitting a shape is MCP-Mod’s modelling step, not implemented yet), its t, df (of the multivariate t), p_value (adjusted for the gene’s contrasts, the single-step max-t test) and p_value_error (its Monte Carlo standard error), adjusted_p_value (Benjamini-Hochberg over the cell type’s genes) and adjusted_p_value_across_groups. Each contrast’s weights on the treated doses are in the cell type’s entry of provenance["groups"] (contrast_tests).

  • "each_dose": each treated dose the cell type compares against the vehicle, the rows of a dose together, doses ascending, each dose’s genes in the cube’s feature order: feature_id, symbol, dose (in the axis’s unit), then the columns of the analysis’s table of a contrast, adjusted within the cell type and dose.

  • "gate": the gate’s call of each gene (gate), with feature_id, symbol, p_value (the p-value of the gate’s test, or with a fold change the smallest of the gene’s TREAT p-values times the doses, capped at 1), adjusted_p_value (Benjamini-Hochberg over the cell type’s genes) and passes_gate, whether adjusted_p_value is at most the gate’s FDR.

lowest_effective_doses() calls each dose against the vehicle in the genes that pass the gate, and gives each gene’s lowest effective dose.

summary has one row per cell type checked: group_id; status, the check’s ("inferential", "descriptive" or "refused"); tested; reason, why a cell type was not tested, the check’s reason or the analysis’s when its fit stopped, empty when tested; n_dose_groups_tested, the vehicle and the treated doses compared; n_samples_used; n_features_tested; df_residual and df_prior of the fit (medians for dream), NaN where not tested; tests_not_run, the tests of the design that a tested cell type did not run, whose reasons table() gives; and n_genes_passing_gate, NaN where the gate did not run, which is not a cell type without responding genes.

Built by dose_response() from the summary, the tables, the design check (design_report), the provenance and, as fits, each tested cell type’s result of the analysis without its tables, from which fit() and curve() compute the cell type’s fit again, and with the cube and design analysed, from which permutation_check() runs the analysis again; a result built without them cannot be checked. A pickled result carries the cube: a cube read from a cube file refers to its file, and a cube in memory carries its arrays. Immutable.

Raises:
  • TypeError – If summary is not a Table, tables not a mapping of (cell type, test) to Table, fits not a mapping of cell type to DifferentialExpressionResult, design_report not a DoseDesignReport, provenance not a mapping that JSON can write, cube not a Cube or design not a Design.

  • ValueError – If provenance holds a NaN or an infinity, or one of cube and design is given without the other.

Explained in: Dose response

property summary#

The status of each cell type checked, whether it was tested and why not, its dose groups, samples, genes and degrees of freedom, and the genes that pass the gate.

property tables#

Every table, by (cell type, test), (cell type, "each_dose") and (cell type, "gate").

property cube#

The cube analysed; None for a result built without it.

property design#

The design given, of the terms other than dose; None for a result built without it.

property gate#

The gate’s test, fdr and fold_change, as a new dict that dose_response(..., gate=result.gate) takes back.

Explained in: Dose response

property design_report#

The check of the design, from check_dose_design().

property groups#

The cell types checked, in order.

property tests#

The tests of the design, those named or, when none were, those it supports, in the order spline, nonlinearity, linear_trend and dose_groups, then the multiple contrast tests named, in the order dunnett, williams and mcp; the gate’s test is among them, named or not.

property method#

The analysis, "limma_voom", "limma_trend" or "dream_voom".

property dose#

The dose axis.

property spline_basis#

The basis of the spline of dose, placed on the doses of the design’s samples; None when fewer than two doses are on the axis.

property candidates#

The candidate shapes of the MCP step, given or spread over the design’s doses; None when "mcp" was not named.

Explained in: Dose response

property settings#

The settings of the analysis, as a new dict, also in the provenance.

They hold the axis (dose, as DoseAxis.to_dict() gives it), the spline’s basis (spline_basis, as to_dict() gives it), the tests and spline_df as given, the candidate shapes of "mcp" (candidates, as CandidateShapes.to_dict() gives them; None without "mcp"), the seed of the multiple contrast tests (seed; None when none ran), the gate (gate, as gate gives it), the analysis, and batch, groups, min_cells and min_counts. The analysis’s other options are in the provenance’s analysis_settings, as the analysis records them.

property provenance#

A JSON-serialisable record of what produced every number, as a new dict.

It holds the analysis (method) and the versions of the software; the cube (cube): its fingerprint, the digests it is built from and its own provenance; the layer read; the model of the dose groups (design): its formula, columns, levels and the values of its variables for every sample; the settings, and the analysis’s settings in full (analysis_settings, null when no cell type was fitted); the gate’s adjustment for multiple testing (gate_adjustment); the tests of the design; and, for every cell type (groups), its status, whether it was tested and why not, the doses it compares with their samples, the contrasts of each test it ran (tests), the tests it did not run with the reasons, the numerator degrees of freedom of each test it ran (f_test_df1), the weights of every contrast of its fit on the model’s columns (contrasts), the weights on the treated doses of each multiple contrast test’s contrasts, with the dimensions the MCP step’s contrasts span and the candidate shapes it left out (contrast_tests), and the analysis’s record of its fit (fit: the samples used and left out, the features tested, the span of voom’s trend and the warnings).

table(group=None, name=None)#

Return the table of one cell type and test, or of each dose.

Parameters:
  • group – A cell type; it may be left out when one cell type was checked.

  • name – A test the cell type ran, "spline", "nonlinearity", "linear_trend", "dose_groups", "dunnett", "williams" or "mcp"; "each_dose" for each dose against the vehicle; or "gate" for the gate’s calls. The class documentation gives the columns.

Raises:
  • ValueError – If group is left out and several cell types were checked, or name is left out.

  • TypeError – If group is not a string.

  • KeyError – If the cell type was not checked or not tested, or the test, or the gate’s test, was not run there; the message says why.

Explained in: Dose response

fit(group=None)#

Compute the fit of a tested cell type again: its values, weights and moderated tests.

The fit of the cell type’s model of the dose groups, as DifferentialExpressionResult.fit() computes it again from the cube and settings the result keeps; it takes the time of the cell type’s analysis. Its moderated tests are those of the contrasts in the cell type’s entry of provenance["groups"]: each dose against the vehicle, named after its indicator such as dose_0.1, the spline’s coefficients and the linear trend.

Parameters:

group – A cell type that was tested; it may be left out when one cell type was checked.

Raises:
  • ValueError – If group is left out and several cell types were checked, or the fit no longer gives what the result records (a lazy cube whose source changed).

  • TypeError – If group is not a string.

  • KeyError – If the cell type was not checked or not tested.

Explained in: Dose response

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

Return the fitted spline of genes against the vehicle, with a 95% band.

The curve at dose x is the fitted spline minus the vehicle’s mean, f(x) - mu_0, a contrast a(x)’theta of the cell type’s dose groups: with the vehicle in a group of its own, 0 at the vehicle with a standard error of 0; with the vehicle on the axis, the spline need not pass through the vehicle’s mean, and its value at the vehicle shows how far it misses. The standard error is (a(x)’ V a(x))^(1/2) times the gene’s posterior standard deviation, with V the unscaled covariance of the dose groups’ estimates, each gene’s own under voom’s weights; the band is pointwise, the estimate plus and minus the 0.975 quantile of t on the degrees of freedom of the gene’s moderated t-tests, as limma’s topTable(confint = TRUE) forms intervals (https://docs.nygen.io/CytePool/statistics/dose-response#dose-response-curves). The fit of the cell type is computed again (DifferentialExpressionResult.fit()), which takes the time of its analysis.

Parameters:
  • group – A cell type that was tested; it may be left out when one cell type was checked.

  • genes – A feature id or symbol, or a list of them, among the genes tested there; None for every gene tested.

  • at – Doses in the axis’s unit: the vehicle’s 0, and doses from the lowest to the highest dose the cell type compares, or from 0 when the vehicle sits on the axis. The curve is not extrapolated. None gives 100 doses evenly spaced along the dose axis, from the lowest dose the cell type compares, or from the vehicle when it sits on the axis, to the highest; a vehicle in a group of its own, where the curve is 0, is left out.

Returns:

One row per gene and dose, the genes in the order given and each gene’s doses in the order of at: feature_id, symbol (when the cube’s feature table has one), dose, log2_fold_change, standard_error, ci_lower and ci_upper.

Raises:
  • TypeError – If group is not a string, genes is not a feature id or symbol or a list of them, or at is not real-valued, or either is or holds a numpy masked array.

  • ValueError – If group is left out and several cell types were checked; the result is of dream_voom, whose fits do not keep the degrees of freedom a band needs; the cell type’s doses cannot estimate the spline, or no spline is placed; a symbol names several genes tested there; or a dose of at is not finite, is negative, or lies outside the doses the cell type compares.

  • KeyError – If the cell type was not checked or not tested, or a gene was not tested there.

Explained in: Dose response

lowest_effective_doses(group=None)#

Return the lowest dose from which each gene of a cell type responds, by stage-wise calls of each dose against the vehicle in the genes that pass the gate.

The calls of the stage-wise procedure of stageR (Heller et al. 2009; Van den Berge et al. 2017), with the gate (gate) as its screen: the gate passes R of the G genes it tested at its FDR, alpha; in each gene it passes, each dose against the vehicle is called by Holm’s step-down procedure with Shaffer’s first step at the level R alpha / G, through stage_wise_adjusted_p_values(), on the moderated t-tests of the table "each_dose", or, under a gate with a fold change, on each dose’s TREAT p-value against that fold change, from the cell type’s fit computed again, as fit() computes it. The lowest effective dose is the lowest dose called: the lowest whose change is called or, with a fold change, the lowest whose change beyond it is called. The calls control the overall false discovery rate (OFDR) at alpha: the expected share of the genes passed with at least one false call, the gate’s or a dose’s, proved under independence between genes (Heller et al. 2009) and expected wherever Benjamini-Hochberg controls the false discovery rate (Van den Berge et al. 2017).

An effective dose here is a dose whose change is detectable at the stage-wise level, with no threshold on its size but the gate’s fold change: toxicology’s lowest observed effect level (LOEL), and the ICH E4 sense of a dose that shows an effect; the clinical minimum effective dose usually adds a clinically relevant size. It is a tested dose, not a potency between doses, and it moves with the replicates, the spacing of the doses and the gate’s FDR. A gene can pass the gate with no dose called. The values hold only at the gate’s FDR, and a call is a value at most it, as stageR counts; another level or another test is another gate, such as gate={"test": "williams", "fdr": 0.1} in dose_response() (https://docs.nygen.io/CytePool/statistics/dose-response#lowest-effective-dose).

Parameters:

group – A cell type that was tested; it may be left out when one cell type was checked.

Returns:

A table of one row per gene tested in the cell type, in the cube’s feature order, with feature_id, symbol (when the cube’s feature table has one), passes_gate (as in the table "gate"), lowest_effective_dose (in the axis’s unit; NaN when no dose is called), log2_fold_change and stage_wise_adjusted_p_value (that dose’s change from the vehicle and its stage-wise adjusted p-value; NaN with the dose), and n_doses_called.

Raises:
  • ValueError – If group is left out and several cell types were checked, or, under a gate with a fold change, the fit computed again no longer gives what the result records.

  • KeyError – If the cell type was not checked or not tested, or the gate was not run there; the message says why.

  • TypeError – If group is not a string.

Used in: Dose response per cell type

Explained in: Choosing a method, Multiple testing, Dose response