batdetect2/docs/source/how_to/save-predictions-in-different-output-formats.md

How to save predictions in different output formats

Use this guide when you need BatDetect2 outputs in a specific representation for downstream tools.

Choose the format that matches the job

Current built-in output formats include:

• raw: one NetCDF file per clip, best for rich structured outputs,
• parquet: tabular storage for data analysis workflows,
• soundevent: prediction-set JSON for soundevent-style tooling,
• batdetect2: legacy per-recording JSON output.

Select a format from the CLI

Use --format for quick experiments.

batdetect2 predict directory \
  path/to/model.ckpt \
  path/to/audio_dir \
  path/to/outputs \
  --format parquet

Use an outputs config for repeatable runs

Use an outputs config when you want reproducible control over format and transforms.

Example:

format:
  name: raw
  include_class_scores: true
  include_features: true
  include_geometry: true
transform:
  detection_transforms: []
  clip_transforms: []

Run with:

batdetect2 predict directory \
  path/to/model.ckpt \
  path/to/audio_dir \
  path/to/outputs \
  --outputs-config path/to/outputs.yaml

Pick the simplest useful format

• Use raw if you want the richest output surface and easy round-tripping.
• Use parquet if you want tabular analysis in Python or data-lake workflows.
• Use soundevent if you want prediction-set JSON.
• Use batdetect2 only when you need the legacy JSON shape.

Related pages

• Outputs config reference: {doc}../reference/outputs-config
• Output formats reference: {doc}../reference/output-formats
• Output transforms reference: {doc}../reference/output-transforms