Call Circadian Workbench¶

Choose the entrance that matches the job. Think of these as different doors into the same laboratory: every door reaches the same registered scientific methods and returns the same numbers.

I want to...	Use
analyse without writing code	the desktop
ask one familiar question	`circadian ask`
work in a notebook or another Python package	`circadian_workbench`
connect another local application	`/api/v1`
reach a specialised registered action	`cw.call(...)`

Complete cohort and study management is intentionally reserved for a separately agreed workflow and is not described here.

Use the Python interface reference for every constructor and bound method. Use the complete action reference for every registered action, exact signature, argument, default, unit, and meaning.

No code: use the desktop¶

Open Circadian Workbench, load a recording, then choose the scientific question. The desktop shows only the reviewed non-cohort questions and keeps the original recording read-only.

circadian-workbench-desktop

One question: use the plain-English command¶

The command accepts a recording followed by a reviewed question or short name. It prints a readable answer unless --json is requested.

circadian --list-questions
circadian ask mouse01.awd "What is the period?"
circadian ask mouse01.awd period --json
circadian ask demo period

Questions are fixed reviewed aliases, not free-text artificial-intelligence interpretation. A misspelling returns close choices instead of guessing which analysis to run. Destructive actions are not available through this command.

A few Python lines: open a recording¶

import circadian_workbench as cw

recording = cw.open("mouse01.awd")
period = recording.period(method="lomb")

print(period.answer)
period.show()

Settings use scientific names and units. Unspecified settings retain the tested defaults.

period = cw.open(
    "mouse01.awd",
    settings={"period_min_hours": 20, "period_max_hours": 28},
).period()

Numeric data: skip file construction¶

Elapsed hours and values can be passed directly. Circadian Workbench sorts the time grid, preserves missing values, and infers the sampling interval.

trace = cw.trace(hours, values, name="cell 17")
trace.period()
trace.compare_periods(["lomb", "chi_square"])
trace.detrend(method="running mean", window_hours=24)

Use the input that describes the experiment:

cw.population(hours, {"cell 1": cell_1, "cell 2": cell_2}).synchrony()
cw.phases([5.8, 6.1, 6.3], period_hours=24).summary(label="regions")
cw.phases({"control": control_phases, "treated": treated_phases}).compare()
cw.channels(hours, {"PER2": per2, "BMAL1": bmal1}).compare()

population means several independent oscillators. channels means several measurements from the same subject.

The result returned by every friendly call¶

Every call returns Result, so callers do not need a new output convention for each analysis.

Field	Meaning
`answer`	concise human-readable answer
`data`	complete analysis result
`table`	table when the result naturally has rows
`files`	files created beneath the chosen output folder
`warnings`	scientific qualifications and refusals
`provenance`	software version, source fingerprint and changed settings
`script`	executable equivalent action call

Use result.show() for a person and result.as_dict() for strict JavaScript Object Notation (JSON). The raw registered-action envelope remains available as result.raw.

A package maintainer: use only the public front door¶

Dependent packages should import the package root and adapt the Result once at their boundary.

import circadian_workbench as cw

def estimate_cell_period(hours, values):
    return cw.trace(hours, values, name="cell").period("lomb").as_dict()

Use from circadian_workbench import statistics for the shared Hedges' g, variance guard, degenerate-data guard and p-value corrections. Modules such as circadian_workbench.analysis and circadian_workbench.period_methods are engine internals, not compatibility contracts.

A specialised action: use `call`¶

cw.call is the escape hatch for registered actions that do not need a dedicated convenience method.

result = cw.call(
    "temperature_compensation",
    temperature_points=[
        [20, 24.2, "slice 1"],
        [25, 24.0, "slice 1"],
        [30, 23.9, "slice 1"],
    ],
)

Use cw.ask("period", source="mouse01.awd") when the caller starts from one of the reviewed questions. It never guesses an action.

Another local application: use version 1 web calls¶

The local service exposes the same registry contract:

GET  /api/v1/actions?action=estimate_period
POST /api/v1/validate
POST /api/v1/call

The request body for validation and execution is:

{
  "action": "estimate_period",
  "params": {
    "recording": {"path": "mouse01.awd"},
    "method": "lomb"
  },
  "root": "my-results"
}

Every response includes api_version: "1" and the registered-action envelope. An output root is a relative folder beneath the service's configured output area; absolute paths and parent-folder escapes are refused. Existing unversioned desktop routes remain compatible.

Errors a caller can act on¶

Friendly Python calls raise typed readable errors:

WorkbenchInputError: change the supplied values, settings or file.
UnknownQuestionError: choose one of the suggested reviewed questions.
UnknownActionError: inspect the registered actions and correct the name.
ActionConfirmationRequired: a destructive machine action needs explicit confirmation.
WorkbenchBackendError: the engine failed rather than declining invalid input.

The versioned web interface returns the corresponding error_type in its envelope. Only backend_error means the application itself is broken.

Compatibility promise¶

Circadian Workbench 0.7 introduces public application programming interface version 1. The cw.open, cw.trace, cw.population, cw.phases, cw.channels, cw.ask, cw.call, Result, input contracts, public errors and circadian_workbench.statistics addresses remain compatible throughout the 0.7 release line. Dependent packages should require circadian-workbench>=0.7,<0.8.

The action registry remains the machine source of truth. python scripts/update_circadian_references.py --check verifies that generated action documentation matches it.