docs: expand inference tutorial examples and model selection guidance

docs/source/how_to/choose-a-model.md

@@ -0,0 +1,112 @@
+# How to choose a model
+
+Use this guide when you want to choose which model checkpoint BatDetect2 loads.
+
+You can choose a model in both the CLI and the Python API.
+
+## Where you can choose the model
+
+In the CLI, use `--model` with commands that load a checkpoint, including:
+
+- `batdetect2 process`
+- `batdetect2 evaluate`
+- `batdetect2 train`
+- `batdetect2 finetune`
+
+In Python, pass the model source to `BatDetect2API.from_checkpoint(...)`.
+
+If you do not choose a model, BatDetect2 uses the built-in default UK model.
+
+## Use a local checkpoint path
+
+Use a local path when you already have a checkpoint file on disk.
+
+CLI example:
+
+```bash
+batdetect2 process directory \
+    path/to/audio \
+    path/to/outputs \
+    --model path/to/model.ckpt
+```
+
+Python example:
+
+```python
+from batdetect2.api_v2 import BatDetect2API
+
+api = BatDetect2API.from_checkpoint("path/to/model.ckpt")
+```
+
+## Use a bundled checkpoint alias
+
+BatDetect2 also supports bundled checkpoint aliases.
+
+The built-in UK model is available as `uk_same`.
+The alias `batdetect2_uk_same` also works.
+
+CLI example:
+
+```bash
+batdetect2 process directory \
+    path/to/audio \
+    path/to/outputs \
+    --model uk_same
+```
+
+Python example:
+
+```python
+from batdetect2.api_v2 import BatDetect2API
+
+api = BatDetect2API.from_checkpoint("uk_same")
+```
+
+## Use a Hugging Face URI
+
+You can also load a checkpoint from Hugging Face with a URI like:
+
+```text
+hf://owner/repo/path/to/model.ckpt
+```
+
+This needs the optional Hugging Face dependency to be installed.
+For example, install it with `pip install batdetect2[huggingface]`.
+
+CLI example:
+
+```bash
+batdetect2 process directory \
+    path/to/audio \
+    path/to/outputs \
+    --model hf://owner/repo/path/to/model.ckpt
+```
+
+Python example:
+
+```python
+from batdetect2.api_v2 import BatDetect2API
+
+api = BatDetect2API.from_checkpoint(
+    "hf://owner/repo/path/to/model.ckpt"
+)
+```
+
+## Choose the right source
+
+- Use a local path when you already have a checkpoint file.
+- Use an alias when you want one of the bundled models.
+- Use a Hugging Face URI when the checkpoint lives in a Hugging Face repo.
+
+## Related pages
+
+- Run inference on a folder:
+  {doc}`../tutorials/run-inference-on-folder`
+- `BatDetect2API` reference:
+  {doc}`../reference/api`
+- Process command reference:
+  {doc}`../reference/cli/predict`
+- Train a custom model:
+  {doc}`../tutorials/train-a-custom-model`
+- Fine-tune from a checkpoint:
+  {doc}`fine-tune-from-a-checkpoint`

docs/source/how_to/index.md

@@ -1,12 +1,15 @@
 # How-to Guides
 
-How-to guides help you answer practical questions once you are past the first tutorial.
+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.
+Use this section when you already know the basic workflow and want help with one
+specific task.
 
 ```{toctree}
 :maxdepth: 1
 
+choose-a-model
 choose-an-inference-input-mode
 run-batch-predictions
 tune-inference-clipping

docs/source/tutorials/run-inference-on-folder.md

@@ -1,120 +1,217 @@
-# Tutorial: Run BatDetect2 on a folder of audio files
+# Run BatDetect2 on a folder of audio files
 
-This tutorial walks through a first end-to-end inference run with the CLI.
+This tutorial shows how to run BatDetect2 on a folder of recordings from the command line.
 
-It is the default starting point for new users.
+Use it when you want a first pass over a folder of audio recordings and want to see what BatDetect2 finds.
 
-Use it when you want to run an existing model on a folder of recordings and
+If you want to follow the tutorial exactly, you can use the example recordings that come with the repository.
-quickly check what BatDetect2 found.
 
 ## Before you start
 
-- BatDetect2 installed in your environment.
+You need:
-- A folder containing `.wav` files.
-- A model checkpoint path.
 
-A checkpoint is the saved model file that BatDetect2 uses to make predictions.
+- BatDetect2 installed.
+- A folder containing supported audio files.
+- A place to save the results.
 
-If you are working from this repository checkout, you can use:
+If you have not installed BatDetect2 yet, start with {doc}`../getting_started`.
 
-```text
+## Optional: use the repository example files
-src/batdetect2/models/checkpoints/Net2DFast_UK_same.pth.tar
+
+If you want to follow the steps with the same paths shown here, clone the repository and move into it:
+
+```bash
+git clone https://github.com/macaodha/batdetect2.git
+cd batdetect2
 ```
 
