SanPy Zarr export

SanPy Zarr is a self-contained collection format for electrophysiology recordings and their SanPy analyses. Export supports ABF and canonical .sanpy source recordings, while the supplied SanPy bAnalysis objects provide metadata, applied detection parameters, analysis results, and the filtered and dV/dt signals.

The completed collection does not contain or require its source recordings or SanPy HDF5 catalog.

Explicit API

The exporter is not imported by sanpy or by package initializers. SanPy installs its Zarr and Parquet dependencies in the normal Python 3.13 environment, so CSV, Parquet, and the default "both" mode require no additional installation step.

from sanpy.io.zarr_export.exporter import export_collection

export_collection(
    analyses,
    "experiment.sanpy.zarr",
    table_format="both",
)

table_format accepts "csv", "parquet", or "both". CSV and Parquet are alternative representations of the same two logical tables. JSON is used for structured metadata and definitions; Zarr is used for point-aligned arrays.

Layout

experiment.sanpy.zarr/
  collection.json
  recordings/
    <recording-id>/
      recording.json
      data.zarr/
      metadata/
        file_metadata.json
        file_metadata_definitions.json
        experimental_metadata.json
        experimental_metadata_definitions.json
        detection_parameters.json
        detection_parameter_definitions.json
        analysis_result_definitions.json
        trace_overlays.json
      tables/
        epochs.csv
        epochs.parquet
        analysis_results.csv
        analysis_results.parquet

Only requested table representations are present.

file_metadata.json stores immutable facts read or derived from the source recording, including acquisition timestamps, source channel and sweep counts, epochs per sweep, axis labels, recording mode, sampling frequency, and an optional ABF user list. experimental_metadata.json stores the separate set of editable experimental annotations using canonical snake-case keys. Each values document has a sibling definitions document containing its human-readable display_name values and any controlled choices.

Arrays

point means one sampled position within a sweep.

Array	Dimensions	Meaning
time	point	Seconds from the start of a sweep
raw	sweep, channel, point	Scaled recorded values
command	sweep, channel, point	Command waveform for the selected channel
epoch_index	sweep, channel, point	Epoch number, or -1 outside an epoch
filtered	sweep, point	SanPy filtered channel-0 recording, when present
dvdt	sweep, point	SanPy channel-0 derivative, when present

All arrays use Zarr format 3. Recorded and command values retain float64 precision in the units declared for each channel.

Definitions and values

detection_parameters.json stores the actual values applied to the recording. detection_parameter_definitions.json separately explains the available parameters.

experimental_metadata.json and file_metadata.json likewise store values separately from their *_definitions.json presentation metadata. SanPy's runtime definitions are authoritative; the exported documents let thin clients display labels without duplicating them.

analysis_results stores the actual one-row-per-spike results. analysis_result_definitions.json separately explains result columns. SanPy's runtime definitions are the source of truth for both definition documents, including their presentation-only category values. The exporter preserves native SanPy schema keys and does not infer categories or rename fields. Nested result values are canonical JSON text in tabular files.

Each collection member also carries a complete display summary in collection.json: recording name, sweeps, channels, points, sampling rate, result count, protocol, and acquisition datetime. A client can render a collection table without opening recording resources. trace_overlays.json stores runtime-owned mappings from result columns to meaningful trace points. It intentionally contains no colors, marker sizes, or layout instructions.

Installation safety

Export is built and validated in a temporary sibling directory. An existing destination is protected unless overwrite=True is supplied. Replacement uses a backup that is restored if installation fails.