From ca0f0d92da6e1064391c636e614c963679a2644c Mon Sep 17 00:00:00 2001 From: mbsantiago Date: Wed, 6 May 2026 19:43:50 +0100 Subject: [PATCH] docs: polish migration guide wording --- docs/source/legacy/migration-guide.md | 135 ++++++++++++++------------ 1 file changed, 75 insertions(+), 60 deletions(-) diff --git a/docs/source/legacy/migration-guide.md b/docs/source/legacy/migration-guide.md index 2dbd8b4..61ac98c 100644 --- a/docs/source/legacy/migration-guide.md +++ b/docs/source/legacy/migration-guide.md @@ -1,55 +1,80 @@ -# Migration guide: legacy to current workflows +# BatDetect2 2.0 migration guide -Use this guide when moving from the previous BatDetect2 workflow to the current -CLI and API. +Use this guide when moving from BatDetect2 1.x workflows to the CLI and API in +2.x. -## Who should migrate now +## Why migrate -You should migrate if: +You get access to newer features. +The codebase changed quite a bit and now gives you much more control over the +workflow through config files, improved training and fine-tuning code, and a +more flexible sound target definition system. -- you are starting a new workflow, -- you want the current docs path, -- you want the newer CLI and API surface, -- you are maintaining code that does not depend on the exact legacy JSON or - feature outputs. +You can also run newer or improved models. +That includes updated versions of the UK model, plus other models trained with +the newer codebase. -You may need the legacy workflow a bit longer if: +We are no longer actively supporting version 1. +No new enhancements are planned there, and only major bug fixes may still be +considered. +Future work is focused on version 2, including compatibility with newer Python +versions. -- downstream tooling depends on the exact old output structure, -- you rely on older notebooks built around `batdetect2.api`, -- you depend on legacy feature extraction outputs without a validated - replacement yet. +## Deprecation plan -## CLI mapping +We have kept the `batdetect2.api` module and the `batdetect2 detect` CLI command +in place for now. +You can keep using them without changing your current workflow. +However, many of the internal functions were relocated, removed or modified. +If your code relied on anything outside of the `api` module, it may break. +It is worth checking the new docs first, since there may already be a newer +feature that covers your use case. +If not, please open an issue. + +Because the old `api` and CLI command are now redundant with the newer stack, we +plan to remove them in about a year. +If you want to keep pipelines up to date and long-running, it is a good idea to +migrate to version 2. + +## How to migrate + +If you are only using the `batdetect2 detect` CLI command or the +`batdetect2.api` module, the migration should be fairly simple. +This guide only covers these two entry points. + +### CLI mapping - `batdetect2 detect AUDIO_DIR ANN_DIR DETECTION_THRESHOLD` -> `batdetect2 - process directory MODEL_PATH AUDIO_DIR OUTPUT_PATH --detection-threshold ...` + process directory AUDIO_DIR OUTPUT_PATH --detection-threshold + DETECTION_THRESHOLD ...` Main changes: -- the model path is now a positional argument on the `process` subcommand, -- the current workflow expects an explicit checkpoint path rather than silently - relying on the old default CLI behavior, -- output formatting is configurable, -- threshold override is an option rather than a required positional argument, -- there are separate subcommands for directory, file-list, and dataset-driven - inference. +- outputs can be written in different formats. + See the output format reference for the available options. +- the detection threshold is now an option instead of a required positional + argument. +- options like saving CNN features are now controlled through config rather than + command flags. +- there are separate subcommands for processing a directory, file list, or + dataset. -## Python API mapping +### Python API mapping - old: `import batdetect2.api as api` - current: - `from batdetect2.api_v2 import BatDetect2API` + `from batdetect2 import BatDetect2API` Typical migration shape: ```python from pathlib import Path -from batdetect2.api_v2 import BatDetect2API +from batdetect2 import BatDetect2API -api = BatDetect2API.from_checkpoint(Path("path/to/model.ckpt")) +# If no checkpoint is provided, the default UK model is loaded +api = BatDetect2API.from_checkpoint() prediction = api.process_file(Path("path/to/audio.wav")) ``` @@ -60,48 +85,38 @@ Useful replacements: - legacy `process_spectrogram` -> current `BatDetect2API.process_spectrogram` - legacy one-off batch loops -> current `process_files` or CLI `process` -## Output and terminology changes +### Model changes -Legacy workflows often centered on: +The default checkpoint used by the new CLI `process` commands and by +`BatDetect2API` is a newer model trained from scratch using the updated training +code, but the same model architecture, training procedure, and data. +Performance did not change substantially, but some differences are still +expected. -- BatDetect2-style JSON output, -- `cnn_feats`, -- `spec_features`, -- `spec_slices`. +### Species names -Current workflows center on: +For the default UK model there are two naming changes: -- `ClipDetections` and `Detection` objects, -- per-detection `detection_score`, -- per-detection `class_scores`, -- per-detection `features`, -- configurable output formatters. +1. The original model had a typo and instead of `Barbastella barbastellus` it + used `Barbastellus barbastellus`. + This has now been corrected. +2. There has been a recent change in name for `Eptesicus serotinus` to + `Cnephaeus serotinus`. -## What to validate after migration +## Stay on version 1 -Before replacing a legacy workflow in production or research analysis, validate: +If you prefer not to migrate to version 2 yet, you can keep using version 1. +In that case, it is a good idea to pin your dependency: -- that thresholds are still appropriate, -- that outputs are being saved in the right format, -- that downstream code reads the new outputs correctly, -- that feature-related assumptions still hold, -- that evaluation and ecological interpretation are unchanged only where you - have actually verified that. - -## Migration checklist - -1. Identify the old entry points you use. -2. Replace them with the current CLI or `BatDetect2API` equivalents. -3. Choose an output format explicitly. -4. Re-run on a small reviewed subset. -5. Compare outputs and downstream behavior. -6. Update any notebooks or scripts that assume legacy field names. +```bash +pip install "batdetect2>=1.3.1,<2" +``` ## Related pages -- Current getting started: +- Getting started: {doc}`../getting_started` -- Current tutorials: +- Tutorials: {doc}`../tutorials/index` -- Current API reference: +- API reference: {doc}`../reference/api`