Measure phase angle¶

Question¶

How far is the daily marker from the zeitgeber transition?

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

When to use¶

Use this for the timing of onset, offset, or acrophase relative to a declared light or feeding transition.

Example figure¶

Measure phase angle output generated by Circadian Workbench

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

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("phase_angle", recording, cohorts=None, config=None, marker=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.
`cohorts`	object	no	`null`	-	Recordings grouped by label, to test whether the groups hold different angles of entrainment: {'WT': [spec, ...], 'KO': [...]}. One angle per animal, so the unit of analysis is the animal. Omit it and only the focal recording is answered for.
`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.
`marker`	string	no	`null`	-	Which daily marker the angle of entrainment is measured from: onset, offset or acrophase. Defaults to the entrainment_marker config key, and is never guessed from the data.

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

How it works¶

Daily marker times are compared with the chosen zeitgeber transition on the circle. Entrainment additionally requires clustered phase and no material daily drift.

$$ \Psi=\operatorname{wrap}(\text{marker}-\text{zeitgeber transition}) $$

Implementation: entrainment.py::phase_angle.

Outputs and interpretation¶

The result reports daily angles, circular mean, resultant length, Rayleigh evidence, phase drift, included days, entrainment verdict, and optional cohort comparison.

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¶

Real calendar timestamps and the actual schedule are required. A stable phase angle describes alignment but does not prove that the zeitgeber caused it.

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¶

Daily phase angle was calculated as the wrapped difference between the selected activity marker and the declared zeitgeber transition; clustering and drift were assessed before calling the record entrained.