Predict sleep pressure¶

Question¶

What does the fitted sleep model predict under a new schedule?

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

When to use¶

Use this only with a completed two-process fit to explore a proposed schedule defined by days and cycle length.

Example figure¶

Predict sleep pressure output generated by Circadian Workbench

This deterministic example is calculated by the two_process_predict action and drawn by render_two_process_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("two_process_predict", fit=fit, schedule={"days": 7, "period_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("two_process_predict", fit, schedule, config=None)

Arguments and parameters¶

Name	Type	Required	Default	Units	Meaning
`fit`	object	yes	—	-	A two_process_fit result, whole. A fit with no parameters -- a record the model refused -- is refused here rather than run with defaults.
`schedule`	object	yes	—	-	The proposed schedule: `days`, `period_hours`, and optionally `acrophase_hours` and `label`. The acrophase defaults to the one the record was fitted under, which assumes the animal holds the same phase angle; where it would not, entrainment_range predicts the new one and it should be passed here.
`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¶

Every parameter set in the fitted family is simulated under the proposed schedule. Amount is summarised across the family, while timing is withheld when family members disagree beyond tolerance.

$$ S_{t+\Delta t}=S_t+\Delta t\,\frac{S_{\mathrm{target}}-S_t}{\tau_{\mathrm{state}}} $$

Implementation: two_process.py::two_process_predict.

Outputs and interpretation¶

The result reports proposed-schedule sleep fraction and range, profile and family band when timing agrees, disagreement, schedule fields, inherited fit quality, verdict, and 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 schedule contains days, period_hours, optional acrophase_hours, and optional label; it does not accept a hand-entered wake/sleep state series. A fit without a parameter ensemble is refused.

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¶

Every parameter set retained by the two-process fit was simulated under the proposed schedule; predicted amount was summarised across the family and timing was withheld when family disagreement exceeded tolerance.