Complete action reference¶

This page is generated from the live registry and documents all 70 callable actions. The signature and parameter tables are therefore the contract enforced by the runner, not a parallel handwritten list.

All successful actions return data, warnings, provenance, and an equivalent replay script. File-writing actions place files under root; source recordings remain read-only.

`inspect`¶

Grounding snapshot: actions, defaults, and optional recording metadata.

cw.call("inspect", recording, config=None)

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.
`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.

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.

Name	Type	Required	Default	Units	Meaning
`animals`	array of objects	yes	—	-	One entry per animal in the pulse experiment. Either a record to score -- {'recording': spec, 'stimulus': '2026-01-08 18:00', 'label': 'm01', 'config': {...}} -- or a point already scored elsewhere: {'circadian_time': 15.2, 'shift_hours': -1.4, 'label': 'm01'}. A record needs fit1_start/fit1_end before the pulse and fit2_start/fit2_end after it in its config, and 'stimulus' is the wall-clock time the pulse landed (or hours from the start of the record's first day). An animal whose pre-stimulus fit is too short is dropped with a warning rather than failing the cohort.
`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.

Name	Type	Required	Default	Units	Meaning
`shift_cohorts`	object	yes	—	-	Two labelled cohorts of pulsed animals, to test whether their phase response curves differ: {'WT': [animal, ...], 'KO': [...]}. Each animal takes the same shape phase_response_curve's `animals` does -- a record to score, or a point already scored. Exactly two cohorts: which contrast is meant is a decision about the experiment.
`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.
`unit`	string	no	`"subject"`	-	Unit of analysis: subject, slice, or cell.

Name	Type	Required	Default	Units	Meaning
`phases`	object	yes	—	hours	Phase values grouped by label: {'WT': [6.1, 5.8, ...], 'KO': [...]}. These are phases the caller already has -- onset hours from daily_measures, phase_hours from estimate_period, or their own scoring. This action does not compute phases, so the numbers may come from anywhere as long as they are clock hours on one shared period.
`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.
`period_hours`	float	no	`null`	hours	The cycle the phases live on. Omit to use the config's period_hours (24 h by default). A free-running cohort should pass its own tau, so that 'one cycle' means one of the animals' cycles rather than one solar day. `splitting` uses it for a second purpose that is the same idea: the period the resolution element P**2/T is worked out at, which sets how far apart two components must be before that record can show them to differ.

Name	Type	Required	Default	Units	Meaning
`phase_values`	array	yes	—	hours	Phase values for one group or tissue, expressed on one shared cycle.
`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.
`period_hours`	float	no	`null`	hours	The cycle the phases live on. Omit to use the config's period_hours (24 h by default). A free-running cohort should pass its own tau, so that 'one cycle' means one of the animals' cycles rather than one solar day. `splitting` uses it for a second purpose that is the same idea: the period the resolution element P**2/T is worked out at, which sets how far apart two components must be before that record can show them to differ.
`label`	string	no	`""`	-	Readable name returned with the single-group phase summary.

Name	Type	Required	Default	Units	Meaning
`traces`	object	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 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.

Name	Type	Required	Default	Units	Meaning
`sleep_result`	object	yes	—	-	An immobility_sleep result, whole. A record it refused to score is refused here for the same reason rather than re-derived.
`period_hours`	float	no	`null`	hours	The cycle the phases live on. Omit to use the config's period_hours (24 h by default). A free-running cohort should pass its own tau, so that 'one cycle' means one of the animals' cycles rather than one solar day. `splitting` uses it for a second purpose that is the same idea: the period the resolution element P**2/T is worked out at, which sets how far apart two components must be before that record can show them to differ.
`acrophase_hours`	number	no	`null`	hours	The circadian term's acrophase, in hours, from the package's own measurement. It is echoed back unchanged: a model that re-fitted it would compete with the measurement it came from.
`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.

