spacr.figures.bundle

Export a graph with its data, statistics, and generating settings.

Each export creates a uniquely named directory containing PDF and PNG renderings, the plotted data, a statistical summary, and a JSON settings record. Statistical summaries use spacr.figures.stats.compare(), the same comparison engine used by interactive figures.

Functions

save(→ str)

Write a reproducible figure-export bundle.

statistics_frame(→ pandas.DataFrame)

Build the statistical table stored with an exported graph.

statistics_rows(→ list)

Convert a statistical comparison into labeled CSV rows.

Module Contents

spacr.figures.bundle.save(folder: str, name: str, *, render: Callable[[str], Any], data: pandas.DataFrame | None = None, groups: Mapping[str, Sequence] | None = None, unit: str = 'observation', paired: bool = False, settings: Mapping[str, Any] | None = None) → str[source]

Write a reproducible figure-export bundle.

Parameters:

  • folder (str) – Parent directory for the export.

  • name (str) – Graph name used for the directory and image files.

  • render (callable) – Function called once with the PDF path and once with the PNG path.

  • data (pandas.DataFrame, optional) – Filtered rows represented by the graph.

  • groups (mapping of str to sequence, optional) – Values used to generate statistics.csv.

  • unit (str, default="observation") – Experimental unit represented by one value.

  • paired (bool, default=False) – Whether group observations are paired.

  • settings (mapping, optional) – Settings and filters used to generate the graph.

Returns:

str – Path to the newly created bundle directory. A numeric suffix is added when the requested directory already exists.

spacr.figures.bundle.statistics_frame(groups: Mapping[str, Sequence] | None = None, *, unit: str = 'observation', paired: bool = False) → pandas.DataFrame[source]

Build the statistical table stored with an exported graph.

Parameters:

  • groups (mapping of str to sequence, optional) – Values grouped by comparison label. Fewer than two groups produce an explanatory row rather than a statistical test.

  • unit (str, default="observation") – Experimental unit represented by one value.

  • paired (bool, default=False) – Whether observations are paired across groups.

Returns:

pandas.DataFrame – Columns item, value, and note. Comparison errors are recorded in the table instead of being raised.

spacr.figures.bundle.statistics_rows(comparison) → list[source]

Convert a statistical comparison into labeled CSV rows.

Parameters:

comparison (spacr.figures.stats.Comparison) – Comparison containing group sizes, assumption checks, test results, and effect estimates.

Returns:

list of tuple – (item, value, note) rows suitable for statistics.csv.