mirror of
https://github.com/macaodha/batdetect2.git
synced 2026-05-23 06:41:53 +02:00
118 lines
3.2 KiB
Markdown
118 lines
3.2 KiB
Markdown
# Home
|
|
|
|
Welcome to the BatDetect2 documentation.
|
|
|
|
## What is BatDetect2?
|
|
|
|
`batdetect2` detects bat echolocation calls in audio recordings.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
The current default model is trained for 17 UK species.
|
|
|
|
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`
|
|
- 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.
|
|
```
|
|
|
|
```{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`.
|
|
```
|
|
|
|
## How to use this site
|
|
|
|
Start with {doc}`getting_started` if you are new.
|
|
|
|
Then choose the section that matches what you need.
|
|
|
|
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)
|
|
- Common questions:
|
|
{doc}`faq`
|
|
- Want to contribute?
|
|
See {doc}`development/index`
|
|
|
|
## Cite this work
|
|
|
|
If you use BatDetect2 in research, please cite:
|
|
|
|
Mac Aodha, O., Martinez Balvanera, S., Damstra, E., et al.
|
|
(2022).
|
|
_Towards a General Approach for Bat Echolocation Detection and Classification_.
|
|
bioRxiv.
|
|
|
|
```{toctree}
|
|
:maxdepth: 1
|
|
:caption: Get Started
|
|
|
|
getting_started
|
|
faq
|
|
tutorials/index
|
|
how_to/index
|
|
reference/index
|
|
explanation/index
|
|
legacy/index
|
|
```
|
|
|
|
```{toctree}
|
|
:maxdepth: 1
|
|
:caption: Contributing
|
|
|
|
development/index
|
|
```
|