Compare period estimates¶

Question¶

Which period estimate should I trust?

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

When to use¶

Use this when a recording contains enough cycles for period estimation and the choice of estimator could change a downstream fold, phase, or model.

Example figure¶

Compare period estimates output generated by Circadian Workbench

This deterministic example is calculated by the compare_periods action and drawn by render_period_comparison_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.open("mouse01.awd").compare_periods(["lomb", "chi_square", "f"])

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("compare_periods", recording, config=None, methods=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.
`methods`	array of strings	no	`null`	-	Which period methods to compare, as a list of registry keys. Omit to use the config's period_methods. BioDare2's advice is to pair any method that cannot test significance (MESA, mFourFit, FFT-NLLS) with one that can (lomb), and discard the rest if the Lomb-Scargle periodogram rejects the record.

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

How it works¶

The same selected and binned trace is sent to only the requested estimators. Lomb-Scargle is the sole default; fast Fourier transform nonlinear least squares, maximum entropy spectral analysis, mFourFit, spectrum resampling, chi-square, F, JTK_CYCLE, and empirical JTK_CYCLE are opt-in comparisons with different output contracts.

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

Implementation: period_methods.py::estimate_periods.

Outputs and interpretation¶

One row per method reports the estimated period and, where that method can supply them, uncertainty, phase, amplitude, relative amplitude error, goodness of fit, significance, and a rhythmic verdict. Empty cells mean that the method does not produce that quantity.

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 short record cannot resolve nearby periods, a peak at the search boundary is weak evidence, and methods without a significance test must not be used to establish rhythmicity.

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¶

Period estimators were applied to the same selected, binned trace over the declared search interval; only the explicitly requested methods were run, with Lomb-Scargle used by default.