Predict the entrainment range¶

Question¶

Which zeitgeber periods can this phase response curve entrain to?

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

When to use¶

Use this only after accepting a fitted phase-response curve and a free-running period, to ask which zeitgeber periods admit stable entrainment.

Example figure¶

Predict the entrainment range output generated by Circadian Workbench

This deterministic example is calculated by the entrainment_range action and drawn by render_entrainment_range_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("entrainment_range", curve=prc, tau_hours=24)

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("entrainment_range", curve, tau_hours, config=None)

Arguments and parameters¶

Name	Type	Required	Default	Units	Meaning
`curve`	object	yes	—	-	A phase_response_curve result, whole. Its `fit` is what is iterated; a curve with no fit -- too few animals -- is refused rather than predicted from.
`tau_hours`	number	yes	—	hours	The animal's own free-running period, in hours. The cohort curve does not carry it because a cohort has one per animal.
`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.

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

How it works¶

The measured curve is iterated as a phase map over the configured zeitgeber-period grid. Fixed points must supply the required daily correction and pass a local stability test.

$$ \phi_{n+1}=\left{\phi_n+\frac{24T}{\tau}+\Delta(\phi_n)\right}\bmod 24 $$

Implementation: prediction.py::entrainment_range.

Outputs and interpretation¶

The result includes the tested zeitgeber grid, required and available shifts, fixed points, stability, entrainable mask and ranges, convergence, curve provenance, and limitations.

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¶

A curve without a fitted periodic model is refused. Predictions remain conditional on the measured curve and do not substitute a generic oscillator model.

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¶

The accepted phase-response curve was iterated as a discrete phase map across the declared zeitgeber-period grid; entrainment required a stable fixed point supplying the necessary daily phase correction.