Skip to content

Fit curves of named dose-response models in each cell type - #85

Merged
parashardhapola merged 10 commits into
masterfrom
dose/10-dose-curves
Nov 22, 2026
Merged

parashardhapola merged 10 commits into
masterfrom
dose/10-dose-curves

Conversation

@parashardhapola

Copy link
Copy Markdown
Member

The problem

A moderated test says that a gene responds to a dose, not what shape the response takes or how sure that shape is. Reports of transcriptomic dose response name a curve: the genomic dose-response approach of the National Toxicology Program and EPA's Transcriptomic Assessment Products (ETAP) fit eight models in BMDS or BMDExpress, linear, polynomial, power, Hill and exponential 2 to 5, and choose one per gene (NTP 2018; US EPA 2024); pharmacologists fit drc's four-parameter log-logistic curve (Ritz et al. 2015); and DRomics adds Gauss-probit curves for responses that rise and then fall (Larras et al. 2018; Delignette-Muller et al. 2023). Until now CytePool gave a spline with a band and no named curve.

Each of those tools fits a gene's samples with their own variance and no weights, from starting values of its own, and none fits curves per cell type. Starting values and optimizers matter: on the series of this PR's validation, pybmds 25.2's maximum fell below that of the same model in 44 of 152 fits, drc 4.0-0's in 17 of 20 even with relTol = 1e-12, and DRomics' nls fits failed for 80 of its items and families and fell below for 13 of the 55 compared. Three replicates also strain the usual lack-of-fit test: BMDS's test 4 compares a likelihood ratio with a chi-square, which at nominal 0.10 rejects a correct straight line in 25% of experiments at 9 doses x 3 and in 38% at 9 doses x 2 (exact). A curve fitted without a spare dose group cannot test its own shape, and benchmark doses from such fits were non-protective in up to 80% of some four-group scenarios (Ringblom et al. 2014). A bell can rest on one outlying dose group, which EFSA found behind most apparent non-monotone responses (EFSA 2021).

The solution

dose_response(models=...) fits a set of named models to every gene of each cell type, and cytepool.stats.dose_curves.fit_dose_curves to a matrix of values outside a cube:

result = cp.dose_response(cube, cp.Design(cube.samples, "~ 1"), dose=axis, models="epa")
curves = result.table("hepatocyte", "curves")   # every gene and model
best = curves.filter(curves["best"])            # each gene's best model by AICc
called = best.filter(best["passes_gate"])       # those of the genes that pass the gate
fits = result.curve_fits("hepatocyte")          # DoseCurveFits: arrays, means, covariance
result.curve("hepatocyte", genes, model="best")  # the curve as a change from the vehicle
plot_dose_response(result, "hepatocyte", genes=genes, model="best")
  • Three sets. "epa": linear, polynomial_2, power, hill and exponential_2 to exponential_5 in BMDS's forms, letters and bounds, written in dose units, with c of exponential 4 and 5 at most 1,000, CytePool's own bound where BMDS sets none. "ll4": drc's LL.4 with b > 0 the slope, d the level at dose 0, c the level at high doses and e the EC50, DRomics' letters; drc's (b, c, d, e) with b < 0 are CytePool's (-b, d, c, e). "dromics": linear, exponential, ll4 and the Gauss-probit and log-Gauss-probit curves, each four- and five-parameter form a model of its own.
  • Three variance modes. "constant", the default: each gene's values in the cell type's fit refitted against dose under one variance, as BMDS fits a gene's samples. "weighted" and "moderated": the dose-group means of the cell type's moderated fit by generalised least squares with their covariance, which carries voom's weights and the design's other terms, and the residual or moderated variance (Pinheiro et al. 2014). A design with terms besides dose needs the weighted modes.
  • Each fit. The parameters, log-likelihood, AIC, AICc counting the variance (Hurvich and Tsai 1989), Akaike weight (Burnham and Anderson 2002), the F-test of lack of fit against free dose-group means in every mode (the pure-error test under constant variance, exact for curves linear in their parameters; read at 0.1, US EPA 2012), largest scaled residual, spare dose groups, parameters at bounds and convergence; each gene's best model, the first in set order within 1e-8 of the lowest AICc.
  • Fits not made. A model without a spare dose group is not fitted in the cell type (models_not_fitted); 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 (not_fitted_reason).
  • Turns. turn_dose gives where a Gauss-probit curve's slope changes sign strictly between 0 and the top dose, from its closed form; a curve that peaks at the top dose rises over every dose. For each gene whose best fit turns, the whole set is refitted without each dose group in turn, and turn_driven_by_dose gives the lowest dose without whose group the best fit no longer turns, 0 for the vehicle's. The check needs a model that can turn with a spare group among the K - 1 groups left, so from 6 dose groups; at 5, turn_driven_by_dose is NaN and the printouts say that the turns were not checked.
  • The gate's call. Where the gate ran, passes_gate follows each gene's ids in the curves table, matched to the table "gate" by feature id, so that curves cover every filtered gene and curves.filter(curves["passes_gate"]) keeps those of the genes that pass; cell types without the gate have no such column.
  • Cell types that support only description get curves under constant variance, from the values a fit would compute, without lack-of-fit p-values.
  • Model curves at any dose from 0 to the top dose, as every model is fitted with the vehicle at dose 0, and figures whose legend names each gene's model.
  • No seed. At each point of a fixed grid of a model's nonlinear parameters, the linear ones are solved exactly within their constraints (variable projection; Golub and Pereyra 1973); the three lowest local minima of the grid each start a refinement in Kaufman's form (Kaufman 1975), and the best result is kept.