Name	Type	Required	Default	Units	Meaning
`fit`	object	yes	—	-	A two_process_fit result, whole. A fit with no parameters -- a record the model refused -- is refused here rather than run with defaults.
`schedule`	object	yes	—	-	The proposed schedule: `days`, `period_hours`, and optionally `acrophase_hours` and `label`. The acrophase defaults to the one the record was fitted under, which assumes the animal holds the same phase angle; where it would not, entrainment_range predicts the new one and it should be passed here.
`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.

Name	Type	Required	Default	Units	Meaning
`curve`	object	yes	—	-	A phase_response_curve result, whole. Its `fit` is what is iterated; a curve with no fit -- too few animals -- is refused rather than predicted from.
`tau_hours`	number	yes	—	hours	The animal's own free-running period, in hours. The cohort curve does not carry it because a cohort has one per animal.
`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.

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 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.
`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.

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.
`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.
`detrend_method`	string	no	`"running_mean"`	-	Baseline removal method: none, linear, robust_linear/Huber, first_difference, running_mean, moving_median, lowess/loess, savitzky_golay, polynomial (including cubic/bicubic and poly6), kernel/baseline, amp_baseline, asymmetric_least_squares/asls, or frequency.
`window_hours`	float	no	`24.0`	hours	Baseline window.
`polynomial_degree`	integer	no	`3`	-	Polynomial baseline degree; poly6/degree6 force 6 and cubic/poly3/bicubic force 3.
`min_valid_fraction`	float	no	`0.5`	-	Minimum finite share of a local smoothing window.
`bandwidth_hours`	float	no	`null`	hours	Gaussian kernel standard deviation; omitted uses one quarter of window_hours.
`low_cut_hours`	float	no	`45.0`	hours	Longest period retained by frequency detrending.
`high_cut_hours`	float	no	`4.0`	hours	Shortest period retained by frequency detrending.
`filter_order`	integer	no	`2`	-	Butterworth frequency-filter order.
`lowess_fraction`	float	no	`null`	-	Fraction of finite samples in each LOWESS local fit; omitted derives it from window_hours.
`lowess_iterations`	integer	no	`3`	passes	LOWESS robust residual-reweighting passes after the initial local fit; 0 disables reweighting.
`asls_smoothness`	float	no	`1000000.0`	-	Positive second-difference penalty for asymmetric least squares; larger is smoother.
`asls_asymmetry`	float	no	`0.01`	-	Weight in (0, 0.5) for points above the asymmetric baseline; smaller excludes positive peaks more strongly.
`asls_iterations`	integer	no	`10`	passes	Asymmetric least-squares reweighting passes, from 1 to 100.
`smooth_window_hours`	float	no	`0.0`	hours	Centred smoothing window; zero disables smoothing.
`exclude_hours`	float	no	`null`	hours	Leading hours to discard before fitting.

Name	Type	Required	Default	Units	Meaning
`dose_points`	array	yes	—	-	The phase shifts of one dose series, as [[dose, shift_hours, label, circadian_time], ...] or as objects with "dose", "shift_hours", an optional "label" naming the animal and an optional "circadian_time". One entry per animal per dose. The dose is in whatever unit the stimulus was measured in and the package never guesses which; the shift follows the Aschoff sign convention the rest of the package uses, advance positive.
`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.
`dose_unit`	string	no	`null`	-	What the dose was measured in -- lux, uW/cm2, mg, photons. A label and nothing else: it is printed wherever a dose is printed and no arithmetic is done with it. Omit it and no unit appears anywhere, which is the honest output for a package that was not told what was measured.

Name	Type	Required	Default	Units	Meaning
`temperature_points`	array	yes	—	-	One entry per unit per temperature: [[20.0, 24.1, 'slice_1'], ...], or objects with temperature_c, period_hours and an optional label. Three slices at each of three temperatures is nine entries, and the labels are what lets the interval be clustered on the slice rather than on the measurement.
`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.

Name	Type	Required	Default	Units	Meaning
`points`	array	yes	—	hours and position units	One entry per region, each carrying a phase and a position: [{'label': 'left', 'phase_hours': 6.2, 'x': 120, 'y': 340}, ...]. A list of [label, phase_hours, x, y] arrays works too. The phases are ones the caller already measured -- acrophases from a cosinor, peak times, onsets -- and the positions are region centroids in whatever unit position_units names. Six regions is the floor; below it the plane is fitted but never tested.
`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.
`period_hours`	float	no	`null`	hours	The cycle the phases live on. Omit to use the config's period_hours (24 h by default). A free-running cohort should pass its own tau, so that 'one cycle' means one of the animals' cycles rather than one solar day. `splitting` uses it for a second purpose that is the same idea: the period the resolution element P**2/T is worked out at, which sets how far apart two components must be before that record can show them to differ.
`position_units`	string	no	`"um"`	-	What the x and y in points are measured in: 'um', 'px', 'mm'. It travels through to the reported speed, which comes back in these units per hour. Nothing is converted -- this is a label, so pass the unit the positions are actually in.

Name	Type	Required	Default	Units	Meaning
`series_a`	object	yes	—	recording units	The first trace: {'label': 'left lobe', 'values': [...]} on the shared hours grid. A [label, values] array works too. The label is reported back as the one that leads or lags, so make it the name you would use in a figure.
`series_b`	object	yes	—	recording units	The second trace, same shape as series_a and on the same hours grid. The reported lag is negative when series_a peaks first.
`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 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.

