From df9f21b5947c40a68932b279314edb4212e0c155 Mon Sep 17 00:00:00 2001 From: mbsantiago Date: Wed, 6 May 2026 20:02:48 +0100 Subject: [PATCH] docs: expand legacy cli and api pages --- docs/source/legacy/cli-detect.md | 48 +++++++++++++++++++------------ docs/source/legacy/python-api.md | 49 +++++++++++++++++++++----------- 2 files changed, 62 insertions(+), 35 deletions(-) diff --git a/docs/source/legacy/cli-detect.md b/docs/source/legacy/cli-detect.md index c22e77e..10a13da 100644 --- a/docs/source/legacy/cli-detect.md +++ b/docs/source/legacy/cli-detect.md @@ -1,38 +1,50 @@ -# Legacy CLI workflow: `batdetect2 detect` +# CLI workflow: `batdetect2 detect` This page documents the previous CLI workflow based on `batdetect2 detect`. ```{warning} -This is legacy documentation. +This is documentation for a previous version of batdetect2. For new workflows, use `batdetect2 process directory` instead. If you are migrating, start with {doc}`migration-guide`. ``` -## Legacy command shape +## Processing a folder of audio files ```bash batdetect2 detect AUDIO_DIR ANN_DIR DETECTION_THRESHOLD ``` -Common legacy options included: - -- `--cnn_features` -- `--spec_features` -- `--time_expansion_factor` -- `--save_preds_if_empty` -- `--model_path` - -## Current replacement - -The closest current CLI entry point is: +Example: ```bash -batdetect2 process directory \ - path/to/model.ckpt \ - path/to/audio_dir \ - path/to/outputs +batdetect2 detect example_data/audio/ example_data/anns/ 0.3 ``` +This command scans a directory of audio files, runs the BatDetect2 detector on +each file, and writes BatDetect2-style outputs into `ANN_DIR`. +Those outputs usually include one JSON file and one CSV file per recording, and +can optionally include extra feature CSVs. + +`AUDIO_DIR` is the folder containing the input `.wav` files. +`ANN_DIR` is the folder where model outputs are written. + +`DETECTION_THRESHOLD` controls which detections are kept. +Predictions below this score are discarded. +Smaller values keep more detections, but usually also increase mistakes. + +Common options: + +- `--cnn_features` Write extra CNN feature CSV files for each recording. +- `--spec_features` Extract and write traditional acoustic spectrogram feature + CSV files. + These are saved as `*_spec_features.csv` files. +- `--time_expansion_factor` Set the time expansion factor used for all files in + the run. +- `--save_preds_if_empty` Save output files even when no detections are found. +- `--model_path` Use a specific checkpoint instead of the included default + model. + If omitted, the command uses the default model trained on UK data. + ## Related pages - Migration guide: diff --git a/docs/source/legacy/python-api.md b/docs/source/legacy/python-api.md index 1091599..9e07f04 100644 --- a/docs/source/legacy/python-api.md +++ b/docs/source/legacy/python-api.md @@ -3,37 +3,52 @@ This page documents the previous Python API workflow based on `batdetect2.api`. ```{warning} -This is legacy documentation. -For new workflows, use `batdetect2.api_v2.BatDetect2API`. +This is documentation for a previous version of batdetect2. +For new workflows, use `batdetect2.BatDetect2API`. If you are migrating, start with {doc}`migration-guide`. ``` -## Legacy entry points +## Using BatDetect2 in Python -Common legacy functions included: +If you prefer to process data inside a Python script, you can use the `batdetect2.api` module. -- `process_file` -- `process_audio` -- `process_spectrogram` -- `load_audio` -- `generate_spectrogram` -- `postprocess` +This interface gives you a simple entry point for running the built-in BatDetect2 model and also exposes the default model and default configuration more directly than the current API. -The legacy API also exposed the default model and default config more directly. +You can process a whole file in one step, or load audio, generate a spectrogram, and work with lower-level functions yourself. -## Current replacement +Common functions: -The current Python path is: +- `process_file` Load an audio file, run the model, and return BatDetect2-style results for that recording. +- `process_audio` Run inference on an audio array that is already loaded in memory. +- `process_spectrogram` Run inference starting from a spectrogram tensor instead of raw audio. +- `load_audio` Load and resample audio using the legacy preprocessing path. +- `generate_spectrogram` Convert audio into the spectrogram representation expected by the model. +- `postprocess` Convert raw model outputs into detections and extracted features. + +Typical usage: ```python -from pathlib import Path +import batdetect2.api as api -from batdetect2.api_v2 import BatDetect2API +AUDIO_FILE = "example_data/audio/20170701_213954-MYOMYS-LR_0_0.5.wav" -api = BatDetect2API.from_checkpoint(Path("path/to/model.ckpt")) -prediction = api.process_file(Path("path/to/audio.wav")) +# Process a whole file +results = api.process_file(AUDIO_FILE) +annotations = results["pred_dict"]["annotation"] + +# Or, load audio and compute spectrograms +audio = api.load_audio(AUDIO_FILE) +spec = api.generate_spectrogram(audio) + +# And process the audio or the spectrogram with the model +detections, features, spec = api.process_audio(audio) +detections, features = api.process_spectrogram(spec) + +# Integrate the detections or extracted features into your own analysis ``` +This interface is most useful when you want to work directly with detections, features, spectrograms, or intermediate arrays inside your own code. + ## Related pages - Migration guide: {doc}`migration-guide`