Shared arguments, results and plots explained¶

This guide explains the shared calling workflow introduced in Workbench 0.8: who owns each definition, how a call gets its settings, and why changing a plot cannot change its scientific answer. It describes the execution order, not a new statistical method; the scientific analysis guide covers the calculations and equations.

For a methods section¶

Use this workflow paragraph alongside the paragraph for the chosen scientific method. The saved call record supplies the experiment-specific inputs, settings and software versions; this paragraph alone is not a complete scientific protocol.

To retain the relationship between sampled observations, analysis choices and reported figures, analyses were invoked through Circadian Workbench's shared scientific interface. Inputs and supplied settings were validated against the installed argument definitions. The requested methods were applied using the resolved settings, and completed-call records retained the consumed inputs, source fingerprints, processing order, effective settings, random seeds where applicable, and software identity. Figures were constructed from completed results with separately resolved display settings. Saved figure bundles retained displayed values and replay instructions; replay checked the recorded sources and environment before recomputation and compared the scientific result and declared figure. These interface and recording rules were original to the project.

Overview¶

Think of a shared recipe book and a dated recipe card: Workbench owns the book; each completed call keeps the exact card it used. Editing a later edition of the book does not rewrite that card. Repeating a recipe also requires the same ingredients and equipment: input data and the recorded software environment.

Workbench owns circadian methods and their argument meanings, units and defaults. Motion and Auto-Organotypic call the selected methods they need; they do not maintain competing circadian registries. The shared figure engine handles appearance, using the installed house style supplied by analysis_kit.style. Scientific settings and display settings remain separate.

Circadian Workbench
  shared argument definitions -> registered scientific methods
                                  ^           ^            ^
                                  |           |            |
                           Python/browser   Motion   Auto-Organotypic

  completed result -> declared figure -> shared figure engine
                                           ^
                                           |
                               installed house style + this figure's options

The analysis in order¶

Bind the input that describes the experiment.
Resolve and validate the settings for this call.
Run the requested method and capture the completed call.
Read the answer through common result views.
Build a figure from the completed result.
Save the figure and verify a later replay.

Reading views and building figures are independent uses of the same completed result. Neither requires the other; saving and replay are optional.

Step 1 - Bind the input¶

A recording file supplies its measured clock and channel metadata. A numeric trace supplies elapsed hours and observations directly, without an intermediate file. Several measurements from one subject are channels; several independent oscillators are a population. This distinction tells the selected method what the observations represent.

Binding an input does not run every available analysis. Elapsed hours do not imply a real calendar date, so date-dependent questions still require an actual recording clock. Source recordings remain read-only.

In the engine: client.open(), client.trace(), client.channels(), client.population() and the input types in contracts.py.

Step 2 - Resolve this call's settings¶

An explicitly named method argument takes priority over the corresponding setting. A setting supplied for this call takes priority over one bound to the input; otherwise the installed default applies. Nothing is inherited from an unrelated earlier run.

An omitted value leaves the next applicable setting in place. Zero and false remain deliberate choices. Fresh invalid settings are refused; compatibility conversion of old saved settings must be requested explicitly and reports its conversions. Changing the original settings dictionary does not retroactively change the bound settings.

In the engine: arguments.CONFIG_ARGUMENTS, arguments.parameter_default(), client._settings(), client._bound_settings() and settings validation in contracts.py.

Step 3 - Run the method and capture the call¶

The shared action registry sends the validated request to its scientific implementation. A convenience call may invoke the prerequisites that its method needs; it does not choose a replacement method from previous results. Explicit processing steps pass their transformed samples onward while retaining their processing order and source identity.

The completed-call record captures the inputs actually consumed, effective settings, applicable randomness and software identity. It records what happened; it is not a database of defaults for future calls. Scientific warnings and refusals remain visible in the returned result.

In the engine: actions.dispatch(), client.ProcessedResult and input capture in run_records.py.

Step 4 - Read a common result¶

