Python interface reference

The friendly interface binds data once and exposes question-shaped methods. Every method ultimately calls the same registered scientific action documented in the complete action reference.

Return object

Every calculation returns Result. data is the complete numerical payload; measurements, tables, and series expose explicitly named views with units. raw retains the complete backend envelope. Processed results retain this contract and support the same recording methods on their transformed samples. available_plots lists supported views; plot() returns a detached figure and save() returns its path and companion paths. See figure options for figure replay.

run_record returns a detached completed-call record: effective arguments, full settings, exact consumed source hashes, complete recording identities, ordered processing, actual random-generator seeds and settings, estimator diagnostics, and software/platform identity. Editing a returned data or provenance dictionary cannot rewrite this record or a later plot of that completed result. There is no run database or historical-default selector.

script supplies the effective inputs and checks sources, package versions and Python-source identities before replay, then compares exact scientific JSON results and input identities. Nested study analyses are checked too. Missing/changed inputs or software cause a refusal; nothing is installed or switched automatically. Explicit demo seed=None still requests fresh randomness: the completed run retains its actual seed, but repeating that original request is not deterministic.

Elapsed and estimated runtime in sample-size calculations, and declared output locations in report/export results, are not scientific equality claims. The existing wall-clock cost guard still applies. File-only export actions retain a workflow record, not a claim of identical file bytes; destructive actions require a new explicit call. Configuration-only scripts retain manual onset corrections and check software, but cannot verify an input hash they were never given. Verified equality is limited to the recorded software/platform conditions, not arbitrary machines or upgrades.

Constructors and dispatch

Discover supported methods

import circadian_workbench as cw

methods = cw.call('period_methods').data['methods']
lomb = next(method for method in methods if method['key'] == 'lomb')
arguments = lomb['arguments']  # live defaults, units, choices and constraints
contract = cw.describe('estimate_period')  # inputs, result meanings and figure views
coverage = cw.discover()  # independently checks package modules and scientific bindings
assert coverage['ok']

Discovery is read-only and needs no server. Select a subset of these definitions; do not maintain another circadian registry. A declared figure view requires its completed result payload; discovery does not execute an analysis.

cw.open(source: 'Any', *, settings: 'Mapping[str, Any] | None' = None) -> 'RecordingCaller'

Bind friendly calls to a file path, recording spec or Recording.

Argument	Required	Default	Meaning
source	yes	—	File path, recording specification, or in-memory recording to bind.
settings	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. Units: -.

cw.trace(hours: 'Sequence[float]', values: 'Sequence[float]', *, name: 'str' = 'trace', value_label: 'str' = 'Activity', value_unit: 'str' = '', settings: 'Mapping[str, Any] | None' = None) -> 'TraceCaller'

Bind friendly calls to one elapsed-time numeric trace.

Argument	Required	Default	Meaning
hours	yes	—	The shared time grid the traces are sampled on, in hours from the start of the recording. Units: hours.
values	yes	—	Numeric observations; a mapping supplies one array per channel.
name	no	"trace"	Human-readable recording or trace label retained in results.
value_label	no	"Activity"	Axis label describing the measured quantity.
value_unit	no	""	Unit printed beside the measured quantity.
settings	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. Units: -.

cw.population(hours: 'Sequence[float]', traces: 'Mapping[str, Sequence[float]]', *, settings: 'Mapping[str, Any] | None' = None) -> 'PopulationCaller'

Bind population analyses to labelled traces on a shared time grid.

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

cw.channels(hours: 'Sequence[float]', values: 'Mapping[str, Sequence[float]]', *, name: 'str' = 'recording', settings: 'Mapping[str, Any] | None' = None) -> 'ChannelCaller'

Bind analyses to several measurements from one subject.

Argument	Required	Default	Meaning
hours	yes	—	The shared time grid the traces are sampled on, in hours from the start of the recording. Units: hours.
values	yes	—	Numeric observations; a mapping supplies one array per channel.
name	no	"recording"	Human-readable recording or trace label retained in results.
settings	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. Units: -.

cw.phases(values: 'Any', *, period_hours: 'float' = 24.0, settings: 'Mapping[str, Any] | None' = None) -> 'PhaseCaller'

Bind circular phase comparison to labelled phase values.

