Metadata-Version: 2.4
Name: circadian-workbench
Version: 0.8.0
Summary: Local-first, reproducible circadian activity analysis
Author: Brancaccio Lab
Maintainer: Jay2owe
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/circadian-workbench/
Keywords: circadian rhythms,actogram,activity analysis,chronobiology
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: analysis-kit>=0.1.0
Requires-Dist: matplotlib<4,>=3.9
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn>=0.34
Requires-Dist: python-multipart>=0.0.20
Requires-Dist: numpy>=2.0
Requires-Dist: pandas>=2.2
Requires-Dist: scipy>=1.14
Requires-Dist: statsmodels>=0.14
Requires-Dist: PyWavelets>=1.6
Requires-Dist: plotly>=6.0
Requires-Dist: reportlab<6,>=5.0
Requires-Dist: svglib<3,>=2.2
Requires-Dist: reprofig[pdf]<1,>=0.5
Requires-Dist: SQLAlchemy>=2.0
Requires-Dist: alembic>=1.13
Requires-Dist: argon2-cffi>=23.1
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: httpx>=0.27; extra == "test"
Requires-Dist: openpyxl>=3.1; extra == "test"
Requires-Dist: playwright<2,>=1.49; extra == "test"
Provides-Extra: desktop
Requires-Dist: pywebview>=5.0; extra == "desktop"
Provides-Extra: release
Requires-Dist: build>=1.0; extra == "release"
Requires-Dist: pyinstaller<7,>=6.0; extra == "release"
Requires-Dist: pywebview>=5.0; extra == "release"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
Dynamic: license-file

# 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

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

## Ask one question

No Python is needed:

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

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

```python
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:

```python
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:

```python
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](https://jay2owe.github.io/CircadianWorkbench-docs/),
  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.