-## Outcome
+Then you can use these example paths from the repository root.
+
+## What you will do
 
 By the end of this tutorial you will have:
 
 - run `batdetect2 process directory`,
 - saved predictions to disk,
-- checked that BatDetect2 wrote output files,
+- checked that BatDetect2 wrote the files you expected,
-- identified the next pages to use for tuning or customization.
+- tried a second run with a higher detection threshold,
+- identified the next pages to use if you want to customise the run.
 
-## 1. Choose your input and output paths
+## 1. Choose your input and output folders
 
-Pick three paths:
+Pick:
 
-- the checkpoint to use,
+- the folder containing your audio files,
-- the directory containing your audio files,
+- an output folder where BatDetect2 should save results.
-- an output directory where BatDetect2 will save its results.
 
 Example layout:
 
 ```text
 project/
-  model.pth.tar
   audio/
     file_001.wav
     file_002.wav
   outputs/
 ```
 
-## 2. Run processing on the directory
+If `outputs/` does not exist yet, that is fine.
+BatDetect2 can create it.
 
-Use this command when you want BatDetect2 to scan a folder of recordings
+If you are using the repository example files, your layout already looks like this:
-automatically.
+
+```text
+batdetect2/
+  example_data/
+    audio/
+      20170701_213954-MYOMYS-LR_0_0.5.wav
+      20180530_213516-EPTSER-LR_0_0.5.wav
+      20180627_215323-RHIFER-LR_0_0.5.wav
+```
+
+## 2. Run BatDetect2 on the folder
+
+For a first run, use the built-in default UK model:
 
 ```bash
 batdetect2 process directory \
-  path/to/model.pth.tar \
+  path/to/audio \
-  path/to/audio_dir \
   path/to/outputs
 ```
 
+If you are using the repository example files, run:
+
+```bash
+batdetect2 process directory \
+  example_data/audio \
+  example_outputs/first_run
+```
+
 What this does:
 
-- loads the checkpoint,
+- looks for supported audio files in `path/to/audio`,
-- finds audio files in `audio_dir`,
+- runs the model on each recording,
-- splits recordings into smaller pieces internally when needed,
+- saves the results in `path/to/outputs`.
-- saves result files to `outputs`.
 
-## 3. Verify that outputs were written
+You do not need to choose a model for this first run.
+If you do nothing, BatDetect2 uses the built-in default UK model.
 
-After the command completes, inspect the output directory.
+If you want to use a different model later, see {doc}`../how_to/choose-a-model`.
 
-For a first run, the important check is simple:
+## 3. Check the output files
 
-- did BatDetect2 create result files,
+After the command finishes, look in your output folder.
-- are they in the output directory you expected,
-- did it process the recordings you meant to analyze.
 
-Different workflows can save results in different file formats.
+By default, the CLI writes predictions in the `batdetect2` output format.
+This is a JSON-based format used for BatDetect2-style outputs.
 
-You do not need to learn those details for the first run.
+With the default settings, you will usually see one `.json` file and one `_detections.csv` file per recording.
 
-If you later need to choose a specific output format, go to
+For the repository example run, that means files like:
-{doc}`../how_to/save-predictions-in-different-output-formats`.
 
-## 4. Inspect predictions
+```text
+example_outputs/first_run/
+  20170701_213954-MYOMYS-LR_0_0.5.wav.json
+  20170701_213954-MYOMYS-LR_0_0.5.wav_detections.csv
+  20180530_213516-EPTSER-LR_0_0.5.wav.json
+  20180530_213516-EPTSER-LR_0_0.5.wav_detections.csv
+  20180627_215323-RHIFER-LR_0_0.5.wav.json
+  20180627_215323-RHIFER-LR_0_0.5.wav_detections.csv
+```
 
