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):
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.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 bylimma_voom()(Law et al. 2014), the default,limma_trend()ordream_voom()(Hoffman and Roussos 2021), with their expression filter, normalization and empirical Bayes moderation (Smyth 2004).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; anddose_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); andmcp, 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).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).
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_valueadjusts the p-values of one cell type and test by Benjamini-Hochberg (Benjamini and Hochberg 1995), as limma’stopTabledoes, andadjusted_p_value_across_groupsadjusts 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’sp_valueis 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’sdose_treatedcolumn, for a dose column nameddose) 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 bysplineanddose_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 thecandidatesfor 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", withpasses_gate; the genes it passes are those whose dosesDoseResponseResult.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(), withbatch,groups,min_cellsandmin_counts, and the check is kept as the result’sdesign_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
countslayer, aslimma_voom()takes.design – A
Designof the terms other than dose, such asDesign(cube.samples, "~ 1")or"~ sex", with random intercepts fordream_voom, whose sample table has asample_idcolumn 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
DoseAxisof 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 whentestsdoes not name it, and decides which genes pass the gate and whose lowest effective doses are called:tests="williams"runs the spline too, andgate={"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
CandidateShapesof"mcp", with abeta_scaleof at least the top dose; None spreads the default shapes over the design’s doses,CandidateShapes.spread(dose, design.samples). Given only with"mcp", intestsor 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 whethertestsnames 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.gategives a result’s gate back.analysis –
limma_voom()(by default),limma_trend()ordream_voom(); a design with random intercepts needsdream_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 thatrng=<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) ordf_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
analysisis 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,gateor one of its settings, orrnghas the wrong type, or an argument is of a type thatcheck_dose_design()or the analysis refuses.ValueError – If
testsnames no test or a test twice, or names a test that the design cannot support;spline_dfis below 1 or above the doses on the axis minus 1, or given without two doses on the axis;candidatesare given without"mcp"or with abeta_scalebelow the top dose; a multiple contrast test is named withcontrast_standard_errors="limma";gatehas 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 withdream_voom, or"each_dose"without one;rngis a negative seed; the design names contrasts, has random intercepts with an analysis of limma or none withdream_voom; the sample table already holds a column of the name of a dose group’s indicator; or ascheck_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, withfeature_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) andstandardized_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 ofprovenance["groups"](f_test_df1)."linear_trend": the analysis’s table of a contrast, whoselog2_fold_changeis 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, withstandard_error(not for dream),average_log2_cpm,t,p_value,adjusted_p_value,adjusted_p_value_across_groupsandlog_odds; dream addsdfandz_statistic."dunnett","williams"and"mcp": multiple contrast tests, each gene as a whole, withfeature_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), itst,df(of the multivariate t),p_value(adjusted for the gene’s contrasts, the single-step max-t test) andp_value_error(its Monte Carlo standard error),adjusted_p_value(Benjamini-Hochberg over the cell type’s genes) andadjusted_p_value_across_groups. Each contrast’s weights on the treated doses are in the cell type’s entry ofprovenance["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), withfeature_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) andpasses_gate, whetheradjusted_p_valueis 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.summaryhas 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_residualanddf_priorof 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 reasonstable()gives; andn_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, asfits, each tested cell type’s result of the analysis without its tables, from whichfit()andcurve()compute the cell type’s fit again, and with thecubeanddesignanalysed, from whichpermutation_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
summaryis not aTable,tablesnot a mapping of (cell type, test) toTable,fitsnot a mapping of cell type toDifferentialExpressionResult,design_reportnot aDoseDesignReport,provenancenot a mapping that JSON can write,cubenot aCubeordesignnot aDesign.ValueError – If
provenanceholds a NaN or an infinity, or one ofcubeanddesignis 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,fdrandfold_change, as a new dict thatdose_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, asDoseAxis.to_dict()gives it), the spline’s basis (spline_basis, asto_dict()gives it), the tests andspline_dfas given, the candidate shapes of"mcp"(candidates, asCandidateShapes.to_dict()gives them; None without"mcp"), the seed of the multiple contrast tests (seed; None when none ran), the gate (gate, asgategives it), the analysis, andbatch,groups,min_cellsandmin_counts. The analysis’s other options are in the provenance’sanalysis_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
groupis left out and several cell types were checked, ornameis left out.TypeError – If
groupis 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 ofprovenance["groups"]: each dose against the vehicle, named after its indicator such asdose_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
groupis 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
groupis 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_lowerandci_upper.- Raises:
TypeError – If
groupis not a string,genesis not a feature id or symbol or a list of them, oratis not real-valued, or either is or holds a numpy masked array.ValueError – If
groupis left out and several cell types were checked; the result is ofdream_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 ofatis 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, throughstage_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, asfit()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}indose_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_changeandstage_wise_adjusted_p_value(that dose’s change from the vehicle and its stage-wise adjusted p-value; NaN with the dose), andn_doses_called.- Raises:
ValueError – If
groupis 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
groupis not a string.
Used in: Dose response per cell type
Explained in: Choosing a method, Multiple testing, Dose response