Test rhythmicity¶

Question¶

Is this series rhythmic under JTK or eJTK?

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

When to use¶

Use this for several sparsely sampled time courses measured on one shared schedule, especially transcript, protein, or imaging summaries.

Example figure¶

Test rhythmicity output generated by Circadian Workbench

This deterministic example is calculated by the rhythmicity action and drawn by render_rhythmicity_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("rhythmicity", recordings=[{"path": "gene_panel.csv"}], rhythmicity_method="ejtk")

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("rhythmicity", recordings, config=None, rhythmicity_method=None)

Arguments and parameters¶

Name	Type	Required	Default	Units	Meaning
`recordings`	array of recording specs	yes	—	-	Recordings to pool into one group trace.
`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.
`rhythmicity_method`	string	no	`null`	-	jtk for classic JTK_CYCLE or ejtk for the permutation null (default). eJTK is the one to use; classic JTK is kept for comparability with published work and is known to be anti-conservative. Both are for sparsely sampled, omics-like data -- a densely sampled record is binned down to jtk_max_points before either sees it.

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

How it works¶

JTK_CYCLE ranks each series against period, phase, and waveform templates. Empirical JTK_CYCLE uses a permutation null; Benjamini-Hochberg correction then controls false discovery across the submitted series.

$$ q_i=\operatorname{BH}(p_i) $$

Implementation: rhythm_detection.py::rhythmicity.

Outputs and interpretation¶

Each series returns its best period and phase, Kendall tau-b effect size, raw p value, corrected q value, rhythmic verdict, and the tested template grid.

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¶

All records must share a time grid. Dense recordings are reduced to at most jtk_max_points; classic JTK_CYCLE is retained for comparison with published work but is anti-conservative relative to empirical JTK_CYCLE.

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¶

Rhythmicity was tested against the declared period and phase templates using empirical JTK_CYCLE, and p values were corrected across series by the Benjamini-Hochberg procedure.