Fit the two-process sleep model¶

Question¶

Which sleep-pressure parameters are supported by this record?

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

When to use¶

Use this after immobility sleep scoring when homeostatic sleep pressure and a circadian threshold are to be modelled without claiming uniquely identified parameters.

Example figure¶

Fit the two-process sleep model output generated by Circadian Workbench

This deterministic example is calculated by the two_process_fit 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_fit", sleep_result=sleep_result, period_hours=24, acrophase_hours=4)

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_fit", sleep_result, period_hours=None, acrophase_hours=None, config=None)

Arguments and parameters¶

Name	Type	Required	Default	Units	Meaning
`sleep_result`	object	yes	—	-	An immobility_sleep result, whole. A record it refused to score is refused here for the same reason rather than re-derived.
`period_hours`	float	no	`null`	hours	The cycle the phases live on. Omit to use the config's period_hours (24 h by default). A free-running cohort should pass its own tau, so that 'one cycle' means one of the animals' cycles rather than one solar day. `splitting` uses it for a second purpose that is the same idea: the period the resolution element P**2/T is worked out at, which sets how far apart two components must be before that record can show them to differ.
`acrophase_hours`	number	no	`null`	hours	The circadian term's acrophase, in hours, from the package's own measurement. It is echoed back unchanged: a model that re-fitted it would compete with the measurement it came from.
`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¶

Sleep pressure rises exponentially while awake and falls exponentially while asleep. Repeated optimisation retains every parameter set that ties the best mismatch, so the result is a family rather than an unjustified single fit.

$$ \frac{dS}{dt}=\frac{U-S}{\tau_w}\ \text{awake},\qquad \frac{dS}{dt}=\frac{L-S}{\tau_s}\ \text{asleep} $$

Implementation: two_process.py::two_process_fit.

Outputs and interpretation¶

The result contains measured and predicted sleep profiles, the tied parameter ensemble and intervals, mismatch, transition coverage, identifiability, convergence, day-to-day scatter, 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 public inputs are the complete sleep result, circadian period, acrophase, and config; optimiser bounds and starting values are internal. Inadequate transitions or days are refused, and parameters are reported as ranges when not identifiable.

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¶

A two-process sleep model was fitted to the complete immobility-sleep result by repeated bounded optimisation; all parameter sets tying the best mismatch were retained and parameter ranges were reported when the record did not identify a unique fit.