Why it matters

Named curves are where CytePool's toxicological analysis starts. PR 11 computes benchmark doses and their bounds from these fits, PR 12 reads EC50s and Hill slopes from the log-logistic set, PR 13 averages models with the Akaike weights computed here, PR 14 applies NTP's and ETAP's rules to the "epa" set, and PR 24 calibrates a test of the curves. The PR builds on PR 6's simulator, whose series the validation and the guide fit, and on PR 7's dose_response, whose moderated fit of each cell type gives the weighted modes their means, covariance and variances. It sits on PR 8's contrast tests and PR 9's gate (#84): each cell type runs its tests and its gate, then fits its curves, with the vehicle's contrast added to the same fit; the curves table carries the gate's call, which PR 9 left to the later of the two PRs, and the chapter sends readers to the gate for which genes respond. Because each fit starts from a grid rather than from guesses, a gene's curve needs no seed and does not depend on the number of threads, and the validation can hold every reference's maximum as a lower bound.

Validation

validation/dose_curves.py (new) simulates five dose series with PR 6's simulator: the vehicle and 8 half-log doses x 3 in two cell types, one of which loses its top dose; 4 decades x 3; 3 decades x 2; a cell type of single samples at 5 doses, which supports only description; and a design with sex. For turns, it adds genes that turn, or do not, by construction (a raised dose group, bells over three groups, rises at the top dose alone, flat genes) at 5, 6 and 9 dose groups under constant variance and at 9 and 5 in the weighted mode. Each reference runs as a program of its own on the same doses and values, with each model's mean and bounds written in the script from the documentation. A fit's maximum may not fall below a reference's by more than 1e-8 of the residual variance (or of Q / (K s^2) in the weighted modes), and parameters of fits that reach the same maximum off every bound, where the data identify them, are compared in standard errors scaled by the likelihood's gap.

Check Reference Tier Largest difference
Maxima not below scipy's best of 200 starts, every set under constant variance (408 fits) and in the weighted (208) and moderated (208) modes scipy 1.18.1 least_squares 1e-8, scale-free 4.2e-10
Log-likelihoods of the reported parameters by the documented means (824 fits) the documented formulas exact (1e-10) 4.7e-14
"epa" maxima not below pybmds's better direction (152 fits) pybmds 25.2 1e-8 of the residual variance 3.4e-13
Parameters where both reach the maximum, off every bound and identified (40) pybmds 25.2 10 SE per sqrt(2 dLL) 8.6
AIC penalty and test 4's degrees of freedom; test 4's p-values from CytePool's F, n log(1 + (K - p) F / (n - K)) on a chi-square (108 each) pybmds 25.2 identical; close (1e-6) 0 mismatches; 6.6e-9
F-test of lack of fit under constant variance, of the line and of the quadratic where its restriction does not bind (61) R 4.4.3 anova of nested lm fits exact (1e-10) 2.2e-14
Largest scaled residual (108), in units of 2 sqrt(n 1e-8) pybmds 25.2 1 0.073
"ll4" maxima not below drc's (20); parameters (3) drc 4.0-0 LL.4 1e-8; 10 SE -3.3e-13; 0.93
"dromics" lowest AICc of each family per sample (55); chosen model's parameters (27); the turn at DRomics' estimates (1) DRomics 2.6.3 drcfit 0.005 AICc units, its rounding, then 1e-8 per sample; 10 SE; 1e-3 -4.9e-6; 4.7e-4; 0
Weighted modes: genes, dose-group means (10,006), unscaled covariance (1,262 genes), residual and moderated variances, lack of fit of a line; limma-trend's own F (631) limma 3.62.1, edgeR 4.4.0 exact (1e-10) 2.4e-14
Descriptive cell type: genes, means and pooled variance of voom's log2 CPM limma voom exact (1e-10) 1.6e-12
Whether each best fit turns (126); the dose of each of the 47 turns, and the dose group that drives it, none at 5 dose groups the documented slope; the rule coded in the script with scipy's refits of the set on K - 1 groups identical; exact; identical 0 mismatches; 0; 0 mismatches

