Predict re-entrainment¶

Question¶

How many cycles should a schedule shift take?

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

When to use¶

Use this after accepting a fitted phase-response curve to predict recovery after a proposed schedule advance or delay.

Example figure¶

Predict re-entrainment output generated by Circadian Workbench

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

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("predicted_reentrainment", curve, tau_hours, shift_hours, t_hours=24.0, 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.
`shift_hours`	number	yes	—	hours	How far the schedule moved, in hours, POSITIVE for an advance -- the transition arriving earlier -- which is the phase response curve's own sign convention.
`t_hours`	number	no	`24.0`	hours	The zeitgeber period the animal is being shifted within, in hours.
`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 same empirical phase map is iterated after the schedule is shifted. Recovery is the first held run inside the configured phase tolerance.

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

Implementation: prediction.py::predicted_reentrainment.

Outputs and interpretation¶

The result reports cycle-by-cycle phase error and correction, direction, recovery cycle, hold criterion, convergence, final phase, supplied periods and shift, and curve provenance.

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 prediction assumes the fitted curve remains valid under the proposed schedule. Lack of convergence or a curve outside its measured support must be interpreted as model limitation, not observed failure.

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 predicted by iterating the accepted empirical phase-response curve after the declared schedule shift until phase error remained within tolerance for the configured hold.