Name	Type	Required	Default	Units	Meaning
`question`	string	no	`"phase_difference"`	-	Which power question to answer: 'phase_difference' for two groups of phases compared on the circle, or 'mesor', 'amplitude' or 'rhythm_phase' for a cosinor parameter compared between two cohorts. 'observed' asks for post-hoc observed power and is refused with the reason, because it is a restatement of the p-value you already have.
`difference`	float	yes	—	hours or recording units	The smallest difference worth detecting, in the parameter's own units: hours for a phase, recording units for a mesor or an amplitude. Not the difference you observed -- the one that would change your mind.
`resultant_length`	float	no	`0.8`	-	How tightly the phases within a group cluster, from 0 (scattered) to just under 1 (identical). This is the R that phase_comparison reports, so a pilot's number goes straight in. Only used by the phase_difference question.
`n_per_group`	integer	no	`null`	units per group	Give it to ask 'what power do I have at this n'. Leave it out to ask 'how many do I need', which searches over n instead.
`target_power`	float	no	`0.8`	-	The power the search aims for when n_per_group is not given. 0.8 by convention; the returned n is the smallest whose interval clears it, not whose point estimate does.
`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.

Name	Type	Required	Default	Units	Meaning
`groups`	object	yes	—	-	Recordings grouped by label: {'WT': [spec, ...], 'KO': [...]}.
`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.
`unit`	string	no	`"subject"`	-	Unit of analysis: subject, slice, or cell.

Name	Type	Required	Default	Units	Meaning
`cohort`	object	yes	—	-	Metadata-driven cohort spec. Requires metadata_csv plus either a recording_column or recording_pattern; groups rows by diagnosis_column, defaulting to a diagnosis/condition/group-like column. Optional exclude_subjects removes participant IDs without editing source metadata. Optional mask_csv supplies one start/end analysis interval per subject; mask_subject_column, mask_start_column, and mask_end_column override its inferred columns.
`analyses`	array	yes	—	-	Action names to run on every recording of the study, e.g. ["cosinor", "sleep"]. Each is dispatched through this same registry, so a number in the report is the number that action returns on its own; run discover for the list of names.
`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.
`epoch_column`	string	no	`null`	-	Metadata column naming which epoch each recording belongs to, e.g. "epoch" holding baseline/treatment. Where it names exactly two epochs and subjects appear in both, the report runs the paired comparison; where it does not, the report says which of those it was. Omit it for a study with one epoch.

Complete action reference¶

inspect¶

describe_config¶

normalize_config¶

normalization_methods¶

normalize¶

load_recording¶

list_output¶

set_group_colours¶

summary¶

analyze¶

quality¶

rhythm¶

periodograms¶

daily_measures¶

onset_fits¶

profile¶

peak_aligned_profile¶

cosinor¶

period_methods¶

estimate_period¶

compare_periods¶

rhythmicity¶

nonparametric¶

bouts¶

fft¶

autocorrelation¶

wavelet¶

actogram¶

time_series¶

select_frame¶

methods_paragraph¶

analysis_script¶

write_analysis_script¶

render_actogram¶

render_figures¶

detrend¶

group_profile¶

phase_response_curve¶

compare_phase_response_curves¶

instantaneous_phase¶

phase_comparison¶

phase_summary¶

synchrony¶

period_dispersion¶

phase_angle¶

reentrainment¶

masking¶

sleep¶

food_anticipation¶

two_process_fit¶

two_process_predict¶

entrainment_range¶

predicted_reentrainment¶

paired_measures¶

longitudinal_measures¶

channel_comparison¶

splitting¶

ultradian¶

dose_response¶

temperature_compensation¶

phase_map¶

coupling¶

sample_size¶

compare_rhythms¶

group_comparison¶

render_group_figure¶

diagnosis_groups¶

study_report¶

render_diagnosis_profile¶

clear_output¶

`inspect`¶

`describe_config`¶

`normalize_config`¶

`normalization_methods`¶

`normalize`¶

`load_recording`¶

`list_output`¶

`set_group_colours`¶

`summary`¶

`analyze`¶

`quality`¶

`rhythm`¶

`periodograms`¶

`daily_measures`¶

`onset_fits`¶

`profile`¶

`peak_aligned_profile`¶

`cosinor`¶

`period_methods`¶

`estimate_period`¶

`compare_periods`¶

`rhythmicity`¶

`nonparametric`¶

`bouts`¶

`fft`¶

`autocorrelation`¶

`wavelet`¶

`actogram`¶

`time_series`¶

`select_frame`¶

`methods_paragraph`¶

`analysis_script`¶

`write_analysis_script`¶

`render_actogram`¶

`render_figures`¶

`detrend`¶

`group_profile`¶

`phase_response_curve`¶

`compare_phase_response_curves`¶

`instantaneous_phase`¶

`phase_comparison`¶

`phase_summary`¶

`synchrony`¶

`period_dispersion`¶

`phase_angle`¶

`reentrainment`¶

`masking`¶

`sleep`¶

`food_anticipation`¶

`two_process_fit`¶

`two_process_predict`¶

`entrainment_range`¶

`predicted_reentrainment`¶

`paired_measures`¶

`longitudinal_measures`¶

`channel_comparison`¶

`splitting`¶

`ultradian`¶

`dose_response`¶

`temperature_compensation`¶

`phase_map`¶

`coupling`¶

`sample_size`¶

`compare_rhythms`¶

`group_comparison`¶

`render_group_figure`¶

`diagnosis_groups`¶

`study_report`¶

`render_diagnosis_profile`¶

`clear_output`¶