From 9635a858bdcf5ec99a06c963b9dd472f1c53e18d Mon Sep 17 00:00:00 2001 From: mbsantiago Date: Thu, 30 Apr 2026 11:48:07 +0100 Subject: [PATCH] docs: align docs entry points with current workflows --- README.md | 91 ++++++++++++++++++++++++++++-- docs/source/explanation/index.md | 11 +++- docs/source/getting_started.md | 74 ++++++++++++++++++------ docs/source/how_to/index.md | 12 +++- docs/source/index.md | 97 ++++++++++++++++++++------------ docs/source/reference/index.md | 12 +++- docs/source/tutorials/index.md | 9 ++- 7 files changed, 239 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index a085cd9..a3f05ad 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,40 @@ # BatDetect2 Code for detecting and classifying bat echolocation calls in high frequency audio recordings. -## Getting started -### Python Environment +## What BatDetect2 is useful for -We recommend using an isolated Python environment to avoid dependency issues. Choose one -of the following options: +BatDetect2 can help you screen recordings for bat calls, +find recordings that need expert review, +and compare model outputs across sites or projects with appropriate caution. + +It is best used as a tool to support ecological work, +not as a replacement for validation or expert interpretation. + +## Start here + +If you want the simplest current workflow, +use the documentation site and start with: + +- getting started: `docs/source/getting_started.md` +- first tutorial: `docs/source/tutorials/run-inference-on-folder.md` + +The current docs default to: + +- the current command-line workflow: `batdetect2 predict` +- the current Python workflow: `batdetect2.api_v2.BatDetect2API` + +If you need the previous workflow based on `batdetect2 detect` or `batdetect2.api`, +use the legacy docs section and migration guide in the docs site. + +## Install BatDetect2 + +If you already use Python, +activate the environment where you want BatDetect2 to live. + +If not, +create a fresh one first so BatDetect2 stays separate from other software on your machine. + +Two common options are: * Install the Anaconda Python 3.10 distribution for your operating system from [here](https://www.continuum.io/downloads). Create a new environment and activate it: @@ -14,7 +43,7 @@ conda create -y --name batdetect2 python==3.10 conda activate batdetect2 ``` -* If you already have Python installed (version >= 3.8,< 3.11) and prefer using virtual environments then: +* If you already have Python installed (version >= 3.10,< 3.14), you can create a fresh environment with: ```bash python -m venv .venv @@ -37,6 +66,43 @@ pip install . Make sure you have the environment activated before installing `batdetect2`. +## Run BatDetect2 on a folder of recordings + +Once installed, +the simplest current workflow is to run BatDetect2 on a folder of `.wav` files. + +If you are working from this repository checkout, +you can use this example checkpoint path: + +```text +src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar +``` + +Example command: + +```bash +batdetect2 predict directory \ + src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar \ + example_data/audio \ + outputs +``` + +This will scan the audio files in `example_data/audio` +and save model outputs to `outputs`. + +For the full beginner walkthrough, +use `docs/source/tutorials/run-inference-on-folder.md`. + +## Legacy workflow + +The sections below are kept only for people maintaining older BatDetect2 scripts and analysis pipelines. + +If you are new to BatDetect2, +stop here and use the current docs and command above. + +If you really do need the older workflow, +the reference material is below. + ## Try the model 1) You can try a demo of the model (for UK species) on [huggingface](https://huggingface.co/spaces/macaodha/batdetect2). @@ -48,9 +114,15 @@ Make sure you have the environment activated before installing `batdetect2`. After following the above steps to install the code you can run the model on your own data. +The remainder of this section is legacy reference material. + ### Using the command line +The commands below describe the legacy CLI workflow. + +For new work, prefer the current docs and `batdetect2 predict`. + You can run the model by opening the command line and typing: ```bash batdetect2 detect AUDIO_DIR ANN_DIR DETECTION_THRESHOLD @@ -73,6 +145,10 @@ You can also specify which model to use by setting the `--model_path` argument. ### Using the Python API +The examples below describe the legacy Python API. + +For new work, prefer `batdetect2.api_v2.BatDetect2API` and the current docs site. + If you prefer to process your data within a Python script then you can use the `batdetect2` Python API. ```python @@ -98,7 +174,10 @@ You can integrate the detections or the extracted features to your custom analys ## Training the model on your own data -Take a look at the steps outlined in finetuning readme [here](batdetect2/finetune/readme.md) for a description of how to train your own model. +Take a look at the training tutorial in the docs site first. + +If you are working from this repository checkout, +start with `docs/source/tutorials/train-a-custom-model.md`. ## Data and annotations diff --git a/docs/source/explanation/index.md b/docs/source/explanation/index.md index 6d4f212..51557bb 100644 --- a/docs/source/explanation/index.md +++ b/docs/source/explanation/index.md @@ -1,14 +1,19 @@ -# Explanation +# Understanding -Explanation pages describe why BatDetect2 behaves as it does and how to reason -about trade-offs. +Understanding pages explain how BatDetect2 works, what its outputs mean, and how to reason about trade-offs. + +Use this section when you want help interpreting the tool, not just running it. ```{toctree} :maxdepth: 1 +what-batdetect2-predicts +interpreting-formatted-outputs +extracted-features-and-embeddings model-output-and-validation postprocessing-and-thresholds pipeline-overview preprocessing-consistency target-encoding-and-decoding +evaluation-concepts-and-matching ``` diff --git a/docs/source/getting_started.md b/docs/source/getting_started.md index a197522..8e36bd1 100644 --- a/docs/source/getting_started.md +++ b/docs/source/getting_started.md @@ -1,22 +1,41 @@ # Getting started -BatDetect2 is both a command line tool (CLI) and a Python library. +If you want to run BatDetect2 on your recordings, +start with the command-line route below. -- Use the CLI if you want to run existing models or train your own models from - the terminal. -- Use the Python package if you want to integrate BatDetect2 into your own - scripts, notebooks, or analysis pipeline. +You do not need to write Python code for a standard first run. + +BatDetect2 also has a Python interface, +but that is mainly for users writing their own analysis scripts. + +- Use the command-line route if you want to run an existing model or train your own model by typing commands in a terminal window. +- Use the Python route only if you already want to work in scripts or notebooks. + +```{note} +If you are looking for the previous BatDetect2 workflow based on `batdetect2 detect` or `batdetect2.api`, go to {doc}`legacy/index`. +New docs default to the current `predict` CLI and `BatDetect2API` workflow. +``` If you want to try BatDetect2 before installing anything locally: - [Hugging Face demo (UK species)](https://huggingface.co/spaces/macaodha/batdetect2) - [Google Colab notebook](https://colab.research.google.com/github/macaodha/batdetect2/blob/master/batdetect2_notebook.ipynb) -## Prerequisites +## The simplest route for most users + +1. Install BatDetect2. +2. Use a model checkpoint. +3. Run the first tutorial on a folder of recordings. + +If that is what you want, +you can ignore the Python sections for now. + +## Install BatDetect2 We recommend `uv` for both workflows. -`uv` is a fast Python package and environment manager that keeps installs -isolated and reproducible. + +`uv` is a tool that helps install Python software cleanly, +without mixing it into the rest of your machine. - Use `uv tool` to install the CLI. - Use `uv add` to add `batdetect2` as a dependency in a Python project. @@ -26,8 +45,8 @@ Install `uv` first by following their ## Install the CLI -The following installs `batdetect2` in an isolated tool environment and exposes -the `batdetect2` command on your machine. +The following installs `batdetect2` in its own small environment and makes the +`batdetect2` command available on your machine. ```bash uv tool install batdetect2 @@ -49,16 +68,34 @@ Run your first workflow: Go to {doc}`tutorials/run-inference-on-folder` for a complete first run. -## Integrate with your Python project +## Choose a model checkpoint -If you are using BatDetect2 from Python code, add it to your project -dependencies: +The current command-line and Python workflows expect an explicit checkpoint path. + +A checkpoint is the saved model file that BatDetect2 will use for prediction. + +You can use: + +- a checkpoint you trained yourself, or +- a checkpoint distributed with your installation or repository checkout. + +In this repository checkout, an example pretrained checkpoint is available at: + +```text +src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar +``` + +Use that path in the tutorial commands if you want a concrete starting point from this source tree. + +## Python route for users writing code + +If you are using BatDetect2 from Python code, add it to your Python project: ```bash uv add batdetect2 ``` -This keeps dependency metadata and the environment in sync. +This keeps your project settings and installed packages in sync. ### Alternative with `pip` @@ -77,7 +114,10 @@ pip install batdetect2 ## What's next -- Run your first detection workflow: +- Run your first workflow on a folder of recordings: {doc}`tutorials/run-inference-on-folder` -- For practical task recipes, go to {doc}`how_to/index` -- For command and option details, go to {doc}`reference/cli/index` +- If you write code and want the Python route: + {doc}`tutorials/integrate-with-a-python-pipeline` +- For common practical tasks, go to {doc}`how_to/index` +- For detailed command help, go to {doc}`reference/cli/index` +- To understand outputs and trade-offs, go to {doc}`explanation/index` diff --git a/docs/source/how_to/index.md b/docs/source/how_to/index.md index 4ae1749..4fafe5a 100644 --- a/docs/source/how_to/index.md +++ b/docs/source/how_to/index.md @@ -1,12 +1,22 @@ # How-to Guides -How-to guides help you complete specific tasks while working. +How-to guides help you answer practical questions once you are past the first tutorial. + +Use this section when you already know the basic workflow and want help with one specific task. ```{toctree} :maxdepth: 1 +choose-an-inference-input-mode run-batch-predictions +tune-inference-clipping tune-detection-threshold +inspect-class-scores-in-python +inspect-detection-features-in-python +save-predictions-in-different-output-formats +fine-tune-from-a-checkpoint +choose-and-configure-evaluation-tasks +interpret-evaluation-outputs configure-aoef-dataset import-legacy-batdetect2-annotations configure-audio-preprocessing diff --git a/docs/source/index.md b/docs/source/index.md index a158b33..c676128 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,63 +1,87 @@ # Home -Welcome to the batdetect2 docs. +Welcome to the BatDetect2 documentation. -## What is batdetect2? +## What is BatDetect2? -`batdetect2` is a bat echolocation detection model. -It detects each individual echolocation call in an input spectrogram, draws a -box around each call event, and predicts the most likely species for that call. -A recording can contain many calls from different species. +`batdetect2` detects bat echolocation calls in audio recordings. -The current default model is trained for 17 UK species but you can also train -new models from your own annotated data. +It can help you screen large collections of recordings, +find files that need expert review, +and support ecology and conservation work where manual review alone would be slow. -For details on the approach please read our pre-print: -[Towards a General Approach for Bat Echolocation Detection and Classification](https://www.biorxiv.org/content/10.1101/2022.12.14.520490v1) +In practice, +BatDetect2 takes recordings, +looks for likely bat calls, +draws a box around each detected event, +and scores the most likely class for that event. -## What you can do +The current default model is trained for 17 UK species. -- Run inference on your recordings and export predictions for downstream - analysis: +The library also supports custom training, +fine-tuning, +evaluation, +and more advanced use from Python. + +For details on the underlying approach, see the pre-print: +[Towards a General Approach for Bat Echolocation Detection and Classification](https://www.biorxiv.org/content/10.1101/2022.12.14.520490v1) + +## A good first use for BatDetect2 + +BatDetect2 is a good fit when you want to: + +- scan many recordings for likely bat activity, +- prioritize files for expert review, +- compare outputs across projects with appropriate caution, +- build reviewed local datasets for later model improvement. + +It is not a substitute for validation. + +## Main user journeys + +- I want to run the model on my recordings: {doc}`tutorials/run-inference-on-folder` -- Train a custom model on your own annotated data: - {doc}`tutorials/train-a-custom-model` -- Evaluate model performance on a held-out test set: - {doc}`tutorials/evaluate-on-a-test-set` -- Integrate batdetect2 into Python scripts and notebooks: +- I write code and want to use Python: {doc}`tutorials/integrate-with-a-python-pipeline` +- I want to train or fine-tune a custom model: + {doc}`tutorials/train-a-custom-model` +- I want to evaluate a trained model on held-out data: + {doc}`tutorials/evaluate-on-a-test-set` ```{warning} Treat outputs as model predictions, not ground truth. -Always validate on reviewed local data before using results for ecological -inference. +Always validate on reviewed local data before using results for ecological inference. ``` -## Where to start +```{note} +Looking for the previous BatDetect2 workflow? +See {doc}`legacy/index`. +The legacy docs are still available, but new workflows should use `batdetect2 predict` and `BatDetect2API`. +``` -If you are new, start with {doc}`getting_started`. +## How to use this site -For a low-code path, go to {doc}`tutorials/index`. -If you are Python-savvy and want more control, go to {doc}`how_to/index` and -{doc}`reference/index`. +Start with {doc}`getting_started` if you are new. -Each section has a different purpose: -some pages teach by example, some focus on practical tasks, some are lookup -material, and some explain trade-offs. +Then choose the section that matches what you need. -| Section | Best for | Start here | -| ------------- | ------------------------------------------- | ------------------------ | -| Tutorials | Learning by doing | {doc}`tutorials/index` | -| How-to guides | Solving practical tasks | {doc}`how_to/index` | -| Reference | Looking up commands, configs, and APIs | {doc}`reference/index` | -| Explanation | Understanding design choices and trade-offs | {doc}`explanation/index` | +If you are here mainly to run the model on recordings, +start with Tutorials. + +| Section | Best for | Start here | +| --- | --- | --- | +| Tutorials | Step-by-step routes for the most common tasks | {doc}`tutorials/index` | +| How-to guides | Answers to specific practical questions | {doc}`how_to/index` | +| Reference | Detailed command and settings help | {doc}`reference/index` | +| Understanding | Concepts, interpretation, and trade-offs | {doc}`explanation/index` | +| Legacy | Previous workflow and migration guidance | {doc}`legacy/index` | ## Get in touch - GitHub repository: [macaodha/batdetect2](https://github.com/macaodha/batdetect2) - Questions, bug reports, and feature requests: - [GitHub Issues](https://github.com/macaodha/batdetect2/issues) + [GitHub Issues](https://github.com/macaodha/batdetect2/issues) - Common questions: {doc}`faq` - Want to contribute? @@ -65,7 +89,7 @@ material, and some explain trade-offs. ## Cite this work -If you use batdetect2 in research, please cite: +If you use BatDetect2 in research, please cite: Mac Aodha, O., Martinez Balvanera, S., Damstra, E., et al. (2022). @@ -82,6 +106,7 @@ tutorials/index how_to/index reference/index explanation/index +legacy/index ``` ```{toctree} diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md index c9d4bcb..f0f0beb 100644 --- a/docs/source/reference/index.md +++ b/docs/source/reference/index.md @@ -1,12 +1,20 @@ # Reference documentation -Reference pages provide factual, complete descriptions of commands, -configuration, and data structures. +Reference pages are the detailed lookup pages. + +Use this section when you need exact command options, setting names, output details, or Python API entries. ```{toctree} :maxdepth: 1 cli/index +api +app-config +inference-config +evaluation-config +outputs-config +output-formats +output-transforms data-sources preprocessing-config postprocess-config diff --git a/docs/source/tutorials/index.md b/docs/source/tutorials/index.md index 83fedc4..a183e45 100644 --- a/docs/source/tutorials/index.md +++ b/docs/source/tutorials/index.md @@ -1,7 +1,12 @@ # Tutorials -Tutorials are for learning by doing. They provide a single, reproducible path -to a concrete outcome. +Tutorials are the default learning path. + +Each tutorial follows one recommended route from start to finish. + +Use tutorials when you want the simplest route to a concrete outcome. + +Use {doc}`../how_to/index` when you need to customize a workflow. ```{toctree} :maxdepth: 1