Analyse a first recording

Question

What does this recording support before I choose a specialised analysis?

What you need

A ClockLab AWD file, timestamped CSV/TSV, BioDare2 elapsed-time table, wide multi-series table, or supported Excel equivalent.

Click path

1. Choose Load activity data and select one file.
2. Check the source name, samples, interval, missing percentage, and timestamp gaps.
3. Set the analysis interval and exclusions.
4. Inspect the actogram, activity profile, daily timing, and periodograms.
5. Open Workbench for a question-specific analysis.

What success looks like

The top status reads Analysis current, figures agree with the selected interval, and warnings are attached to the result they qualify.

What it does not prove

A clean import does not establish rhythmicity, entrainment, or biological validity.

What gets saved

Use Save project for replay instructions or Export reproducibility bundle for figures and numerical tables.

Related explanation

Analysis explained · Importer troubleshooting

File to figure in Python

Run in the directory containing mouse.awd. No server or account is needed.

import circadian_workbench as workbench

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

The output is .circadian-agent/periods.svg, with companion data/statistics CSVs, JSON evidence and a standalone replay producer. The source remains unchanged. The comparison uses the processed values and its figure states the preceding detrending. result.tables["estimates"] gives the estimates and their units; result.warnings retains failed/refused methods and their reasons. These are software outputs, not proof of a biological rhythm.

Complete numeric-trace example

If hours and values already exist in your measurement workflow, use:

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")

Motion's analysis.circadian.trace and Auto-Organotypic's auto_organotypic.rhythm.trace expose that same constructor. The scientific settings and figure options therefore have the same meanings at all three entrances. Their older measurement wrappers retain their documented legacy settings; they do not supply defaults for this call.

This synthetic seven-day signal has a 23.5-hour rhythm, a slow baseline and one missing sample. Elapsed hours are not a real calendar clock.

import math
import circadian_workbench as workbench

hours = list(range(168))
values = [20 + 0.02 * hour + 4 * math.cos(2 * math.pi * hour / 23.5)
          for hour in hours]
values[50] = None
trace = workbench.trace(
    hours, values, name="Synthetic cell", value_label="Luminescence",
    value_unit="photons/s",
    settings={"period_min_hours": 21, "period_max_hours": 27,
              "period_hours": 24, "bin_minutes": 60},
)
processed = trace.detrend(window_hours=24)
result = processed.compare_periods(["lomb", "mesa"],
                                  settings={"period_max_hours": 26})
print(result.tables["estimates"])
figure = result.plot(theme="classic", show_grid=False)
saved = figure.save("numeric-periods.svg", root="my-figures")
print(saved.path)

# This fit overrides the per-call 24-hour cycle; it does not change the search.
fixed_fit = processed.cosinor(period_hours=23.5, settings={"period_hours": 24})
print(fixed_fit.measurements["amplitude"].value)

The comparison inherits the 21-hour lower search bound and overrides its upper bound to 26 hours. The cosinor uses the explicitly requested 23.5-hour cycle. Missing samples stay missing and baseline-subtracted negative values are valid. Raw activity files still reject negative activity; those checks are not bypassed.

result.run_record retains the completed settings, processing, inputs and environment. The saved producer verifies those sources and software before recomputing, then checks the scientific result and complete figure definition. Keep the original inputs and recorded environment. Changing an input or upgrading a package is a mismatch, not a request to find a historical result or silently install an older engine.

Complete channel example

Channels are measurements from the same subject, not independent replicates. Here two synthetic reporters share one time grid and differ in phase.

import math
import circadian_workbench as workbench

hours = list(range(168))
reporters = {
    "PER2": [10 + math.cos(2 * math.pi * hour / 24) for hour in hours],
    "BMAL1": [10 + math.cos(2 * math.pi * (hour - 6) / 24) for hour in hours],
}
recording = workbench.channels(hours, reporters, name="Synthetic dual reporter",
                              settings={"period_min_hours": 22, "period_max_hours": 26})
result = recording.compare()
print(result.tables["channels"])
result.plot().save("reporter-comparison.svg")

For genuinely separate oscillators, use workbench.population(hours, traces) instead. Calendar-dependent questions need a file/recording with a real origin; the numeric constructors do not invent one. The command-line question entrance accepts files or the demo, not a numeric-array expression. Python and the registered machine interface accept numeric specifications directly.