Deliberate differences: pybmds completed no fit in 3 of its 304 runs (each fit then completed in the other direction), and its maximum lay below CytePool's in 44 of 152 fits (polynomial 2 17, Hill 11, exponential 5 9, exponential 3 4, power 3), by up to 9.0 log-likelihood units, and never beyond CytePool's bounds: pybmds's own exponential 5 fits went to c of 41, 69 and 183 though its table of priors lists [0, 20], so CytePool bounds c at 1,000, where its fits of those three genes run along the ridge to c near 1,000 with maxima above pybmds's. drc's maximum lay below in 17 of 20 fits. DRomics' fits failed for 80 of its items and families and lay below, beyond the rounding of its printed criteria, for 13 of the 55 compared; one Gauss-probit family lay 0.02 below in AICc where DRomics reports no parameters, and scipy's search within CytePool's bounds found no higher maximum there. 330 of CytePool's 27,712 fits reached 500 iterations before the stopping rule held, nearly all in the weighted and moderated modes, sliding along flat valleys, and keep the best point found; the scipy rows, which cover 4 genes of each cell type, set and mode, find every fit they cover at the maximum.

pybmds's PyPI wheel lacks NLopt's Luksan LBFGS and falls back to another optimizer when a fit asks for it. A probe that ran each pybmds fit in a process of its own found that 234 of the 304 runs attempted LBFGS; they completed as often as the others (the 3 incomplete runs had not attempted it), and their better direction fell below CytePool's maximum in 35 of 139 fits, against 6 of the 13 fits that never tried LBFGS. These fits give no sign that the fallback causes pybmds's lower maxima. This PR compares no BMDs; PR 11 should compare them only where pybmds reaches the maximum.

dose_response_calibration.py gains rows of shape recovery: on the power datasets of 9 dose groups with 3 replicates, the best fit's change from the vehicle to the top dose had the true sign, or turned for a bell, for 0.729 to 0.735 of about 2,600 responsive genes under "epa" in every variance mode, 0.736 under "ll4" and 0.766 under "dromics", whose best fits turned for 0.637 of the true bells but rested on one dose group in 0.960 of the flat genes' turns; PR 8's 101 rows came back identical. plotting.py gains two rows for the curves of a model, against drc's log-logistic formula evaluated in R: 5.9e-15 for the drawn curves and 4.0e-15 for their points, exact.

Recorded runs before the rebase onto #84, each the second of two runs in one container (4 CPU, 8 GiB, AMD Zen 3): dose_curves.py 4,454 s and 1,030 MiB (its references take most of it: 200-start scipy searches of every fit, and 100-start refits of the whole "dromics" set without each dose group for the 47 turning genes), dose_response_calibration.py 3,211 s and 455 MiB, plotting.py 32.3 s and 883 MiB. dose_curves.py --benchmark fit 10,000 genes in 37.4 s with "epa" and 35.7 s with "dromics", and dose_response with weighted curves took 30.2 s on a cell type of 10,000 genes against 0.58 s without curves; on the same kind of host before the reviews' changes, 41.6, 34.0 and 35.7 s. The benchmark's baseline is the ordinary least squares fit, while the performance targets use the weighted fit of linear_models.py --benchmark, which a probe on an AMD Zen 3 host timed at 0.200 s: the curves cost about 190 such baselines with "epa" and 180 with "dromics", against the target of 350. The calibration script's 111 rows are those of its previous run but its two "dromics" rows, whose shares moved by 0.001 (turns now count strictly within the doses). The fixtures were byte-identical in the recorded run and the run before it. The helper also lists scripts whose checked code this PR changes without changing what they compute, as they import cytepool.plotting, cytepool.dose_responses or cytepool._group_fits, whose expression filter moved into one function: activity.py, combined_p_values_and_replication.py, cube_collection.py, differential_expression.py, differential_expression_options.py, dose_axes.py, dose_contrasts.py, dose_design.py, dose_gate.py, dose_response_tests.py, dream.py, gene_set_files_and_ora.py, gene_set_tests.py, gsea.py, interferon_stimulated_pbmcs.py, kenward_roger_and_f_tests.py, meta_analysis.py, pathway_scores.py, pca_and_dot_plots.py, rotation_gene_set_tests.py, sumrank.py and variance_partitioning.py.

