Find ultradian rhythms¶

Question¶

Is there a repeatable rhythm faster than one day?

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

When to use¶

Use this when a reproducible component shorter than the circadian cycle is suspected.

Example figure¶

Find ultradian rhythms output generated by Circadian Workbench

This deterministic example is calculated by the ultradian action and drawn by render_ultradian_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("ultradian", 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("ultradian", 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¶

The configured circadian cosinor is removed first, then the residual is searched over the ultradian band. Resolution, samples per cycle, relative amplitude, and harmonic guards decide whether the peak is reportable.

$$ \delta P=\frac{P_{\mathrm{fast}}^2}{T},\qquad A_{\mathrm{rel}}=\frac{A_{\mathrm{fast}}}{A_{\mathrm{circadian}}} $$

Implementation: ultradian.py::ultradian_component.

Outputs and interpretation¶

The result includes the candidate period, power and significance, reconstructed component, relative amplitude, resolution, harmonic relation, samples per cycle, guards, and 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¶

Short records and circadian harmonics can mimic ultradian structure. A spectral peak is withheld when resolution, sampling, amplitude, or harmonic guards fail.

Example¶

The figure above is a real package result from a seeded, redistributable synthetic dataset. Its editable SVG embeds the exact plotted data and provenance and is included with a rendered preview in the installed help. The separate authoring bundle retains figure_data_ultradian-rhythms.csv, a standalone plot_ultradian-rhythms.py and source hashes; these companion files are not installed application files.

Methods text¶

The circadian component was removed before searching the declared ultradian band; candidates were required to pass resolution, sampling, relative-amplitude, and harmonic guards.