Measure population synchrony¶

Question¶

Did the population damp because cells desynchronised?

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

When to use¶

Use this for aligned single-cell or region traces when loss of ensemble amplitude may reflect either cellular damping or desynchronisation.

Example figure¶

Measure population synchrony output generated by Circadian Workbench

This deterministic example is calculated by the synchrony action and drawn by render_synchrony_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.population(hours, cell_traces).synchrony()

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("synchrony", traces, hours, config=None)

Arguments and parameters¶

Name	Type	Required	Default	Units	Meaning
`traces`	object or array	yes	—	recording units	Single-cell traces on one shared time grid: {'roi_1': [values], ...}. Per-ROI output from a slice recording.
`hours`	array	yes	—	hours	The shared time grid the traces are sampled on, in hours from the start of the recording.
`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¶

A band-limited Hilbert phase is calculated per trace and combined into the population order parameter. Cell amplitude, ensemble amplitude, and coherence trajectories are compared over time.

$$ R(t)=\left|\frac{1}{N}\sum_i e^{i\theta_i(t)}\right| $$

Implementation: synchrony.py::synchrony.

Outputs and interpretation¶

The result contains coherence through time, contributing-cell count, cell and ensemble amplitudes, damping rates, decomposition, significance, diagnostics, and a biological interpretation.

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¶

At least the configured number of cells and contributors per timepoint are required. Low-amplitude Hilbert phase and shared technical artifacts can distort apparent synchrony.

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_population-synchrony.csv, a standalone plot_population-synchrony.py and source hashes; these companion files are not installed application files.

Methods text¶

Per-trace analytic phases were combined into the circular order parameter, and ensemble damping was compared with single-trace amplitude damping to separate desynchronisation from cellular damping.