Measure a dose response¶

Question¶

How much stimulus does it take to move the clock?

See every package-generated example · Read the complete analysis pipeline

When to use¶

Use this when phase shifts were measured at several doses delivered at comparable circadian times.

Example figure¶

Measure a dose response output generated by Circadian Workbench

This deterministic example is calculated by the dose_response action and drawn by render_dose_response_svg, the same renderer used for publication export. Empty or withheld elements are therefore visible exactly as they are in a real result.

import circadian_workbench as cw

cw.call("dose_response", dose_points=points, dose_unit="lux")

Required inputs and controls¶

The public function is the registered action below. settings= is accepted as a friendlier alias for config= by cw.call; the calculation stores the complete normalized config in provenance.

Function reference¶

cw.call("dose_response", dose_points, config=None, dose_unit=None)

Arguments and parameters¶

Name	Type	Required	Default	Units	Meaning
`dose_points`	array	yes	—	-	The phase shifts of one dose series, as [[dose, shift_hours, label, circadian_time], ...] or as objects with "dose", "shift_hours", an optional "label" naming the animal and an optional "circadian_time". One entry per animal per dose. The dose is in whatever unit the stimulus was measured in and the package never guesses which; the shift follows the Aschoff sign convention the rest of the package uses, advance positive.
`config`	object	no	`null`	-	Partial analysis config. Missing keys fall back to analysis.DEFAULT_CONFIG and out-of-range values are clamped silently — run describe_config for every key, its default and its allowed values, or normalize_config to see what a given config actually becomes.
`dose_unit`	string	no	`null`	-	What the dose was measured in -- lux, uW/cm2, mg, photons. A label and nothing else: it is printed wherever a dose is printed and no arithmetic is done with it. Omit it and no unit appears anywhere, which is the honest output for a package that was not told what was measured.

Every nested config key, default, allowed value, and purpose is listed in the complete configuration reference.

How it works¶

A Hill curve is fitted to dose and shift points, while animal-level bootstrap resampling preserves the biological unit when estimating uncertainty.

$$ \Delta(d)=M\frac{d^n}{ED_{50}^{\,n}+d^n} $$

Implementation: dose_response.py::dose_response.

Outputs and interpretation¶

The result reports fitted maximum response, slope, half-maximal effective dose, confidence intervals, curve coordinates, saturation, circadian-time spread, and withholding reasons.

cw.call returns a Result: use .data for calculated values, .warnings for scientific qualifications, .provenance for version and input identity, .script for an equivalent replay script, and .files for saved outputs.

Limitations¶

At least four dose levels are required. The half-maximal effective dose is withheld outside the tested range, and circadian-time imbalance can confound dose with phase sensitivity.

Example¶

The figure above is a real package result from a seeded, redistributable synthetic dataset. Its audited project bundle retains figure_data.csv, a standalone plot.py, source hashes, an editable SVG, and a rendered preview.

Methods text¶

Dose-dependent phase shifts were fitted with a Hill curve, with uncertainty estimated by resampling independent animals and the half-maximal effective dose withheld when it lay outside the tested range.