Measure acute masking¶

Question¶

Did a light pulse change activity while it was present?

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

When to use¶

Use this for the immediate activity response during a light pulse, distinct from a later clock phase shift.

Example figure¶

Measure acute masking output generated by Circadian Workbench

This deterministic example is calculated by the masking action and drawn by render_masking_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("masking", recording={"path": "mouse01.awd"}, pulse_start="2026-01-12T22:00", pulse_hours=1)

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("masking", recording, pulse_start, pulse_hours, config=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.
`pulse_start`	string	yes	—	-	When the light pulse began, as an ISO date-time (2026-05-11T22:00). The same clock window on the days before it becomes the control.
`pulse_hours`	float	yes	—	hours	How long the pulse lasted. Must be greater than zero.
`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.

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

How it works¶

Activity during the declared pulse duration is compared with the same clock-time window on preceding control days using a predictive t statistic.

$$ t=\frac{x_{\mathrm{pulse}}-\bar x_c}{s_c\sqrt{1+1/n_c}} $$

Implementation: entrainment.py::masking.

Outputs and interpretation¶

The result reports pulse and control activity, change and percentage change, predictive interval, p value, coverage, direction, significance, and matched control dates.

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 half of the pulse window and the configured number of control days must be covered. Masking is an acute response and is not evidence of phase resetting.

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¶

Activity during the declared pulse start and duration was compared with the same clock-time interval on preceding control days using a predictive t statistic.