Dose curves#

Fit dose-response curves of named models to every gene, and compare them; Curves of named models explains the models and how to read the fits.

Fit dose-response curves of named models to every gene, and compare them.

A moderated test says that a gene responds to a dose, not what shape the response takes. fit_dose_curves() fits a named set of models to each gene of a samples x genes matrix of log-scale values, such as log2 CPM, and DoseCurveFits holds each fit with its parameters, log-likelihood, AIC and AICc (Akaike’s criterion corrected for small samples), Akaike weight (each model’s share of support among the gene’s models), lack-of-fit test, largest scaled residual and the gene’s best model. dose_response() fits the same sets to the dose groups of each cell type, with the variances of its moderated fit. The sets, their means and bounds, the variance modes and how to read the fits are in https://docs.nygen.io/CytePool/statistics/dose-response#dose-response-model-curves.

The sets:

"epa": the eight models of NTP 2018 and of EPA’s Transcriptomic Assessment Products (US EPA 2024), linear, polynomial of degree 2, power, Hill and exponential 2 to 5, in the forms and bounds of BMDS (US EPA 2026), with BMDS’s parameter letters; "ll4": the four-parameter log-logistic curve of drc’s LL.4 (Ritz et al. 2015); "dromics": DRomics’ families (Larras et al. 2018; Delignette-Muller et al. 2023), linear, exponential, the log-logistic curve and the Gauss-probit and log-Gauss-probit curves, which can rise and then fall, each of their four- and five-parameter forms a model of its own. Hill, sigmoid Emax and four-parameter log-logistic curves are one family (Kappenberg et al. 2023): "ll4"’s curve is the Hill curve with a slope from 0.1.

The fits:

Each gene’s dose-group means are sufficient for its fit: under constant variance the samples’ sum of squares about a curve is the within-group sum of squares plus Q = sum_k n_k (ybar_k - f(x_k))^2, so each model is fitted to the K means with weights n_k. Each fit starts from the three lowest local minima of a fixed grid of its nonlinear parameters, at which the linear ones are solved exactly (variable projection; Golub and Pereyra 1973), and each start is refined within the model’s bounds, so that no fit needs a seed or a start and the larger maximum is found where a search from one start can stop short.

Model choice:

AIC = -2 LL + 2k and AICc = AIC + 2k(k + 1) / (n - k - 1) count k = p + 1 parameters, the p of the mean and the variance, and n samples (Hurvich and Tsai 1989); AICc is infinite when n <= k + 1. Akaike weights are exp(-Delta / 2) over their sum, Delta the AICc minus the gene’s lowest (Burnham and Anderson 2002).

References

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

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

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

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

Larras F, Billoir E, Baillard V, Siberchicot A, Scholz S, Wubet T, Tarkka M, Schmitt-Jansen M, Delignette-Muller ML (2018). DRomics: a turnkey tool to support the use of the dose-response framework for omics data in ecological risk assessment. Environmental Science & Technology 52, 14461-14468. doi:10.1021/acs.est.8b04752

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

Golub GH, Pereyra V (1973). The differentiation of pseudo-inverses and nonlinear least squares problems whose variables separate. SIAM Journal on Numerical Analysis 10, 413-432. doi:10.1137/0710036

Hurvich CM, Tsai CL (1989). Regression and time series model selection in small samples. Biometrika 76, 297-307. doi:10.1093/biomet/76.2.297

Burnham KP, Anderson DR (2002). Model Selection and Multimodel Inference, 2nd edition. Springer, New York. doi:10.1007/b97636

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

US EPA (2012). Benchmark Dose Technical Guidance. EPA/100/R-12/001, Risk Assessment Forum, US Environmental Protection Agency, Washington, DC.

Ringblom J, Johanson G, Öberg M (2014). Current modeling practice may lead to falsely high benchmark dose estimates. Regulatory Toxicology and Pharmacology 69, 171-177. doi:10.1016/j.yrtph.2014.03.004

EFSA Scientific Committee (2021). Opinion on the impact of non-monotonic dose responses on EFSA’s human health risk assessments. EFSA Journal 19, e06877. doi:10.2903/j.efsa.2021.6877