Argument	Required	Default	Meaning
values	yes	—	Numeric observations; a mapping supplies one array per channel.
period_hours	no	24.0	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. Units: hours.
settings	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. Units: -.

cw.normalization_methods() -> 'Result'

Return every value-normalisation method, formula, alias and requirement.

This function has no parameters.

cw.ask(question: 'str', *, source: 'Any' = None, root: 'str | Path | None' = None, settings: 'Mapping[str, Any] | None' = None, **params: 'Any') -> 'Result'

Run one reviewed question or fixed alias; never guesses an action.

Argument	Required	Default	Meaning
question	yes	—	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. Units: -.
source	no	null	File path, recording specification, or in-memory recording to bind.
root	no	null	Output directory for actions that write files.
settings	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. Units: -.
params	no	extra named values	Named parameters accepted by the selected registered action.

cw.call(action: 'str', /, *, root: 'str | Path | None' = None, **params: 'Any') -> 'Result'

Run any registered action with friendly errors and a uniform result.

Argument	Required	Default	Meaning
action	yes	—	Registered action name; see the complete action reference.
root	no	null	Output directory for actions that write files.
params	no	extra named values	Named parameters accepted by the selected registered action.

Bound analysis methods

RecordingCaller

RecordingCaller.actogram(self, *, root: 'str | Path | None' = None, output: 'str | Path | None' = None, options: 'Mapping[str, Any] | None' = None, individual_layers: 'bool' = False, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Render actogram SVG under root/figures.

Registered action: render_actogram.

Argument	Required	Default	Meaning
root	no	null	Chosen output root; files stay beneath it and source recordings remain read-only. Units: path.
output	no	null	Chosen output root; files stay beneath it and source recordings remain read-only. Compatibility alias for root; supply only one. Units: path.
options	no	null	Actogram export options. Units: -.
individual_layers	no	false	Also write one SVG per measurement channel. Units: -.
settings	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. Units: -.

RecordingCaller.autocorrelation(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Autocorrelation function and best period.

Registered action: autocorrelation.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.bouts(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Activity bout detection and summary statistics.

Registered action: bouts.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.compare_channels(self, first: 'str', second: 'str', *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

The lag between two measurement channels of one subject, with each channel's own period so the lag is not misread as a phase angle.

Registered action: channel_comparison.

Argument	Required	Default	Meaning
first	yes	—	Exactly two measurement channel keys from this recording, e.g. ["activity", "body_temperature"]. Use inspect to list what a recording carries. Units: -.
second	yes	—	Exactly two measurement channel keys from this recording, e.g. ["activity", "body_temperature"]. Use inspect to list what a recording carries. Units: -.
settings	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. Units: -.

RecordingCaller.compare_periods(self, methods: 'Sequence[str] | None' = None, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Run several period methods over one record and return one comparison table.

Registered action: compare_periods.

Argument	Required	Default	Meaning
methods	no	null	Which period methods to compare, as a list of registry keys. Omit to use the config's period_methods. BioDare2's advice is to pair any method that cannot test significance (MESA, mFourFit, FFT-NLLS) with one that can (lomb), and discard the rest if the Lomb-Scargle periodogram rejects the record. Units: -.
settings	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. Units: -.

RecordingCaller.cosinor(self, period_hours: 'float | None' = None, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Cosinor fit at the configured period.

Registered action: cosinor.

Argument	Required	Default	Meaning
period_hours	no	null	Reference cycle used for folding, cosinor, and circular quantities. Units: hours.
settings	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. Units: -.

RecordingCaller.daily_timing(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Daily onset, offset, alpha and phase markers.

Registered action: daily_measures.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.detrend(self, method: 'str' = 'running_mean', *, window_hours: 'float' = 24.0, polynomial_degree: 'int' = 3, min_valid_fraction: 'float' = 0.5, bandwidth_hours: 'float | None' = None, low_cut_hours: 'float' = 45.0, high_cut_hours: 'float' = 4.0, filter_order: 'int' = 2, lowess_fraction: 'float | None' = None, lowess_iterations: 'int' = 3, asls_smoothness: 'float' = 1000000.0, asls_asymmetry: 'float' = 0.01, asls_iterations: 'int' = 10, smooth_window_hours: 'float' = 0.0, exclude_hours: 'float | None' = None, settings: 'Mapping[str, Any] | None' = None) -> 'ProcessedResult'

Baseline subtract, smooth, optionally exclude transients, and fit damping.

Registered action: detrend.

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

RecordingCaller.food_anticipation(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Whether the animal became active before a declared mealtime, and whether that anticipation survived a fast.

Registered action: food_anticipation.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.instantaneous_phase(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Hilbert phase, instantaneous period and amplitude envelope over time.

Registered action: instantaneous_phase.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.is_rhythmic(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Classify rhythmicity using the configured periodogram, not JTK/eJTK.

Registered action: rhythm.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.masking(self, pulse_start: 'str', pulse_hours: 'float', *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Whether a light pulse changed activity while it was on, which is not the same finding as a phase shift.

Registered action: masking.

Argument	Required	Default	Meaning
pulse_start	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. Units: -.
pulse_hours	yes	—	How long the pulse lasted. Must be greater than zero. Units: hours.
settings	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. Units: -.

RecordingCaller.methods(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Publication-ready Methods paragraph for the actual analysis.

Registered action: methods_paragraph.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.nonparametric(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

IS, IV, RA, L5 and M10 metrics.

Registered action: nonparametric.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.normalize(self, method: 'str' = 'minmax', *, target_min: 'float' = -1.0, target_max: 'float' = 1.0, reference_value: 'float | None' = None, reference_start_hours: 'float | None' = None, reference_end_hours: 'float | None' = None, reference_statistic: 'str' = 'mean', standard_deviation_ddof: 'int' = 0, detrended: 'bool' = False, envelope_floor_fraction: 'float' = 0.1, settings: 'Mapping[str, Any] | None' = None) -> 'ProcessedResult'

Normalise the selected trace through the shared scientific core.

Registered action: normalize.

Argument	Required	Default	Meaning
method	no	"minmax"	Transformation to apply. Canonical choices are none, mean_center, median_center, zscore, robust_zscore, robust_scale, own_mean, own_daily_total, minmax, max_abs, reference_delta, fold_change, delta_over_reference, log2_fold_change, percent_of_reference, percent_change, envelope and pre_treatment_cycle. Aliases include range for minmax, extreme or to_extreme for max_abs, z for zscore, dff for delta_over_reference, and fold for fold_change. Units: -.
target_min	no	-1.0	Lower output bound for minmax range scaling; ignored by other methods. Units: normalised units.
target_max	no	1.0	Upper output bound for minmax range scaling; must exceed target_min. Units: normalised units.
reference_value	no	null	Explicit baseline for reference_delta, fold_change, delta_over_reference, log2_fold_change, percent_of_reference, percent_change or pre_treatment_cycle. Use this or a reference time window, never both. Units: recording units.
reference_start_hours	no	null	Inclusive start of the baseline window, in hours from the selected recording start. Must be paired with reference_end_hours. Units: hours.
reference_end_hours	no	null	Inclusive end of the baseline window used to calculate the reference. Must exceed and be paired with reference_start_hours. Units: hours.
reference_statistic	no	"mean"	How a reference time window is reduced: mean or median. Units: -.
standard_deviation_ddof	no	0	Degrees of freedom removed from the z-score standard-deviation divisor: 0 for a population, 1 for a sample. Units: -.
detrended	no	false	Whether inputs are already baseline-subtracted. Units: -.
envelope_floor_fraction	no	0.1	For envelope normalisation, return missing values after the fitted oscillation envelope falls below this fraction of its starting amplitude. Must lie from 0 inclusive to 1 exclusive. Units: fraction.
settings	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. Units: -.

RecordingCaller.onset_fits(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Regression fits through daily onsets and offsets.

Registered action: onset_fits.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.peak_aligned_profile(self, peak_period: 'str', *, anchor_amplitude: 'float | None' = None, peak_options: 'Mapping[str, Any] | None' = None, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Align an average-cycle profile to a participant morning or evening peak.

Registered action: peak_aligned_profile.

Argument	Required	Default	Meaning
peak_period	yes	—	Peak to detect and align: morning (07:00-14:00) or evening (17:00-22:00). Units: -.
anchor_amplitude	no	null	Optional established participant peak amplitude. When supplied, the unsmoothed aligned profile is scaled so time zero equals this value. Units: activity amplitude.
peak_options	no	null	Peak-alignment options: alignment_window_hours, smoothing_window_bins, polynomial_order, minimum_peak_distance_hours, active_window_hours, and allow_window_max_fallback. Units: -.
settings	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. Units: -.

RecordingCaller.period(self, method: 'str | None' = None, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Period, phase and amplitude by one named method.

Registered action: estimate_period.

Argument	Required	Default	Meaning
method	no	null	Which period method to run: lomb, chi_square, f, fft_nlls, mesa, mfourfit, spectrum_resampling, jtk or ejtk. Omit to use the config's period_method (default lomb). Run period_methods for what each one can and cannot report -- MESA and mFourFit give no error bar and no significance measure, and FFT-NLLS is the only one that yields RAE. Units: -.
settings	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. Units: -.

RecordingCaller.periodograms(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Lomb-Scargle, chi-square and F periodograms.

Registered action: periodograms.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.phase_angle(self, marker: 'str | None' = None, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

How far the animal's daily marker sits from the light transition, and whether that angle held.

Registered action: phase_angle.

Argument	Required	Default	Meaning
marker	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. Units: -.
settings	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. Units: -.

RecordingCaller.profile(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Folded average-day activity profile.

Registered action: profile.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.quality(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Data-quality metrics for the selected window.

Registered action: quality.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.reentrainment(self, shift_day: 'str | None' = None, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

How many cycles the animal took to catch up with a shifted schedule, and at what rate.

Registered action: reentrainment.

Argument	Required	Default	Meaning
shift_day	no	null	The date the light schedule moved, as YYYY-MM-DD. Omit it and the date is read out of the schedule itself; supply it when the schedule in the config does not carry the move. The shift date belongs to neither side: the first full day on the new schedule is day 1. Units: -.
settings	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. Units: -.

RecordingCaller.rhythmicity(self, method: 'str | None' = None, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Test this one series with rank/template-based JTK or empirical JTK.

Registered action: rhythmicity.

Argument	Required	Default	Meaning
method	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. Units: -.
settings	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. Units: -.

RecordingCaller.run(self, action: 'str', /, *, root: 'str | Path | None' = None, **params: 'Any') -> 'Result'

Argument	Required	Default	Meaning
action	yes	—	Registered action name; see the complete action reference.
root	no	null	Output directory for actions that write files.
params	no	extra named values	Named parameters accepted by the selected registered action.

RecordingCaller.sleep(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Sleep scored as sustained immobility, split by light and dark, with bouts and fragmentation.

Registered action: sleep.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.spectrum(self, kind: 'str | None' = None, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

FFT amplitude or power spectrum.

Registered action: fft.

Argument	Required	Default	Meaning
kind	no	null	Display Fourier amplitude or squared-amplitude power; does not select a period estimator. Units: named choice or label.
settings	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. Units: -.

RecordingCaller.splitting(self, period_hours: 'float | None' = None, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Two circadian components running at once, or the reason the record carries one.

Registered action: splitting.

Argument	Required	Default	Meaning
period_hours	no	null	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. Units: hours.
settings	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. Units: -.

RecordingCaller.summary(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Headline read on one recording: period, rhythm, quality, metrics.

Registered action: summary.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.time_series(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Binned time series for every measurement channel.

Registered action: time_series.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.ultradian(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

The strongest component faster than a day, and how large it is beside the daily one.

Registered action: ultradian.

Argument	Required	Default	Meaning
settings	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. Units: -.

RecordingCaller.wavelet(self, cycles: 'float | None' = None, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Continuous wavelet transform power and ridge.

Registered action: wavelet.

Argument	Required	Default	Meaning
cycles	no	null	Cycles in the Morlet wavelet; trades temporal localisation against period resolution. Units: cycles.
settings	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. Units: -.

TraceCaller

TraceCaller.coupling(self, other: "TraceData | 'TraceCaller' | Sequence[float]", *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

How far one named trace leads another, whether that lag is a number, and whether it held.

Registered action: coupling.

Argument	Required	Default	Meaning
other	yes	—	The second trace, same shape as series_a and on the same hours grid. The reported lag is negative when series_a peaks first. Units: recording units.
settings	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. Units: -.

PopulationCaller

PopulationCaller.period_dispersion(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Whether a population lost coherence because its cells' periods diverged or because their phases were displaced.

Registered action: period_dispersion.

Argument	Required	Default	Meaning
settings	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. Units: -.

PopulationCaller.synchrony(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Kuramoto coherence over single cells, and whether damping is desynchrony or amplitude loss.

Registered action: synchrony.

Argument	Required	Default	Meaning
settings	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. Units: -.

PhaseCaller

PhaseCaller.compare(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Circular summary and between-group test for phase.

Registered action: phase_comparison.

Argument	Required	Default	Meaning
settings	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. Units: -.

PhaseCaller.summary(self, *, label: 'str' = '', settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Circular mean, concentration and Rayleigh test for one set of phases.

Registered action: phase_summary.

Argument	Required	Default	Meaning
label	no	""	Readable name returned with the single-group phase summary. Units: -.
settings	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. Units: -.

ChannelCaller

ChannelCaller.compare(self, first: 'str | None' = None, second: 'str | None' = None, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

The lag between two measurement channels of one subject, with each channel's own period so the lag is not misread as a phase angle.

Registered action: channel_comparison.

Argument	Required	Default	Meaning
first	no	null	Exactly two measurement channel keys from this recording, e.g. ["activity", "body_temperature"]. Use inspect to list what a recording carries. Units: -.
second	no	null	Exactly two measurement channel keys from this recording, e.g. ["activity", "body_temperature"]. Use inspect to list what a recording carries. Units: -.
settings	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. Units: -.

Result and figure methods

Result.plot(self, view: 'str | None' = None, *, theme: 'str | None' = None, width: 'float | None' = None, height: 'float | None' = None, preset: 'str | None' = None, text_scale: 'float | None' = None, font_family: 'str | None' = None, show_grid: 'bool | None' = None, legend: 'bool | str | Mapping | None' = None, line_width: 'float | None' = None, marker_size: 'float | None' = None, group_colours: 'Mapping | None' = None, colours: 'Mapping | None' = None, options: 'Mapping | None' = None) -> "'Figure'"

Plot completed values without rerunning analysis; choose from available_plots.

Argument	Required	Default	Meaning
view	no	null	One of result.available_plots; omitted selects the first declared view.
theme	no	null	Installed house theme; historical aliases are supported. Units: dimensionless / display choice.
width	no	null	Output viewport width; the declared geometry keeps its aspect ratio. Units: pixels.
height	no	null	Output viewport height; the declared geometry keeps its aspect ratio. Units: pixels.
preset	no	null	Existing publication page preset, using physical millimetres. Units: dimensionless / display choice.
text_scale	no	null	Scale the shared theme's text sizes. Units: dimensionless / display choice.
font_family	no	null	Explicit font family; the house font is used otherwise. Units: dimensionless / display choice.
show_grid	no	null	Show decorative axis gridlines; timing and significance marks are retained. Units: dimensionless / display choice.
legend	no	null	Line-figure legend: true, false, top, right, or explicit position/orientation. Units: dimensionless / display choice.
line_width	no	null	Width of data lines, independent of axis widths. Units: pixels.
marker_size	no	null	Diameter of data-point markers. Units: pixels.
group_colours	no	null	Explicit group-name colours, stable across ordering and subsets. Units: dimensionless / display choice.
colours	no	null	Per-series colours, keyed by declared series key; override named-group colours. Units: dimensionless / display choice.
options	no	null	Actogram export options. Units: -.

Result.show(self) -> "'Result'"

Print the concise answer and any warnings; return self for chaining.

This function has no parameters.

Result.as_dict(self) -> 'dict[str, Any]'

A strict JSON-clean representation for another application.

This function has no parameters.

Figure.save(self, filename: 'str | Path', *, root: 'str | Path | None' = None, output: 'str | Path | None' = None) -> 'SavedFigure'

Save SVG/PDF plus data, evidence and a scientific replay script.

Argument	Required	Default	Meaning
filename	yes	—	Relative SVG or PDF filename beneath the selected output root; source and companion-file collisions are protected.
root	no	null	Output directory for actions that write files.
output	no	null	Compatibility spelling of root; supply only one of the two.