Skip to content

Figure options

Figures resolve their display choices from the installed analysis_kit.style house definitions and the options on that figure. Plotting does not change scientific settings, units, missing values or the result being plotted.

The shared engine accepts theme, width, height, preset, text_scale, font_family, show_grid, legend, line_width, marker_size, group_colours and colours. Unknown options fail with an explanation. The live definitions are figure_engine.DISPLAY_ARGUMENTS, also returned by the browser analysis catalogue under display.

  • theme="pyflash" is the fixed default. classic remains available. house, pyflash-house and pyflash_house mean pyflash; legacy, old, circadian and prism mean classic.
  • width and height are viewport pixels. Supplying just one keeps the declared aspect ratio; supplying both fits the geometry without stretching. preset instead uses the existing publication page sizes in millimetres: single_column, double_column, a4_portrait or a4_landscape. Viewports scale the whole figure; for a compact physical page, increase text_scale to keep text readable (for example, 3.5 with classic and single_column). They do not automatically rearrange scientific geometry.
  • text_scale multiplies house text sizes. font_family chooses a font. Data line width and marker diameter are pixels; axis widths stay independent.
  • show_grid controls decorative gridlines, not timing, significance or table rules. Its omitted value follows the chosen theme.
  • Line figures accept legend=True, False, "top", "right", or a mapping with position and orientation (horizontal/vertical). Maps and other specialised geometries retain their semantic keys and reject this option.
  • group_colours={"Control": "circadian_teal"} declares colours by name, independent of group ordering or subsets. colours={"mean": "blue"} overrides a specific declared series. House colour names and literal colours are accepted. Phase maps keep their circular phase scale.

Compatibility spellings are style → theme, text_size_scale → text_scale, group_colors → group_colours, and colors → colours. Supply only one spelling. Omitted/None values use the fixed defaults; False is an explicit choice.

Actograms retain their separate layer, clock, paging and marker settings. Explicit actogram-editor font/text controls are retained; otherwise the shared theme supplies their typography. Browser comparison thumbnails use their existing compact text sizing.

The old analysis_kit.style.declare_conditions global colour interface is still supported by legacy group-renderer calls. It is not an input to the new figure engine: declare group colours with the figure instead. Resolved figures contain detached display values and can be rendered after unrelated plots without adopting their settings. Reproducibility assumes fixed data, explicit options and software versions, not arbitrary upgrades.

Plot and save a completed result

import circadian_workbench as workbench

recording = workbench.open("mouse.awd")
result = recording.detrend(window_hours=24).compare_periods()
saved = result.plot().save("periods.svg")
print(saved.path)  # actual path under .circadian-agent

result.available_plots lists explicit view names, default first. For example, recording.bouts() offers bout_lengths and interbout_serial:

result = recording.bouts()
figure = result.plot("interbout_serial", theme="classic", show_grid=False)
saved = figure.save("intervals.pdf", root="my-figures")

Plotting uses the completed result, never a new scientific analysis or a fresh read of the source. figure.definition and figure.data return detached copies of the declared geometry and displayed values. Named display arguments override the options mapping. Results without a declared figure explain this explicitly; use their measurements, tables or unchanged text-oriented show() instead.

Saving supports SVG and PDF. Relative names stay beneath the run's chosen root (default .circadian-agent); output is a compatibility alias for root. Source inputs, source aliases, companion-file collisions and path escapes are protected. An existing different figure requires a new filename. Saving the same figure again, or in both formats with the same stem, retains its identity.

saved.files lists the carrier, exact figure-data and statistics CSV files, JSON evidence and a plot_<name>_<format>.py producer. The carrier also embeds its figure data, resolved display settings, scientific settings, processing history, source identity and recorded software versions using ReproFig. The trusted producer reruns the complete scientific chain, rejects changed sources or versions, checks the declared figure and writes reproduced_<name>. The completed result.run_record supplies the actual consumed inputs, effective arguments, seeds and processing order. Replay checks Python-source identity as well as package versions and platform conditions, compares the complete scientific result, then compares the declared figure values and style. Editing a returned result dictionary cannot alter this completed snapshot. No historical defaults, automatic installs or claim of byte-identical PDF files are involved. A manually constructed Result without captured inputs can still plot its declared values, but is explicitly marked as lacking scientific replay.