class cytepool.stats.dose_curves.DoseCurveFits(model_set, models, models_not_fitted, parameter_names, variance, doses, n_samples, means, covariance, covariance_scale, df, parameters, log_likelihood, aic, aicc, akaike_weight, lack_of_fit_p_value, max_abs_scaled_residual, parameters_at_bounds, turn_dose, converged, not_fitted_reason, best, turn_driven_by_dose)#

The fits of a set of dose-response models to every gene, with the data they were fitted to.

Rows of the arrays are genes, in the order given; the model axis holds the set’s models fitted, in set order (models). The arrays are read-only. https://docs.nygen.io/CytePool/statistics/dose-response#dose-response-model-curves gives each model’s mean and bounds and explains how to read the fits.

Variables:
  • model_set – "epa", "ll4" or "dromics".

  • models – The set’s models fitted, in set order.

  • models_not_fitted – The set’s other models, each with the reason: a model of p parameters needs a spare dose group, K - p of at least 1.

  • parameter_names – The set’s parameter letters, the last axis of parameters: BMDS’s for "epa", where Hill’s k is the EC50, the dose of half the change v; DRomics’ for the others, where the log-logistic curve ll4 has b > 0 its slope, d its level at dose 0, c its level at high doses and e its EC50, the dose of half the change. drc’s LL.4 estimates (b, c, d, e) with b < 0 are (-b, d, c, e).

  • variance – How the means were weighed: "constant", "weighted" or "moderated".

  • doses – (K,) the dose of each dose group, ascending.

  • n_samples – (K,) the samples of each dose group.

  • means – (n_genes, K) the dose-group means the curves were fitted to.

  • covariance – (n_genes, K, K) their unscaled covariance, diag(1 / n_k) under constant variance.

  • covariance_scale – (n_genes,) the variance that multiplies covariance to give the covariance of the means: the pooled within-group variance under constant variance, NaN without replicates; the residual variance of the cell type’s moderated fit in dose_response() ("weighted"); or its moderated variance ("moderated").

  • df – (n_genes,) the degrees of freedom of covariance_scale.

  • parameters – (n_genes, n_models, n_parameter_names) the parameters of each fit, NaN where a model has no such parameter or was not fitted.

  • log_likelihood – (n_genes, n_models): under constant variance that of the samples with the variance at its maximum, -n/2 (log(2 pi sigma^2) + 1) with sigma^2 the residual sum of squares over n, as BMDS and drc report it; otherwise that of the means given their covariance.

  • aic – (n_genes, n_models) AIC, counting every parameter of the mean and the variance, also those at a bound.

  • aicc – (n_genes, n_models) AICc, AIC corrected for small samples, with the same count.

  • akaike_weight – (n_genes, n_models) each fitted model’s share of the gene’s support, exp(-Delta / 2) over the sum, Delta its AICc minus the lowest; 0 for an infinite AICc, NaN where not fitted.

  • lack_of_fit_p_value – (n_genes, n_models) the F-test of the curve against free dose-group means, F = Q / ((K - p) s^2) on K - p and df degrees of freedom, s^2 the covariance_scale and Q the weighted sum of squares of the means about the curve; read at 0.1 (US EPA 2012). It is exact for curves linear in their parameters; under constant variance it is the pure-error test of lack of fit, of which BMDS’s test 4, n log(1 + (K - p) F / df) on a chi-square of K - p degrees of freedom, is the large-sample form. NaN without replicates and for cell types that support only description.

  • max_abs_scaled_residual – (n_genes, n_models) the largest |ybar_k - f(x_k)| / se_k over the doses, se_k = sigma / sqrt(n_k) under constant variance and s sqrt(C_kk) otherwise; above 2 warrants a look.

  • parameters_at_bounds – (n_genes, n_models) the parameters of each fit that sit at a bound, comma-separated, empty for none.

  • turn_dose – (n_genes, n_models) the dose at which the fit’s slope changes sign strictly between 0 and the top dose; NaN when it does not turn there, as a curve that peaks at the top dose does not. Only Gauss-probit curves with f other than 0 can turn.

  • converged – (n_genes, n_models) False when the refinement stopped at its limit of 500 iterations before converging; the fit keeps the best point found and its statistics.

  • not_fitted_reason – (n_genes, n_models) why a model was not fitted to the gene, empty when it was: exponential 2 to 5 where a dose-group mean is not positive, and every model when the values do not vary or, in the weighted and moderated modes, when the means’ variance is 0 to rounding.

  • best – (n_genes,) the position in models of the gene’s lowest AICc, the first in set order within 1e-8 of it; -1 when no AICc is finite.

  • turn_driven_by_dose – (n_genes,) for a gene whose best fit turns, the lowest dose whose group, left out, leaves a best fit of the set that does not turn within the doses kept; 0 when that group is the vehicle’s, so test it with numpy.isfinite. NaN when the best fit turns without each group, for genes whose best fit does not turn, and for every gene when no model that can turn has a spare dose group among the K - 1 groups left, as at 5 dose groups; the printout then says that the turns were not checked.

