Fit a phase response curve¶

Question¶

How does stimulus timing change the clock?

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

When to use¶

Use this when independent animals received a timed stimulus and the response must be related to each animal's circadian phase.

Example figure¶

Fit a phase response curve output generated by Circadian Workbench

This deterministic example is calculated by the phase_response_curve action and drawn by render_phase_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("phase_response_curve", animals=animals)

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("phase_response_curve", animals, config=None)

Arguments and parameters¶

Name	Type	Required	Default	Units	Meaning
`animals`	array of objects	yes	—	-	One entry per animal in the pulse experiment. Either a record to score -- {'recording': spec, 'stimulus': '2026-01-08 18:00', 'label': 'm01', 'config': {...}} -- or a point already scored elsewhere: {'circadian_time': 15.2, 'shift_hours': -1.4, 'label': 'm01'}. A record needs fit1_start/fit1_end before the pulse and fit2_start/fit2_end after it in its config, and 'stimulus' is the wall-clock time the pulse landed (or hours from the start of the record's first day). An animal whose pre-stimulus fit is too short is dropped with a warning rather than failing the cohort.
`config`	object	no	`null`	-	Partial scientific settings. Omitted or None values use the shared installed defaults; invalid fresh values are rejected. Run describe_config for names, meanings, units, bounds and choices. Explicitly load old saved mappings with load_saved_settings to report compatibility conversions.

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

How it works¶

Pre-stimulus onset regression supplies circadian time and the before/after marker fits supply phase shift. A periodic harmonic regression is then fitted across animals using the advance-positive Aschoff convention.

$$ \Delta(\phi)=a_0+\sum_{h=1}^{H}\left[a_h\cos!\left(\frac{2\pi h\phi}{24}\right)+b_h\sin!\left(\frac{2\pi h\phi}{24}\right)\right] $$

Implementation: phase_response.py::phase_response_curve.

Outputs and interpretation¶

The curve includes animal points, fitted values, coefficients, uncertainty, advance and delay extrema, dead-zone estimate, phase coverage, and type-classification diagnostics.

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¶

Animals without adequate pre/post fits are dropped and named. A curve needs the configured minimum animals and phase coverage; clock-time stimulus bins are not a substitute for circadian time.

Example¶

The figure above is a real package result from a seeded, redistributable synthetic dataset. Its editable SVG embeds the exact plotted data and provenance and is included with a rendered preview in the installed help. The separate authoring bundle retains figure_data_phase-response-curve.csv, a standalone plot_phase-response-curve.py and source hashes; these companion files are not installed application files.

Methods text¶

Per-animal circadian stimulus time and phase shift were scored from declared marker fits and modelled by periodic harmonic regression using the advance-positive Aschoff convention.