-Start with a small subset of representative files.
+One of the JSON files will look roughly like this:
 
-Check:
+```json
+{
+  "annotated": false,
+  "annotation": [
+    {
+      "class": "Rhinolophus ferrumequinum",
+      "class_prob": 0.889,
+      "det_prob": 0.889,
+      "end_time": 0.0668,
+      "event": "Echolocation",
+      "high_freq": 84857,
+      "individual": "-1",
+      "low_freq": 67578,
+      "start_time": 0.0
+    }
+  ]
+}
+```
 
-- whether detections were written for the expected recordings,
+Very briefly:
-- whether output counts are plausible,
-- whether the model is obviously too sensitive or too conservative,
-- whether the predicted classes look broadly reasonable for your data.
 
-Do not treat the first run as validated ecological output.
+- `annotated: false` means this is a prediction file, not a reviewed annotation file.
+- `annotation` holds the list of detections.
+- Each detection includes a predicted class, detection score, class score, time bounds, and frequency bounds.
 
-The first run is a workflow check.
+For more detail, see {doc}`../explanation/interpreting-formatted-outputs`.
+If you want to save results in another format, see {doc}`../how_to/save-predictions-in-different-output-formats`.
 
-Validation comes next.
+## 4. Run the same folder with a higher threshold
 
-## 5. Tune only after you have a baseline
+If you want, you can also run the same folder again with a higher detection threshold and save that run in a separate output folder.
 
-If the first run is too noisy or misses obvious calls, tune thresholds on a
+```bash
-reviewed subset rather than changing settings blindly across the full dataset.
+batdetect2 process directory \
+    path/to/audio \
+    path/to/outputs_threshold_05 \
+    --detection-threshold 0.5
+```
 
-Use {doc}`../how_to/tune-detection-threshold` for that process.
+Concrete example:
 
-## What to do next
+```bash
+batdetect2 process directory \
+    example_data/audio \
+    example_outputs/threshold_05 \
+    --detection-threshold 0.5
+```
 
-- If you need a different input mode, use
+Keeping this in a separate folder makes it easy to compare runs later.
-  {doc}`../how_to/choose-an-inference-input-mode`.
+
-- If you want to tune sensitivity, use
+## 5. Run the model on a list of recordings
-  {doc}`../how_to/tune-detection-threshold`.
+
-- If you already write code and want more control from Python, use
+If you only want to process selected recordings, use `file_list`.
-  {doc}`integrate-with-a-python-pipeline`.
+The list file should contain one recording path per line.
-- If you need full command details, use {doc}`../reference/cli/predict`.
+
+Example `audio_files.txt`:
+
+```text
+path/to/audio/file_001.wav
+path/to/audio/file_002.wav
+path/to/audio/file_010.wav
+```
+
+Repository example:
+
+```text
+example_data/audio/20170701_213954-MYOMYS-LR_0_0.5.wav
+example_data/audio/20180530_213516-EPTSER-LR_0_0.5.wav
+```
+
+Then run:
+
+```bash
+batdetect2 process file_list \
+    path/to/audio_files.txt \
+    path/to/selected_outputs
+```
+
+Concrete example:
+
+```bash
+batdetect2 process file_list \
+    example_data/audio_files.txt \
+    example_outputs/selected_outputs
+```
+
+This is useful when your recordings are spread across folders, or when you only want to run a chosen subset.
+
+## Common next steps
+
+- If your recordings are not all in one folder, or you want to compare input modes, see {doc}`../how_to/choose-an-inference-input-mode`.
+- If you want to save results in another format, see {doc}`../how_to/save-predictions-in-different-output-formats`.
+- If you want to choose a different model, see {doc}`../how_to/choose-a-model`.
+- If you already write code and want more control from Python, see {doc}`integrate-with-a-python-pipeline`.
+- If you want the full command reference, including `--model`, see {doc}`../reference/cli/predict`.

example_data/audio_files.txt

@@ -0,0 +1,2 @@
+example_data/audio/20170701_213954-MYOMYS-LR_0_0.5.wav
+example_data/audio/20180530_213516-EPTSER-LR_0_0.5.wav