Explained in: Dose response

table(*, feature_ids=None)#

Return the fits as a table, one row per gene and model fitted.

Genes in order, and each gene’s models in set order: feature_id, model, the set’s parameter columns (NaN where the model has no such parameter), n_parameters, spare_groups (K - p), log_likelihood, aic, aicc, akaike_weight, best (True for the gene’s best model), lack_of_fit_p_value, max_abs_scaled_residual, parameters_at_bounds, turn_dose, turn_driven_by_dose (on the best row; NaN on the others), converged and not_fitted_reason.

Parameters:

feature_ids – One id per gene, as text; by default feature_0, feature_1, …

Raises:
  • ValueError – If feature_ids does not give one id per gene.

  • TypeError – If an id is not text, or feature_ids is a numpy masked array.

Explained in: Dose response

cytepool.stats.dose_curves.fit_dose_curves(doses, values, *, models='epa', n_threads=None)#

Fit a set of dose-response models to every gene, under constant variance.

Each gene’s values are fitted against dose by maximum likelihood with a constant variance, as BMDS, drc and DRomics fit individual data: through the dose-group means with weights n_k, which give the samples’ likelihood. Each model is fitted from the lowest points of a fixed grid of its nonlinear parameters and refined within its bounds, so the results need no seed and do not depend on the number of threads. A model of p parameters is fitted only with a spare dose group, K - p of at least 1 (Ringblom et al. 2014); exponential 2 to 5 are not fitted to a gene with a dose-group mean at or below 0, and no model to a gene whose values do not vary. A gene whose best fit turns is fitted again without each dose group in turn, to show whether one group drives the turn (EFSA 2021). https://docs.nygen.io/CytePool/statistics/dose-response#dose-response-model-curves gives the models’ means and bounds and how to read the fits.

Parameters:
  • doses – One dose per sample, finite and at least 0; the dose groups are the distinct doses. No vehicle (dose 0) is required.

  • values – (n_samples, n_genes) log-scale values, such as log2 CPM, finite and at most 1e100 in size.

  • models – The set of models: "epa" (default; linear, polynomial_2, power, hill, where k is the EC50, the dose of half the change v, and exponential_2 to exponential_5, as BMDS writes them), "ll4" (the four-parameter log-logistic curve: b > 0 its slope, d its level at dose 0, c its level at high doses and e its EC50, the dose of half the change; drc’s LL.4 estimates (b, c, d, e) with b < 0 are (-b, d, c, e)) or "dromics" (DRomics’ linear, exponential and log-logistic curves and its Gauss-probit forms).

  • n_threads – The most threads to use; None keeps numba’s setting.

Returns:

The fits, with the dose-group means and covariance they were fitted to.

Raises:
  • TypeError – If doses or values do not hold real numbers, are numpy masked arrays, or models is not a string.

  • ValueError – If values is not 2-D with one row per dose, a value or dose is not finite, a value is larger than 1e100 in size, a dose is negative, two distinct doses differ by less than 1e-8 of the dose, the doses form fewer than two groups, models names no set, or no model of the set has a spare dose group.

Example

>>> import numpy as np
>>> doses = np.repeat([0.0, 0.1, 0.3, 1.0, 3.0, 10.0], 3)
>>> rng = np.random.default_rng(1)
>>> mean = 6.0 + 2.0 / (1.0 + (1.0 / np.maximum(doses, 1e-12)) ** 2)
>>> values = (mean + rng.normal(0.0, 0.1, doses.size))[:, None]
>>> fits = fit_dose_curves(doses, values, models="ll4")
>>> [round(float(v), 1) for v in fits.parameters[0, 0]]  # b, c, d, e
[2.1, 8.0, 6.0, 1.0]

Explained in: Choosing a method, Dose response