Detect two circadian components¶

Question¶

Is this record carrying two circadian rhythms at once?

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

When to use¶

Use this when one record appears to contain two close circadian components rather than one broad peak or a harmonic.

Example figure¶

Detect two circadian components output generated by Circadian Workbench

This deterministic example is calculated by the splitting action and drawn by render_splitting_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("splitting", recording={"path": "mouse01.awd"})

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("splitting", recording, config=None, period_hours=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.
`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.

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

How it works¶

The analysis finds two circadian spectral candidates, rejects unresolved and harmonic pairs, checks persistence, and compares a two-component cosinor with a one-component fit.

$$ \delta P=\frac{P^2}{T} $$

Implementation: splitting.py::split_components.

Outputs and interpretation¶

The result reports both component periods, separation, record resolution, persistence, joint-fit support, separation rate, each guard, and a final split/not-split verdict.

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¶

At least the configured duration is needed. Two large peaks are insufficient when their separation is below resolution or one is a harmonic of the other.

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¶

Potential rhythm splitting was assessed from two resolved circadian spectral components, harmonic and persistence guards, and the improvement of a two-component over a one-component cosinor fit.