The same result object offers a short answer, the complete payload, and declared measurements, tables and series. Each named view retains its units and meaning. A withheld value is not converted to zero, and an error measure is not relabelled as a confidence interval.

Views are detached copies: changing a returned table cannot change the completed scientific record. Specialised results without a particular view retain their original payload instead of inventing a generic measurement or flattening an image into a line.

In the engine: contracts.Result and explicit view mappings in result_views.py.

Step 5 - Build a figure from the result¶

A supported figure uses the values already computed. The figure definition declares the axes, series and specialised geometry; the shared engine resolves the appearance for that figure. Creating or restyling a figure does not reread the recording or rerun the scientific method.

The default house theme is fixed by the installed version. Fonts, sizing and colours can be set explicitly for this figure. Unrelated earlier plots and the legacy global colour table are not inputs to this engine. Specialised geometries retain their meaning: for example, a circular phase map cannot become an arbitrary categorical colour chart.

In the engine: result_figures.plot_result(), figure_definitions.FigureDefinition and figure_engine.resolve_figure().

Step 6 - Save and verify replay¶

Saving writes the figure with its exact displayed data, statistics, evidence and producer script beneath the chosen output root. Source files and conflicting figures are protected. The saved appearance belongs to that figure, not to future calls.

Replay is an explicit new computation. It checks source fingerprints and the recorded software and execution conditions, then compares the scientific result and, for a figure producer, the declared figure. A mismatch is reported; replay does not silently install another version, select historical defaults or substitute an algorithm. Keep the original inputs, recorded environment and fonts. This is not a guarantee of identical image bytes on arbitrary machines.

In the engine: result_figures.Figure.save(), publication.save_result_figure(), result_figures.replay_figure() and verification in run_records.py.

---¶

Reference sections¶

Where each step misleads¶

Step	What goes wrong	What the step cannot tell you
1. Input	Channels are mistaken for independent samples.	Biological replication or a missing real-world clock.
2. Settings	A new package version is assumed to have old defaults.	Whether an upgrade reproduces an earlier run.
3. Execution	A fixed seed is omitted from an explicitly random request.	That repeating a request for fresh randomness gives the same output.
4. Result	A missing value is interpreted as zero.	An effect the method could not identify.
5. Figure	A shared visual style is mistaken for interchangeable methods.	That different estimators have identical assumptions or uncertainty.
6. Replay	Only the image or a project file is retained.	The missing original data or software environment.

Worked examples¶

A complete in-memory call¶

This synthetic fixture demonstrates the interface, not an experimental result. The example deliberately requests just the lomb estimator (Lomb–Scargle period estimation); use the method comparison guide to choose methods for real data.

import numpy as np
import circadian_workbench as workbench

hours = np.arange(0, 240, 0.5)
values = 10 + np.cos(2 * np.pi * hours / 24)
recording = workbench.trace(
    hours, values,
    settings={"period_min_hours": 20, "period_max_hours": 28},
)
result = recording.compare_periods(["lomb"])
figure = result.plot(theme="classic", show_grid=False)

The search bounds stay in result.provenance["effective_config"]. The appearance belongs to figure.definition; figure.data contains the displayed values. Neither figure construction nor accessing these views writes a file.

An explicit override without changing the next call¶

inherited = recording.cosinor()  # installed 24-hour reference cycle
changed = recording.cosinor(
    period_hours=25,
    settings={"period_hours": 26},
)
again = recording.cosinor()

assert inherited.provenance["effective_config"]["period_hours"] == 24
assert changed.provenance["effective_config"]["period_hours"] == 25
assert again.provenance["effective_config"]["period_hours"] == 24

The named 25-hour cycle overrides the per-call 26-hour value. Neither changes the next call. This controls the fixed cycle for the cosinor fit, not the period-search bounds.

For an actual recording, the short path remains:

import circadian_workbench as workbench

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

The relative filename is saved beneath .circadian-agent by default. See figure options for choosing a root, saving both vector formats and replaying the saved figure.