The rebase onto #84 (PR 9's gate) merged only the two PRs' additions: a merge of the two heads differs from the rebased branch only in dose_responses.py and the calibration script, where each definition that both PRs changed holds both sides' changes and nothing else. Short runs at the merged code, in place of second recorded runs, show every script's rows unchanged. The CytePool side of dose_curves.py (its series, every fit, the inputs of each reference and the turn tasks, 423,805 values) is bit-identical to that of the recorded code, and the script is unchanged, so its references see the same inputs. On a few datasets of every design cell of the calibration, each dose_response result and permutation check of its rows was bit-identical at #84's code and at the merged code (153 calls, 1,237,226 values with the printed rows), and those of its curve rows at the recorded code (10 calls, 375,125 values; #84's n_genes_passing_gate column is the only addition). plotting.py, dose_gate.py and dose_contrasts.py, run once at the merged code, printed every row of their recorded runs: 32, 26 and 80 checks, none failed. The Validation page gives the calibration's 149 checks from its two recorded runs, #84's 139 and this PR's 111, which printed their 101 shared rows alike, and a total of 3,394 checks. At the merged code, docs/changed_since_run.py lists the 39 scripts it lists on master and four more: dose_curves.py and dose_response_calibration.py, whose records are of the runs above, and dose_gate.py and dose_contrasts.py, which this PR's code reaches.

The last four commits add passes_gate to the curves table and correct docstrings. The table is built when asked for, and the scripts read only feature_id and named parameter columns from it, while docstrings do not count in the digests, so the helper lists the same 43 scripts. The same probes, run again at the final head on the machine that ran them at 93bedc2, found the CytePool side of dose_curves.py (423,805 values) and the calibration's curve rows (10 calls, 375,135 values) bit-identical.

Modal runs, all ephemeral apps in cytearc_profiling through the shared harness:

