Measure re-entrainment¶

Question¶

How quickly did the clock catch a shifted schedule?

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

When to use¶

Use this after an explicitly dated schedule shift to estimate recovery time and trajectory.

Example figure¶

Measure re-entrainment output generated by Circadian Workbench

This deterministic example is calculated by the reentrainment action and drawn by render_reentrainment_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("reentrainment", recording={"path": "jet_lag.awd"}, shift_day="2026-01-11")

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("reentrainment", recording, config=None, shift_day=None)

Arguments and parameters¶

Name	Type	Required	Default	Units	Meaning
`recording`	recording spec	yes	—	-	The record to analyse: {'path': 'data/m01.awd'} (a bare path string also works), {'demo': true} for the built-in deterministic record, {'inline': {'filename': ..., 'text': ...}} for tabular text, {'trace': {'hours': [...], 'values': [...], 'name': ...}} for one elapsed-time trace, or {'channels': {'hours': [...], 'values': {'reporter_a': [...], 'reporter_b': [...]}}} for several measurements from one subject.
`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.
`shift_day`	string	no	`null`	-	The date the light schedule moved, as YYYY-MM-DD. Omit it and the date is read out of the schedule itself; supply it when the schedule in the config does not carry the move. The shift date belongs to neither side: the first full day on the new schedule is day 1.

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

How it works¶

Daily marker deviation from the post-shift baseline is followed across days. Recovery requires a held run inside the configured tolerance, and an exponential decay describes the trajectory when identifiable.

$$ D(d)=A e^{-d/\tau_r},\qquad t_{1/2}=\tau_r\ln 2 $$

Implementation: entrainment.py::reentrainment.

Outputs and interpretation¶

The result contains daily phase deviations, tolerance, first held recovery day, exponential time constant and half-life, pre/post coverage, and convergence notes.

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¶

The analysis needs enough valid days on both sides of the shift. A transient crossing of the tolerance is not recovery unless it persists for the configured hold.

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¶

Re-entrainment was measured from daily marker deviation after the declared schedule shift; recovery required a held run within the configured baseline-derived tolerance, and an exponential trajectory was fitted where supported.