Interpretation guide¶

Shared definitions mean the same argument has one maintained meaning, not that every method accepts every argument.
A central default can change in a future release. Pin the exact version and preserve the recorded environment for old runs; do not rely on an unversioned snippet alone.
The new Motion and Auto-Organotypic trace entrances use Workbench defaults. Legacy wrappers retain their explicit settings; use identical explicit settings when comparing those paths.
A completed snapshot cannot be changed by editing returned views. It does not make a fresh call with changed source data equivalent to the original.
An explicit request for fresh randomness, such as a demo with seed=None, is not deterministic. Its completed record retains the actual seed for replay.
Workbench is the central catalogue of implemented circadian methods. That does not claim that every method in the literature is implemented or independently validated.

Symbols¶

No new mathematical symbols or equations are introduced: these steps describe the calling contract. The synthetic example uses hours for elapsed time and arbitrary units for values. Scientific equations belong to the linked method guides.

Technical reference¶

Data flow¶

[1] client.trace() / client.open()
       -> [2] shared arguments + resolved settings
       -> [3] actions.dispatch() -> scientific method -> completed run record
       -> [4] contracts.Result -> named result views
                              -> [5] result_figures.plot_result()
                                     -> figure_engine.resolve_figure()
                                     -> [6] Figure.save() -> replay_figure()

Files¶

All module paths below are relative to src/circadian_workbench/.

arguments.py: scientific argument definitions, defaults and reusable groups.
actions.py: registered capabilities and dispatch to scientific implementations.
client.py and contracts.py: public calling patterns, validation and common result contract.
result_views.py: declared measurements, tables and series.
figure_definitions.py, result_figures.py and figure_engine.py: figure content, completed-result plotting and shared appearance.
run_records.py and publication.py: completed-call evidence, saved bundles and replay checks.

Configuration¶

These are the settings used by this guide, with defaults from Workbench 0.8. The configuration reference and figure options remain the complete inventories.

Setting	Default	Changes the science?
`period_min_hours`, `period_max_hours`	18 and 30 hours	Yes: candidate search bounds.
`period_hours`	24 hours	Yes: reference cycle, not search bounds.
`period_methods`	`["lomb"]`	Yes: methods requested by comparison.
`bin_minutes`	15 minutes	Yes: regular analysis grid.
`theme`	`"pyflash"`	No: figure appearance.
`show_grid`	`None`, resolved from the theme	No: decorative gridlines.
`root`	`.circadian-agent`	No: output location.

Settings precedence is named method argument, per-call settings, explicitly bound settings, then installed defaults. Use either settings or its compatibility alias config, never both. None is omitted; zero and False are explicit.

Naming and outputs¶

result.answer: readable summary; result.data: full scientific payload.
result.measurements, result.tables, result.series: explicitly named views with units.
result.run_record: detached record of the completed invocation; result.script: verified scientific replay.
result.available_plots: supported figure views; result.plot(): detached figure.
figure.data, figure.definition: displayed values and resolved figure specification.
saved.path, saved.files: actual saved carrier and all companion paths.

Saving produces a Scalable Vector Graphics (SVG) or Portable Document Format (PDF) carrier, comma-separated value (CSV) tables, JavaScript Object Notation (JSON) evidence and a Python producer. The output guide distinguishes these from project files and backup snapshots.

Verification before trusting a change¶

Check shared argument definitions against their generated help and consumer selections.
Check settings precedence, invalid inputs and the absence of cross-call state.
Check that result views are detached and plotting never reruns science.
Check replay in a separate process, including changed-source and changed-environment refusals.
Build the documentation and execute its short examples against the intended package version.

References¶

Circadian Workbench source, shared-interface implementation released in 0.8.0: the modules listed above establish steps 1–6. No published source — the argument-resolution, result-view, figure-dispatch and replay contracts are original to this project.

No statistical estimator or new scientific equation is introduced here. The scientific analysis guide provides the method-specific explanations and references.