Track repeated visits¶
Question¶
Did a measure change across three or more ordered visits?
See every package-generated example · Read the complete analysis pipeline
When to use¶
Use this for three or more ordered visits from the same subjects.
Example figure¶
This deterministic example is calculated by the longitudinal_measures action and drawn by render_longitudinal_measures_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("longitudinal_measures", epochs=visits, order=["baseline", "week1", "week2"])
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("longitudinal_measures", epochs, config=None, circular_measures=None, order=None)
Arguments and parameters¶
| Name | Type | Required | Default | Units | Meaning |
|---|---|---|---|---|---|
epochs |
object | yes | — | - | The epochs of one study, each a list of subject entries: {"baseline": [{"subject_id": "m01", "measures": {"period_hours": 23.8}}, ...], "treatment": [...]}. Pairing is by subject_id, so a subject missing from any epoch is dropped and named. paired_measures takes exactly two and longitudinal_measures three or more; each refuses the other's shape by name. |
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. |
circular_measures |
array | no | null |
- | Which measure names are clock times rather than plain numbers, e.g. ["acrophase_hours"]. Those are differenced round the circle -- 23.5 h to 00.5 h is +1 h, not -23 h -- and tested with a Rayleigh test. Nothing is inferred from a name. |
order |
array | no | null |
- | The epoch labels in study order, e.g. ["baseline", "6_months", "12_months"]. The linear trend is fitted along this axis, so it decides what rising and falling mean. Without it the order the epochs arrived in is used and said to have been assumed. |
Every nested config key, default, allowed value, and purpose is listed in the complete configuration reference.
How it works¶
Repeated observations are matched by subject and the visit trajectory is tested.
$$ y_{ij}=\mu+\mathrm{visit}j+\mathrm{subject}_i+\epsilon $$
Implementation: repeated.py::longitudinal_measures.
Outputs and interpretation¶
The result includes visit means, trajectories, omnibus tests and dropped subjects.
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¶
Visit order and subject identity must be correct; missing visits reduce the matched cohort.
Example¶
The figure above is a real package result from a seeded, redistributable synthetic dataset. The flat gallery bundle retains figure_data_longitudinal-measures.csv, a standalone plot_longitudinal-measures.py, source hashes, an editable SVG, and a rendered preview.
Methods text¶
Ordered repeated visits were compared within subjects.