Circadian Workbench

Circadian Workbench is a local-first desktop application and Python package for circadian activity analysis. It imports supported ClockLab and tabular recordings, provides core rhythm views plus a reviewed non-cohort question workbench, and preserves settings and provenance in project, result, figure, and recovery outputs.

Install

pip install "circadian-workbench[desktop]"
circadian-workbench-desktop

Python 3.10 or newer is required. The application runs only on the local machine; it has no account, login, hosted-service, or data-upload requirement.

Offline guide for people and AI callers

The installed package includes searchable workflows, input requirements, method choices, output explanations and troubleshooting. Reading it loads no recordings and does not start the application:

from circadian_workbench import context

print(context.read())
print(context.read("quickstart"))
print(context.search("missing values"))
print(context.read("troubleshooting", format="json"))

Terminal access uses python -m circadian_workbench.context quickstart or python -m circadian_workbench.context --search "missing values" and returns JSON.

Ask one question

No Python is needed:

circadian ask mouse01.awd period
circadian --list-questions

The same scientific engine is available through a small Python front door:

import circadian_workbench as workbench

recording = workbench.open("mouse.awd")
result = recording.detrend(window_hours=24).compare_periods()
result.plot().save("periods.svg")

The figure and its data, statistics, evidence and replay script are saved under .circadian-agent. The original recording is unchanged. No server is needed for Python calls. For a text answer use result.show(); named measurements, tables and series expose results with units.

Numeric traces do not need to be turned into files or pandas DataFrames. This complete example generates a seven-day synthetic signal:

import math
import circadian_workbench as workbench

hours = list(range(168))
values = [20 + 4 * math.cos(2 * math.pi * hour / 24) for hour in hours]
result = workbench.trace(hours, values, name="Synthetic cell",
                        settings={"period_min_hours": 22, "period_max_hours": 26}).compare_periods()
result.show()

For arrays already extracted by another package, use the same short workflow:

import circadian_workbench as workbench

recording = workbench.trace(
    hours,
    values,
    settings={"period_min_hours": 20, "period_max_hours": 28},
)
result = recording.compare_periods()
result.plot(theme="classic").save("periods.svg")

Workbench owns the implemented circadian method catalogue and shared argument definitions. Motion and Auto-Organotypic consume the installed public interface; their new trace entrance is the Workbench function itself. Common figures use one shared builder for scientific data, labels, units, geometry and style. Existing consumer measurement wrappers keep their explicit legacy settings.

Argument meanings, units, choices and installed defaults are shared by Python, the browser and machine calls. Explicit method arguments override per-call settings, which override bound settings, which override fixed defaults. Display options belong to result.plot(...); output folders belong to .save(..., root=...). Earlier runs never choose a new method or theme. Reproduction requires the same data, settings, seeds and recorded software environment, not arbitrary upgrades. result.run_record captures the complete call and software/code identity. result.script verifies the recorded inputs and environment and then checks the recomputed result; the saved figure producer also verifies the declared figure. A mismatch is reported without changing software or choosing defaults from previous runs. This is not a promise of identical raster pixels across different operating systems and font engines.

See the installed Callers and automation guide for populations, phases, measurement channels, result fields, errors, provenance and the version 1 local web application programming interface.

Main capabilities

• Actograms, profiles, onset/offset fits, fixed cosinor, non-parametric measures, spectral estimators, bouts, and quality checks.
• Period comparison, rhythmicity, instantaneous phase, entrainment and perturbation, immobility sleep, ultradian rhythm, temperature compensation, within-recording synchrony/spatial/coupling analyses, prospective power, and model prediction.
• Editable SVG and vector PDF publication bundles with exact plotted data and embedded ReproFig provenance.
• Verified application snapshots and disposable restore rehearsal.
• Public task-oriented documentation, also installed with the application, and machine-readable scientific action contracts.

Scientific status

This is beta research software. The distribution distinguishes implemented and internally tested methods from independent validation. Retain original recordings, inspect warnings, and verify outputs for the intended use.

Complete multi-recording experimental management is reserved for a future separately agreed workflow.

Released under the MIT License.