Run Why Resources Duration Result
Three full runs of dose_curves.py while writing it The script against its references 4 CPU, 8 GiB 80 s, 46 min, 32 min an R matrix fixed; then 9 failed checks (scipy gaps in the weighted modes, pybmds beyond bounds, voom's span), fixed; then 1 (unidentified parameters), fixed
pybmds probes (API, rows, two fallback probes) pybmds's fields, its rows alone, and the Luksan question 2 to 4 CPU, 4 to 8 GiB 10 s to 4 min findings above
pr10-dromics-turns Why the row of turns compared nothing 2 CPU, 4 GiB 83 s DRomics' one bell was a lower maximum
Guide checks on AVX-512, 7 tries CI's runners have AVX-512 4 to 8 CPU, 8 GiB 0 s to 82 s one landed on AMD Zen 4 with AVX-512: outputs current; a local stand-in covered the merged guide
Recorded runs, launched 5 times Twice in one container; two launches were stopped when the code changed (a turn computed without exp; the rebase onto #83 and the package's private-name rules), one was superseded by the rebase, and the curves script ran once more after the fix of DRomics' count 4 CPU, 8 GiB per container final: 41 and 103 min 41, 111 and 32 checks, none failed
pr10-curves-baseline The curves against the weighted baseline (limma_voom with its observation weights) in one run 4 CPU, 8 GiB 390 s 219 and 180 baselines
pr10-docs-build CI's docs build and the guide's outputs 4 CPU, 8 GiB 287 s built without warnings; outputs current
dose_curves-write-fixtures (review) One run of dose_curves.py after the reviews' changes, before the recorded runs, writing the fixtures 8 CPU, 8 GiB 1,050 s, after one preemption 43 checks, none failed
pr10-review-guide-avx512, -2 (review) The changed guide's outputs on a host with AVX-512 4 CPU, 8 GiB 8 s and 3 s AMD Zen 3 without AVX-512 both times
pr10-review-dose-curves-twice, pr10-review-calibration-plotting-twice (review) The recorded runs on the final code, the curves script with its benchmark and --write-fixtures 4 CPU, 8 GiB per container 162 and 111 min 43, 111 and 32 checks, none failed; fixtures byte-identical
pr10-review-guide-avx512-3, -4 and pr10-review-docs-build (review) Two more tries for an AVX-512 host; CI's docs build and the guide's outputs 4 CPU, 8 GiB 3 s, 4 s and 270 s no AVX-512 again (a local stand-in with every transcendental result moved by one unit in the last place found the outputs current); built without warnings, outputs current
pr10-rebased-docs-build (rebase) CI's docs build and the guide's outputs at the rebased head 4 CPU, 8 GiB 258 s built without warnings; outputs current
Recorded runs at the rebased head, two launches (rebase) The curves script with its benchmark, and the calibration and plotting scripts, twice in one container 4 CPU, 8 GiB per container stopped with the session, under 30 min in no result; replaced by the short runs
plotting, dose_gate, dose_contrasts (merged code) Each script once, its rows against its recorded run 4 CPU, 8 GiB per container 169, 188 and 302 s 32, 26 and 80 checks, none failed, every row as recorded
pr10-final-docs-build CI's docs build and the guide's outputs at 93bedc2 4 CPU, 8 GiB 287 s built without warnings; outputs current
pr10-verify-docs-build CI's docs build and the guide's outputs after the verify stage's changes, with numpy's CPU features as CI leaves them 4 CPU, 8 GiB, AMD Zen 3 313 s built without warnings; outputs current
pr10-verify-full-suite The full suite at the final head while the local lock was held by another job 8 CPU, 8 GiB, AMD Zen 3 766 s 6,224 passed, 36 skipped, none failed

Tests

tests/test_dose_curves.py and the curve tests of tests/test_dose_responses.py and tests/test_plotting.py check:

  • Every model's mean against the formula written in the tests from the chapter, and its analytic gradient against central differences, at interior points and at the limits (dose 0, k = 0, rate 0, n = 1).
  • Noise-free curves of every model recovered to 1e-8; the line and the quadratic against least squares in closed form; log-likelihoods, AICc and Akaike weights derived by hand, also in the weighted modes against scipy's multivariate normal density; the F-test of lack of fit derived by hand on unequally spaced doses in every mode, against scipy's F distribution; BMDS's scaled residuals of a line by hand.
  • Fits not made, bounds and turns: exponentials not fitted at a mean at or below 0, a gene whose values do not vary under constant and weighted variance, models without a spare dose group listed, parameters at bounds named (c recovered at 30 and stopped at 1,000), a Hill k beyond the top dose, Gauss-probit widths and peaks within their bounds; turns below the lowest dose counted, peaks at the top dose not counted, turn doses as extrema of the documented mean, the drop-one data equal to the data of the samples left, the drivers equal to the rule computed with the public function on the samples without each group, the lower of two doses reported, the vehicle as a driver, and turns at 5 dose groups not checked; cell types without curves, each with its reason, also beside a cell type with curves.
  • Against the fixtures of validation/dose_curves.py: maxima not below scipy's 200-start optimum in every set and mode, pybmds's and drc's maxima with their AIC penalties, test 4 from the F-test, scaled residuals and parameters, DRomics' criteria and the doses of its turns, and 47 verdicts of the dose group that drives a turn by the script's own coding of the rule, 14 of them at 5 dose groups; the means, covariance (M V M') and variances of the weighted modes and their lack-of-fit p-values against limma, rebuilt from the fixture's counts; the vehicle's mean at the average of the samples the fit uses.
  • Invariants and records: the same fits in any gene order, dose unit and number of threads; refusals with a fix; the table and the pickled result; PR 7's tables, summary and figure unchanged with curves; the gate's call in the curves table, gene by gene against the table "gate" on a series where both calls occur, and no such column in a cell type whose spline cannot run or that supports only description.

Deliberate bugs, each applied to the source and caught by the test named:

Deliberate bug Outcome Caught by
No refinement: the grid's best point kept caught test_constant_maxima_reach_scipys_best_of_200_starts
One refinement, from the grid's lowest point only caught test_constant_maxima_reach_scipys_best_of_200_starts
The means' covariance as V, not M V M' caught test_weighted_curve_data_match_limma[ladder abundant voom-weighted]
W = I under constant variance caught test_linear_and_polynomial_are_least_squares
S_w left out of the log-likelihood caught test_linear_and_polynomial_are_least_squares
AICc with k = p caught test_aicc_and_akaike_weights_by_hand
AICc with n = K caught test_aicc_and_akaike_weights_by_hand
Akaike weights from AIC caught test_aicc_and_akaike_weights_by_hand
Lack of fit by test 4 under constant variance caught test_lack_of_fit_by_hand
The F-test on K - p - 1 numerator degrees of freedom caught test_lack_of_fit_by_hand
Hill's k bounded at the top dose caught test_locations_reach_beyond_the_doses
No k = 0 point in Hill's grid survived: equivalent, since k = d_min / 100 with n = 18 already gives the step to rounding none
Turns counted on (lowest dose, top] caught test_a_turn_below_the_lowest_dose_counts
A sign slip in z* of the turn caught test_turn_doses_are_extrema_of_the_documented_mean, test_a_turn_below_the_lowest_dose_counts
The vehicle never left out of the refits caught test_a_turn_can_rest_on_the_vehicle
The same model refitted, not the whole set caught test_turns_and_the_group_they_rest_on
Exponentials declined only below 0 caught test_declines
The quadratic's sign restriction ignored caught test_linear_and_polynomial_are_least_squares
A Jacobian column with a sign slip (Hill's k) caught test_noise_free_curves_are_recovered[epa-hill]
A Jacobian column with a sign slip (Gauss-probit width) caught test_noise_free_curves_are_recovered[dromics-gauss_probit]
Gauss-probit width floor at a tenth of the smallest gap caught test_gauss_probit_bounds_hold
The vehicle's mean as the intercept caught test_the_vehicles_mean_is_at_the_average_of_the_other_terms
Descriptive voom values with a prior count of 2 caught test_descriptive_values_are_those_a_fit_computes
The moderated mode on the residual degrees of freedom alone caught test_weighted_curves_use_the_fits_means_and_variances
The curves' baseline f(0) instead of the vehicle's mean caught test_model_curves
Turns checked at 5 dose groups caught test_turns_at_five_dose_groups_are_not_checked
A turn at the top dose counts caught test_a_peak_at_the_top_dose_is_not_a_turn
c bounded at 20 again caught test_bounds_are_reported
Descriptive cell types keep their lack-of-fit p-values caught test_descriptive_cell_types_get_curves_without_p_values
No check of the column of sample groups in dose_response caught test_a_column_of_sample_groups_is_checked_before_curves
Model curves refuse doses below the lowest caught test_model_curves
The legend leaves out the model caught test_plot_dose_response_draws_model_curves
A model's name gets no pointer to its set; values beyond 1e100 accepted caught test_arguments_are_refused_with_a_fix
Plug-in log det with the wrong sign; AICc with n = K; plug-in scaled residuals without s^2 caught test_plug_in_likelihood_aicc_and_residuals_by_hand
Constant scaled residuals with the pooled within-group SD caught test_constant_scaled_residuals_by_hand, test_epa_fits_reach_pybmds_maxima_with_its_statistics
The highest driving dose named, not the lowest caught test_the_lower_of_two_driving_doses_is_named, test_turn_drivers_follow_the_rule_with_refits_of_the_samples
Refits keep the dropped group's within-group sum of squares caught test_the_data_without_a_group_are_those_of_its_samples
The turn driver on every model's row caught test_the_table_puts_the_turn_driver_on_the_best_row
The vehicle's mean over every sample, used or not caught test_weighted_curves_with_a_sample_left_out
The gate's calls joined one gene off; a column in which no gene passes; a column of False where the gate did not run caught test_the_curves_table_carries_the_gates_call
passes_gate after the other columns instead of after the gene's ids caught test_the_curves_table_carries_the_gates_call, test_constant_curves_fit_the_samples_values, test_the_curves_table_carries_symbols

Coverage: dose_curves.py is covered in full, and so are this PR's lines of dose_responses.py, plotting.py and _group_fits.py; with NUMBA_DISABLE_JIT=1, every line and branch of the compiled kernels in _dose_curve_models.py and _dose_curve_search.py runs. The branches that no input could reach (a grid without a finite point, a step with no free parameter) were removed, and values whose sums of squares would overflow, beyond 1e100 in size, are refused.

At the final head, the full suite passed with 6,242 tests and 18 skipped (zstd needs Python 3.14), on this machine and on Modal, where 18 more skip because the container has no git checkout and runs as root; ruff, ruff format and mypy were clean.

Decisions

Decision Alternatives Reason
Fit every mode on the K dose-group means with a K x K weight matrix, adding the within-group sum of squares under constant variance Fit the samples The means are sufficient, so estimates and log-likelihoods are the samples', and problems of K values are fast
A fixed grid of the nonlinear parameters with the linear ones solved exactly (variable projection), the three lowest local minima refined in Kaufman's form Random starts with a seed; each reference's own starting values; Levenberg-Marquardt in all parameters Deterministic and thread-independent; Levenberg-Marquardt in all parameters zig-zagged when the linear parameters were re-solved, and stopped 5.6e-5 above scipy's optimum without the re-solve; a second grid minimum found a log-logistic basin that the best point missed
variance="constant" (default), "weighted", "moderated" "reference"; "residual" for "weighted" "Constant variance" is BMDS's term, and "reference" reads as the vehicle group; "weighted" says how the means are weighed, and PRs 11 and 17 use it
The F-test of lack of fit in every mode, F = Q / ((K - p) s^2) on K - p and the variance's degrees of freedom BMDS's test 4 under constant variance Test 4's chi-square rejects a correct curve in 25% of experiments at nominal 0.10 with 9 doses x 3 (38% at 9 x 2); the F is exact for curves linear in their parameters and is the plug-in modes' formula; pybmds's test 4 follows from it, n log(1 + (K - p) F / (n - K)), which the validation checks, and PR 14's rule sets can apply it
c of exponential 4 and 5 at most 1,000, CytePool's own bound 20, from pybmds's table of priors BMDS states no upper bound and pybmds's fits went to 183; a bound keeps finite the fits that approach a line, where c grows as b shrinks
Turns strictly between 0 and the top dose (0, D] A curve that peaks at the top dose rises over every dose, and the symmetric curves' peak bound made D a mass point (106 and 227 of 300 top-only rises in a probe)
A turn checked for a driving group only when a model that can turn has a spare group among K - 1, from 6 dose groups Refit at any K At 5 dose groups no refit can turn, so every turn would be put on the vehicle's group
AICc with k = p + 1 and n samples in every mode; ties within 1e-8 to the first model of the set Plain AIC in the plug-in modes; n = K One criterion whose penalty is the same in every mode; with n = K, a model with one spare group would never be chosen
Gauss-probit peaks within the doses and widths of at least a third of the largest gap Peaks to 5 D and widths from a tenth of the smallest gap A bell narrower than a gap made likelihood valleys without a maximum, and 38 to 46 of 300 genes' fits crawled unconverged; every dose then lies within half a gap of a dose, where a bell keeps 32% of its height
polynomial_2 restricted to coefficients of one sign, the better of both signs; both directions of the exponential models Unrestricted; BMDS's detected direction pybmds 25.2's default restriction; one bounded space per model
Bounds of "epa" from BMDS in dose units, with levels unbounded BMDS's bounds on its scaled response BMDS's scaling is not documented to reproduce; every fit with a level beyond 100 log2 units in the example (83 Hill and 82 log-logistic fits of 817) has a parameter at a bound, and the chapter says to read levels only where none is
One dose group drives a turn when, without that group, the best model of the whole set no longer turns; the vehicle included The same model refitted; turns on a dose grid Whether the chosen shape survives without one group (EFSA 2021); turns are exact from the closed form
"ll4" in DRomics' letters, b > 0 and d at dose 0; drc's (b, c, d, e) with b < 0 is (-b, d, c, e) drc's signs One convention in both sets, stated in the chapter; PR 12 maps GraphPad's slope from it
Model curves as f(x) minus the vehicle's mean f(x) - f(0) PR 7's baseline for its spline and the figure's points; PR 11's BMDs use f(0)
Descriptive cell types fitted under constant variance in every mode No curves They have no first-stage variance, and description is what they support
passes_gate in the curves table where the gate ran, after the gene's ids and matched by feature id No column, leaving a join with the table "gate"; a column of False where the gate did not run PR 9 gave the gate's call in the curves table to the later of PRs 9 and 10, so that curves cover every filtered gene with the call beside each (R4); False would read as a call where no gate ran
Parameters compared with a reference only where the data identify them (scaled Jacobian condition number at most 1e6) Every fit that reaches the same maximum A flat gene's power curve whose change rests on the top dose fixes v x^n there but neither v nor n, and standard errors along that ridge mean nothing
DRomics' turns checked at DRomics' own estimates Only where both reach the same maximum DRomics fitted one bell in the series, at a lower maximum than CytePool's
A gene whose values do not vary is declined even when its mean rounds, and a weighted gene whose means' standard error is below 1e-12 of their size Exact zeros The mean of three equal values can differ from them in the last place, and voom's weights scale rounding residuals
A symmetric curve's turn taken as e itself e exp(0) Keeps a peak at the top dose's bound at the bound, which the strict rule excludes, whatever a CPU's exp does
The curves' data helpers live in dose_responses.py; the parts of fit_dose_curves that dose_response runs are listed as shared A private module of their own; public names The package keeps code that one module uses in that module (tests/test_private_names.py), and lists such shared parts, as sumrank and variance_fractions do

Trimmed, with where each went: ETAP's Hill rule and AIC selection under a rule set to PR 14; curves of dream_voom fits to PR 21 (constant variance would ignore the random intercepts, and the weighted modes need degrees of freedom that dream's fits do not keep); bands of model curves to PRs 11 and 12, with profile-likelihood bounds; DRomics' selection filters, not reproduced, since PR 9's gate decides which genes respond; BMDS's non-constant and log-normal variance, out; exponents below 1 in power and Hill, not offered, as BMDExpress and ETAP restrict them; lists of models to PRs 13 and 21.

A moderated test says that a gene responds to a dose, not what shape the response takes, while reports of transcriptomic dose response name a curve: BMDS's eight models, drc's log-logistic curve or DRomics' curves that rise and then fall.

fit_dose_curves fits the sets "epa", "ll4" and "dromics" to a matrix of values under constant variance, and dose_response(models=..., variance=...) to every gene of each cell type, also by generalised least squares on the dose-group means of the cell type's moderated fit. Each fit starts from the lowest points of a fixed grid of its nonlinear parameters, with the linear ones solved exactly, and is refined within the model's bounds. Each gene gets every model's parameters, AICc, Akaike weight, F-test of lack of fit and largest scaled residual, its best model, where a bell turns and, from 6 dose groups, whether one dose group drives the turn; DoseResponseResult gains the table "curves", curve_fits and curve(model=...), and plot_dose_response draws model curves.

The curves need no seed, do not depend on threads, and take about 3.7 ms per gene with the eight EPA models.
… limma and R

validation/dose_curves.py fits five simulated series and genes built to turn, and runs pybmds 25.2, drc 4.0-0, DRomics 2.6.3, a 200-start scipy search, limma and R's anova on the same data in programs of their own: maxima, parameters, AIC penalties, test 4 from the F-test, lack-of-fit F-tests, the data of the weighted modes, turns and the dose group that drives each turn. dose_response_calibration.py gains rows of shape recovery and plotting.py the drawn model curves. --write-fixtures writes the fixtures that the tests read.
…d references

The tests write every mean from the chapter's formulas, check gradients against central differences, likelihoods, AICc, weights and lack-of-fit tests by hand, the rules of fits not made, bounds and turns, invariants of order, units and threads, and the fixtures of pybmds, drc, DRomics, scipy and limma; dose_response's curves are checked against fit_dose_curves, limma and R, and the figure against the documented formula.
The chapter's section on curves of named models gives each set's formulas and bounds, the variance modes, how fits are found, how to read the curves table and turns, and how BMDExpress's outputs map; Choosing a method, the glossary, the bibliography, the API reference and the guide gain the curves, and the Validation page the recorded runs.
…ields

#84 made the cube and the design keyword fields of DoseResponseResult, passed by pickling after the five positional ones; the curves join them as a keyword field, and the test of the fields' types follows. The guide was executed again with the curves' sections and the gate's in one notebook: every output of both is unchanged.
…tion page

After the rebase onto #84, the calibration's section and the page's total held placeholders for runs that never finished, which fails the tests of the page's openings and totals, and the chapter's description had grown to 218 characters, beyond the 200 a link preview shows.

The calibration's section now names the two runs whose rows it shows, on 2026-11-21: 139 checks without the rows of the curves and 111 without those of the gates, which printed the 101 rows they share alike, 149 checks in all. The total adds to 3,394 checks, none failed. The chapter's description lists its sections in their order, in 192 characters.
The plan puts the gate's call beside each gene's curves, and PR 9 left that to whichever of the two PRs merged second, but the curves table had no such column, so a reader had to join it with the table "gate" to keep the curves of the genes that pass.

table(g, "curves") now holds passes_gate after the gene's ids in every cell type where the gate ran, matched to the table "gate" by feature id; cell types without the gate, because its test did not run there or because they support only description, keep the table as it was. The chapter's table of columns and its reading of turns name the column.

A test checks the column against the table "gate" gene by gene on a series where both calls occur, and its absence in a cell type whose spline cannot run and in one that supports only description.
The search module's docstring still described a refinement that moves every parameter by Levenberg-Marquardt, from before the refinement became Kaufman's form of variable projection, and the docstring of the turn's dose divided the slope by b twice.

The module docstring now says that the refinement moves the nonlinear parameters along their projected Jacobian columns, solves the linear ones again at every point tried, and tries each parameter alone before it stops; the turn's slope is written once, with dz/dx for both forms.
The script's docstring said that 36 genes go to the references under constant variance and that the weighted modes compare a spread of 6 genes with limma, while the script sends 28 genes (12, 8 and 8 of the three series), compares every gene's means, covariance and variances with limma, and gives scipy's searches 4 genes of each cell type. The docstring now says so, as the Validation page does; docstrings do not count in the run records' digests.
The helper's docstring still named a series that supports only description, which a test of its own now builds; the helper builds the weighted curves of one series.
@parashardhapola
parashardhapola merged commit aea816a into master Nov 22, 2026
6 checks passed
@parashardhapola
parashardhapola deleted the dose/10-dose-curves branch November 22, 2026 20:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant