Candidate shapes#

The candidate shapes of a dose response that the MCP step of dose_response tests, spread over a series’ doses or given; Trends, doses against the vehicle and candidate shapes explains them.

Candidate shapes of a dose response, for the MCP step of MCP-Mod.

MCP-Mod, multiple comparison procedure and modelling (Bretz, Pinheiro and Branson 2005; Pinheiro et al. 2014), tests for a dose signal under uncertainty about the shape of the response, then models it. Its first step, the MCP step, is the test: the analyst guesses a few plausible shapes, each becomes the contrast of the dose groups that best detects it, and the largest of the contrasts’ t-statistics is referred to the multivariate t distribution. CandidateShapes holds the guesses in the model families of DoseFinding (Bornkamp et al. 2026), as the change from the vehicle along dose: Emax, sigmoid Emax, exponential and beta. Its spread() places a few shapes of each family over the doses of a series, so that their contrasts cover monotone responses that start early, midway or late, and umbrella responses that rise and fall; means() gives each shape’s mean change at the doses, from which optimal_contrasts() builds the contrasts. dose_response() runs the step with tests=("mcp",) (https://docs.nygen.io/CytePool/statistics/dose-response#dose-response-contrasts).

References

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

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

class cytepool.CandidateShapes(emax=(), sigmoid_emax=(), exponential=(), beta=(), beta_scale=None)#

Candidate shapes of a dose response: guesses of the mean change from the vehicle along dose, for the MCP step of MCP-Mod (multiple comparison procedure and modelling), its test for a dose signal.

Each shape is a curve of dose d in one of DoseFinding’s model families (Bornkamp et al. 2026), up to its size, which the step does not need:

  • emax: d / (ED50 + d), a rise that slows from the start and reaches half its plateau at ED50;

  • sigmoid_emax: d^h / (ED50^h + d^h), the Hill equation with ED50 and Hill slope h, a rise that starts slowly when h is above 1;

  • exponential: exp(d / delta) - 1, a rise that grows with dose, the change from the vehicle of BMDS’s exponential 2 model a exp(b d) with b = 1 / delta (US EPA 2026); a small delta keeps the shape flat until the top doses;

  • beta: (d / s)^delta1 (1 - d / s)^delta2 with the scale s = beta_scale, an umbrella shape, which rises to a peak at s delta1 / (delta1 + delta2) and falls.

There is no linear shape, as DoseFinding’s advice for MCP-Mod has it: an Emax shape with a large ED50 and an exponential shape with a large delta are nearly linear. The step tests each shape’s direction with the contrast of the dose groups that best detects it, so a shape and the same shape scaled or shifted give one contrast. Build the shapes from prior guesses of ED50s and peaks, or let spread() place them over the doses of a series (https://docs.nygen.io/CytePool/statistics/dose-response#dose-response-contrasts).

Parameters:
  • emax – The ED50 of each Emax shape, in the dose’s unit.

  • sigmoid_emax – (ED50, Hill slope) of each sigmoid Emax shape.

  • exponential – delta of each exponential shape, in the dose’s unit.

  • beta – (delta1, delta2) of each beta shape, exponents: for a peak at P, delta1 = k P / s and delta2 = k (1 - P / s), and a larger k narrows the peak.

  • beta_scale – The beta model’s scale s, at least the top dose, in the dose’s unit; given with beta shapes, and only then.

Each family takes a list with one entry per shape, such as emax=[0.5] for one shape; every parameter is finite and above 0, and there is at least one shape.

Raises:
  • TypeError – If a family is not a list of numbers (emax, exponential) or of pairs of numbers (sigmoid_emax, beta), or a value is not a real number, or an argument is a numpy masked array.

  • ValueError – If there is no shape, a parameter is not finite and above 0, or beta_scale is missing with beta shapes or given without them.

Example

>>> shapes = CandidateShapes(emax=[0.2, 2.0], beta=[(0.5, 2.0)], beta_scale=12.0)
>>> shapes.names
('emax_1', 'emax_2', 'beta')
>>> shapes.means([0.0, 0.1, 1.0, 10.0]).round(3).tolist()[0]
[0.0, 0.34, 0.85, 1.0]

Used in: Dose response per cell type

Explained in: Choosing a method, Dose response

property names#

The shapes’ names in order, each the name of its family, such as "emax", with _1, _2, … when the family has several shapes.

Explained in: Dose response

means(doses)#

Each shape’s mean change from the vehicle at doses, scaled as DoseFinding scales them: 1 at the highest dose for rising shapes, 1 at the peak for beta shapes.

A shape’s change is 0 at dose 0 and is scaled to 1 at the highest of doses for the rising shapes, and at its peak for a beta shape, wherever the peak lies, as DoseFinding’s getResp(Mods(..., doses = doses)) gives the means with its default placebo effect 0 and maximal effect 1. The contrasts of the MCP step do not depend on the scale.

Parameters:

doses – (n_doses,) doses in the dose’s unit, finite and at least 0, at most beta_scale with beta shapes, and at least one above 0.

Returns:

(n_shapes, n_doses) float64 means, the shapes in the order of names.

Raises:
  • TypeError – If doses is not real-valued or is a numpy masked array.

  • ValueError – If doses is not 1-D, holds a dose that is not finite or is negative, has no dose above 0, or holds a dose above beta_scale.

Explained in: Dose response

to_dict()#

The shapes as plain values that JSON stores.

CandidateShapes(**shapes.to_dict()) rebuilds them.

Explained in: Dose response

classmethod spread(axis, samples, *, n_emax=2, n_sigmoid_emax=1, n_exponential=1, n_beta=1)#

Place candidate shapes over the doses of a series.

Between the lowest and highest treated dose of the samples, along the axis’s positions (log10 of the dose, of the dose plus the offset when the vehicle sits on a log10 axis, or the dose on a linear axis), the j-th of m shapes of a family is placed at the fraction j / (m + 1) of the way:

  • Emax: ED50 there;

  • sigmoid Emax: ED50 there, with a Hill slope of 3, steeper than an Emax shape’s slope of 1 along log dose;

  • exponential: half its change at the top dose D reached at (1/2 + j / (2 (m + 1))) D, on the dose scale, since an exponential shape reaches half its change only above D / 2 (0.75 D for one shape);

  • beta: the peak there, half the peak’s change halfway between the lowest treated dose and the peak, along the axis, and the scale 1.2 D, DoseFinding’s default.

The defaults, two Emax, one sigmoid Emax, one exponential and one beta shape, give five shapes from four families, within the 3 to 7 shapes from 2 to 4 families that DoseFinding’s advice for MCP-Mod finds sufficient (Bornkamp et al. 2026): early, midway and late monotone rises, and an umbrella peaking mid-range. https://docs.nygen.io/CytePool/statistics/dose-response#dose-response-contrasts explains the rule.

Parameters:
  • axis – The DoseAxis of the series.

  • samples – The sample table, a Table, a mapping of column name to 1-D values, or a pandas DataFrame, with the axis’s dose column, such as design.samples.

  • n_emax – The number of Emax shapes, 0 or more.

  • n_sigmoid_emax – The number of sigmoid Emax shapes, 0 or more.

  • n_exponential – The number of exponential shapes, 0 or more.

  • n_beta – The number of beta shapes, 0 or more.

Returns:

The shapes, in the dose’s unit.

Raises:
  • TypeError – If axis is not a DoseAxis, samples is not a table or holds a numpy masked array, its dose column is not numeric, or a count is not an integer.

  • ValueError – If a count is negative or all are 0; the dose column is missing, holds a dose that is not finite or is negative, or has fewer than two distinct doses above 0.

Example

>>> from cytepool import DoseAxis
>>> 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]}
>>> shapes = CandidateShapes.spread(axis, samples)
>>> shapes.names
('emax_1', 'emax_2', 'sigmoid_emax', 'exponential', 'beta')
>>> [round(ed50, 4) for ed50 in shapes.emax]
[0.4642, 2.1544]

Used in: Dose response per cell type

Explained in: Choosing a method, Dose response