Dose axes#
Dose axes record where each dose sits on the axis of a dose-response curve, and give the design columns of a spline of dose; Dose axes and the vehicle explains them.
Dose axes: where each dose sits along the axis of a dose-response curve, and the design columns of a spline of dose.
A dose series has a vehicle, the samples given no dose, and treated samples at a few
doses, often spaced by a constant factor. A curve of dose follows an axis: the
logarithm of the dose, on which equal factors are equal steps, or the dose itself.
The vehicle’s dose of 0 has no logarithm, so DoseAxis either keeps the
vehicle as a group of its own, separated from the treated samples by a column of the
design, or places it on the axis by adding a recorded offset to every dose, as
DoseFinding’s model log(dose + off) does (Bornkamp et al. 2026). sci-Plex-GxE
added 0.001 to every dose, a pseudocount chosen from experiments whose data are not
shown (McFaline-Figueroa et al. 2024); the offset decides where the vehicle sits and
the slope at the low end, which is why it is recorded rather than built in. The axis
also records the unit and the metric, what the dose measures (administered, nominal,
measured or internal), so that knots and curves print in the dose’s own terms
(https://docs.nygen.io/CytePool/statistics/dose-response#dose-axes).
References
Bornkamp B, Pinheiro J, Bretz F, Sandig L, Thomas M, Sabanes Bove D (2026). DoseFinding: Planning and Analyzing Dose Finding Experiments. R package version 1.4-2. https://cran.r-project.org/package=DoseFinding
McFaline-Figueroa JL, Srivatsan S, Hill AJ, Gasperini M, Jackson DL, Saunders L, Domcke S, Regalado SG, Lazarchuck P, Alvarez S, Monnat RJ, Shendure J, Trapnell C (2024). Multiplex single-cell chemical genomics reveals the kinase dependence of the response to targeted therapy. Cell Genomics 4, 100487. doi:10.1016/j.xgen.2023.100487
- class cytepool.DoseAxis(column, *, unit, metric, scale='log10', vehicle='own_group', offset=None)#
The axis along which a curve of dose is fitted, with the vehicle’s place on it.
Records the dose column of a sample table, the dose’s unit and metric, whether the curve follows log10 of the dose or the dose itself, and where the vehicle, the samples of dose 0, goes: in a group of its own (
"own_group"), or on the axis ("on_axis"), on the log10 scale at an offset added to every dose. With the vehicle in its own group, a column of the design marks the treated samples, the spline columns are 0 for the vehicle, and the spline is fitted along the treated doses; a dose of 0 has no position on the axis. From the axis,spline_basis()places the knots of a natural cubic spline on the samples’ doses, anddesign_columns()gives the columns that enter the design (https://docs.nygen.io/CytePool/statistics/dose-response#dose-axes).- Parameters:
column – The column of the sample table that holds each sample’s dose, finite and at least 0, with 0 for the vehicle.
unit – The unit of the doses, such as
"ug/kg","uM"or"Gy", which messages and records print.metric – What the dose measures:
"administered", the amount given to the animal or person, as mg/kg;"nominal", the amount added to the medium;"measured", the amount measured in the medium, blood or tissue; or"internal", the amount at the target estimated by a model.scale –
"log10"(default), positions at log10 of the dose, or"linear", at the dose itself.vehicle –
"own_group"(default), the vehicle is a group of its own, marked by{column}_treated, and the spline runs along the treated doses; or"on_axis", the vehicle sits on the axis, at log10(offset) on a log10 axis or at 0 on a linear one.offset – With
scale="log10"andvehicle="on_axis", and only then: a dose, above 0, added to every dose before its logarithm is taken, so that the vehicle sits at log10(offset).
- Raises:
TypeError – If
columnorunitis not a str, an option is not a str, oroffsetis not a real number.ValueError – If
columnorunitis empty, an option is not one of its choices, oroffsetis missing where the vehicle sits on a log10 axis, given elsewhere, or not positive and finite.
Example
>>> axis = DoseAxis("dose", unit="ug/kg", metric="administered") >>> samples = {"dose": [0.0, 0.0, 0.1, 0.1, 1.0, 1.0, 10.0, 10.0]} >>> basis = axis.spline_basis(samples, df=2) >>> knots = axis.doses(basis.knots), axis.doses(basis.boundary_knots) >>> [k.round(6).tolist() for k in knots] [[1.0], [0.1, 10.0]] >>> columns = axis.design_columns(samples, basis) >>> list(columns) ['dose_treated', 'dose_s1', 'dose_s2'] >>> columns["dose_s1"].tolist() [0.0, 0.0, 0.0, 0.0, 1.0, 1.0, 2.0, 2.0]
Used in: Dose response per cell type
Explained in: Choosing a method, limma-voom and limma-trend, Dose response
- positions(doses)#
Where each dose sits on the axis.
log10(dose) on the log10 scale, log10(dose + offset) with the vehicle on a log10 axis, and the dose itself on the linear scale; NaN for the vehicle, dose 0, when it is a group of its own.
- Parameters:
doses –
(n,)doses in the axis’s unit, finite and at least 0.- Returns:
(n,)float64 positions.- Raises:
TypeError – If
dosesis not real-valued or is a numpy masked array.ValueError – If
dosesis not 1-D, or holds a value that is not finite or is negative.
Explained in: Dose response
- doses(positions)#
The doses at positions on the axis, the inverse of
positions().Converts positions on the axis, such as knots, back to doses in the axis’s unit: 10^position, minus the offset when the vehicle sits on a log10 axis, or the position itself on the linear scale. The round trip through
positions()can differ from the dose in the last bit.- Parameters:
positions –
(n,)real positions; NaN marks a missing value, and stays NaN.- Returns:
(n,)float64 doses.- Raises:
TypeError – If
positionsis not real-valued or is a numpy masked array.ValueError – If
positionsis not 1-D or holds an infinite value.
Explained in: Dose response
- spline_basis(samples, df=None, *, knots='levels', form='restricted_cubic')#
The basis of a natural cubic spline of dose, with knots placed on the samples’ doses.
The knots and the boundary knots, the lowest and highest doses on the axis, are placed on the positions of the samples that have one: the treated samples when the vehicle is a group of its own, and every sample when it is on the axis. Pass the basis to
design_columns(), and read its knots in doses withdoses(). The spline columns and the intercept, with{column}_treatedwhen the vehicle is a group of its own, fitdf + 1distinct doses on the axis, sodfis at most the number of distinct doses on the axis minus one; at that maximum the curve passes through the mean of every dose group.- Parameters:
samples – The sample table, a
Table, a mapping of column name to 1-D values, or a pandas DataFrame, with the dose column.df – The number of spline columns, from 1 up. Needed with a rule; with knots given, it must agree with them (
len(knots) + 1).knots – A rule of
NaturalSplineBasis:"levels"(default), R’s quantile rule on the distinct doses, each counted once whatever its number of replicates, so that a knot can fall between two doses; or"quantiles", R’s rule fornson the samples’ positions. Or the interior knots as doses in the axis’s unit, strictly between the lowest and highest dose on the axis.form –
"restricted_cubic"(default), whose first column is the position minus the lower boundary knot, so that the other columns test departure from a straight line; or"b_spline", the columns of R’snsup to a change of basis. Both stay well conditioned when doses crowd.
- Returns:
The basis, without an intercept.
- Raises:
TypeError – If
samplesis not a table or holds a numpy masked array, its dose column is not numeric,dfis not an integer, or the knots are not real numbers.ValueError – If
knotsnames no rule of a dose axis; the dose column is missing or holds a dose that is not finite or is negative; fewer than two distinct doses are on the axis, or two of them differ by less than 1e-8 of the dose;dfis missing with a rule, disagrees with given knots or exceeds the distinct doses on the axis minus one; a given knot is not strictly between the lowest and highest dose on the axis; any two knots coincide; or the rule cannot place the knots.
Explained in: Designs, linear models and contrasts, Dose response
- design_columns(samples, basis)#
The design columns of a spline of dose, at each sample’s dose.
In this order:
{column}_treated, 1 for a dose above 0 and 0 for the vehicle, when the vehicle is a group of its own; then{column}_s1to{column}_s{df}, the basis at each sample’s position, 0 for the vehicle when it is a group of its own. Every spline column vanishes at the lower boundary knot, so that{column}_treatedis the difference between the curve there and the vehicle’s mean, at the lowest dose with the rules"levels"and"quantiles". The vehicle’s rows change no F-test that keeps the intercept and{column}_treated, and no fitted curve: only what those two coefficients mean.The result is a dict of float64 arrays, which
Table.with_columnsadds to the sample table.samplescan be any table with the dose column, such as a grid of doses at which to draw a fitted curve.- Parameters:
samples – The sample table, a
Table, a mapping of column name to 1-D values, or a pandas DataFrame, with the dose column.basis – A basis of this axis, from
spline_basis(): its knots are positions on this axis, and a basis placed on other values gives columns without meaning.
- Returns:
The columns by name.
- Raises:
TypeError – If
samplesis not a table or holds a numpy masked array, its dose column is not numeric, orbasisis not aNaturalSplineBasis.ValueError – If the dose column is missing or holds a dose that is not finite or is negative, or the basis has an intercept.
Explained in: Designs, linear models and contrasts, Dose response
- to_dict()#
The axis as plain values that JSON stores: its six fields.
DoseAxis(**axis.to_dict())rebuilds the axis.Explained in: Dose response