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(action, data, answer, warnings, files, provenance, script, raw). data is the numerical payload; script is executable replay code; raw retains the complete backend envelope.

Constructors and dispatch

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 configuration overrides; omitted keys use live defaults.

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	—	Shared elapsed-time coordinates in 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 configuration overrides; omitted keys use live defaults.

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	—	Shared elapsed-time coordinates in hours.
traces	yes	—	Mapping from trace label to values on the shared hours grid.
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

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	—	Shared elapsed-time coordinates in 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 configuration overrides; omitted keys use live defaults.

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	Reference cycle length in hours.
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

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	—	Reviewed natural-language question or fixed alias; unknown questions are refused.
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 configuration overrides; omitted keys use live defaults.
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.summary(self, *, settings: 'Mapping[str, Any] | None' = None) -> 'Result'

Argument	Required	Default	Meaning
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

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

Argument	Required	Default	Meaning
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

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

Argument	Required	Default	Meaning
method	no	null	One registered period or detrending method, depending on the function.
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

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

Argument	Required	Default	Meaning
methods	no	null	Sequence of period-estimator names to run on the same trace.
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

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

Argument	Required	Default	Meaning
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

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

Argument	Required	Default	Meaning
period_hours	no	null	Reference cycle length in hours.
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

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) -> 'Result'

Argument	Required	Default	Meaning
method	no	"running mean"	One registered period or detrending method, depending on the function.
window_hours	no	24.0	Baseline window length in hours.
polynomial_degree	no	3	Global polynomial degree, or local degree for Savitzky–Golay detrending.
min_valid_fraction	no	0.5	Minimum finite share required inside a running, median, or kernel window.
bandwidth_hours	no	null	Gaussian-kernel standard deviation in hours; omitted uses one quarter of the baseline window.
low_cut_hours	no	45.0	Longest period retained by frequency detrending, in hours.
high_cut_hours	no	4.0	Shortest period retained by frequency detrending, in hours.
filter_order	no	2	Butterworth order used in each direction by frequency detrending.
lowess_fraction	no	null	Fraction of finite samples used by each LOWESS local fit; omitted derives it from the baseline window.
lowess_iterations	no	3	LOWESS robust residual-reweighting passes after the initial fit; zero disables reweighting.
asls_smoothness	no	1000000.0	Positive asymmetric least-squares curvature penalty; larger gives a smoother baseline.
asls_asymmetry	no	0.01	Weight in (0, 0.5) for points above the asymmetric baseline; smaller excludes positive peaks more strongly.
asls_iterations	no	10	Asymmetric least-squares reweighting passes, from 1 to 100.
smooth_window_hours	no	0.0	Centred smoothing width; zero disables smoothing.
exclude_hours	no	null	Leading duration removed before fitting.
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

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) -> 'Result'

Normalise the selected trace through the shared scientific core.

Argument	Required	Default	Meaning
method	no	"minmax"	One registered period or detrending method, depending on the function.
target_min	no	-1.0	Lower endpoint used only by min–max normalisation.
target_max	no	1.0	Upper endpoint used only by min–max normalisation; it must exceed target_min.
reference_value	no	null	Explicit non-zero baseline used by reference-based normalisations; omit it when supplying a reference window.
reference_start_hours	no	null	Inclusive start of the baseline window, paired with reference_end_hours.
reference_end_hours	no	null	Inclusive end of the baseline window, paired with reference_start_hours.
reference_statistic	no	"mean"	Reduce the reference window with its mean or median.
standard_deviation_ddof	no	0	Degrees of freedom removed from the z-score divisor: 0 for a population or 1 for a sample.
detrended	no	false	Declare that values are already baseline-subtracted so incompatible mean-based scaling is refused.
envelope_floor_fraction	no	0.1	For envelope normalisation, replace unstable tail values after the fitted amplitude falls below this fraction with missing values.
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

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

Argument	Required	Default	Meaning
output	no	null	Directory beneath which generated files are written.
options	no	null	Actogram display/export overrides.
individual_layers	no	false	Also save one actogram layer per measurement channel.
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

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

Argument	Required	Default	Meaning
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

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.

TraceCaller

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

Argument	Required	Default	Meaning
other	yes	—	Second aligned trace or trace caller used in pairwise coupling.
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

PopulationCaller

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

Argument	Required	Default	Meaning
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

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

Argument	Required	Default	Meaning
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

PhaseCaller

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

Argument	Required	Default	Meaning
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

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

Argument	Required	Default	Meaning
label	no	""	Value used for label.
settings	no	null	Partial configuration overrides; omitted keys use live defaults.

ChannelCaller

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

Argument	Required	Default	Meaning
first	no	null	First channel key; omitted with second to use the two available channels.
second	no	null	Second channel key; omitted with first to use the two available channels.
settings	no	null	Partial configuration overrides; omitted keys use live defaults.