Fit a daily cosine¶

Question¶

What are this recording's rhythm amplitude and peak time?

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

When to use¶

Use this to estimate the level, amplitude and peak time of an approximately daily rhythm.

Example figure¶

Fit a daily cosine output generated by Circadian Workbench

This deterministic example is calculated by the cosinor action and drawn by render_cosinor_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("cosinor", 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("cosinor", recording, config=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. A returned processed_trace spec retains transformed values, their original clock, source identity and explicit processing history. Versioned recording_snapshot specs are self-contained numeric inputs for replaying in-memory Recording objects; they do not invoke a raw-activity importer.
`config`	object	no	`null`	-	Partial scientific settings. Omitted or None values use the shared installed defaults; invalid fresh values are rejected. Run describe_config for names, meanings, units, bounds and choices. Explicitly load old saved mappings with load_saved_settings to report compatibility conversions.

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

How it works¶

A 24-hour cosine is fitted to the selected recording by least squares.

$$ y(t)=M+A\cos(2\pi(t-\phi)/24) $$

Implementation: analysis.py::cosinor.

Outputs and interpretation¶

The result reports mesor, amplitude, peak phase, fit quality and test evidence.

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¶

A fixed daily cosine can conceal drift, changing amplitude or multiple components.

Example¶

The figure above is a real package result from a seeded, redistributable synthetic dataset. The flat gallery bundle retains figure_data_daily-cosine.csv, a standalone plot_daily-cosine.py, source hashes, an editable SVG, and a rendered preview.

Methods text¶

A 24-hour cosinor was fitted to the selected trace and its mesor, amplitude and acrophase were reported.