mirror of
https://github.com/macaodha/batdetect2.git
synced 2026-04-04 15:20:19 +02:00
Improved home doc page and moved faq to docs
This commit is contained in:
mbsantiago
parent
c5b2446978
commit
ebc1f573c8
@ -113,7 +113,7 @@ Your data may differ, and as a result it is very strongly recommended that you v
|
||||
|
||||
|
||||
## FAQ
|
||||
For more information please consult our [FAQ](faq.md).
|
||||
For more information please consult our [FAQ](docs/source/faq.md).
|
||||
|
||||
|
||||
## Reference
|
||||
|
||||
@ -1,3 +1,7 @@
|
||||
---
|
||||
orphan: true
|
||||
---
|
||||
|
||||
# Documentation Architecture and Migration Plan (Phase 0)
|
||||
|
||||
This page defines the Phase 0 documentation architecture and inventory for
|
||||
|
||||
86
docs/source/faq.md
Normal file
86
docs/source/faq.md
Normal file
@ -0,0 +1,86 @@
|
||||
# FAQ
|
||||
|
||||
## Installation and setup
|
||||
|
||||
### Do I need Python knowledge to use batdetect2?
|
||||
|
||||
Not much. If you only want to run the model on your own recordings, you can
|
||||
use the CLI and follow the steps in {doc}`getting_started`.
|
||||
|
||||
Some command-line familiarity helps, but you do not need to write Python code
|
||||
for standard inference workflows.
|
||||
|
||||
### Are there plans for an R version?
|
||||
|
||||
Not currently. Output files are plain formats (for example CSV/JSON), so you
|
||||
can read and analyze them in R or other environments.
|
||||
|
||||
### I cannot get installation working. What should I do?
|
||||
|
||||
First, re-check {doc}`getting_started` and confirm your environment is active.
|
||||
If it still fails, open an issue with your OS, install method, and full error
|
||||
output: [GitHub Issues](https://github.com/macaodha/batdetect2/issues).
|
||||
|
||||
## Model behavior and performance
|
||||
|
||||
### The model does not perform well on my data
|
||||
|
||||
This usually means your data distribution differs from training data. The best
|
||||
next step is to validate on reviewed local data and then fine-tune/train on
|
||||
your own annotations if needed.
|
||||
|
||||
### The model confuses insects/noise with bats
|
||||
|
||||
This can happen, especially when recording conditions differ from training
|
||||
conditions. Threshold tuning and training with local annotations can improve
|
||||
results.
|
||||
|
||||
See {doc}`how_to/tune-detection-threshold`.
|
||||
|
||||
### The model struggles with feeding buzzes or social calls
|
||||
|
||||
This is a known limitation of available training data in some settings. If you
|
||||
have high-quality annotated examples, they are valuable for improving models.
|
||||
|
||||
### Calls in the same sequence are predicted as different species
|
||||
|
||||
batdetect2 returns per-call probabilities and does not apply heavy sequence-
|
||||
level smoothing by default. You can apply sequence-aware postprocessing in your
|
||||
own analysis workflow.
|
||||
|
||||
### Can I trust model outputs for biodiversity conclusions?
|
||||
|
||||
Use caution. Always validate model behavior on local, reviewed data before
|
||||
using outputs for ecological inference or biodiversity assessment.
|
||||
|
||||
### The pipeline is slow
|
||||
|
||||
Runtime depends on hardware and recording duration. GPU inference is often much
|
||||
faster than CPU. If files are very long, splitting them into shorter clips can
|
||||
help throughput.
|
||||
|
||||
If you need a clipping workflow, see the annotation GUI repository:
|
||||
[batdetect2_GUI](https://github.com/macaodha/batdetect2_GUI).
|
||||
|
||||
## Training and scope
|
||||
|
||||
### Can I train on my own species set?
|
||||
|
||||
Yes. You can train/fine-tune with your own annotated data and species labels.
|
||||
|
||||
### Does this work on frequency-division or zero-crossing recordings?
|
||||
|
||||
Not directly. The workflow assumes audio can be converted to spectrograms from
|
||||
the raw waveform.
|
||||
|
||||
### Can this be used for non-bat bioacoustics (for example insects or birds)?
|
||||
|
||||
Potentially yes, but expect retraining and configuration changes. Open an issue
|
||||
if you want guidance for a specific use case.
|
||||
|
||||
## Usage and licensing
|
||||
|
||||
### Can I use this for commercial purposes?
|
||||
|
||||
No. This project is currently for non-commercial use. See the repository
|
||||
license for details.
|
||||
@ -1,18 +1,83 @@
|
||||
# Home
|
||||
|
||||
Welcome.
|
||||
Welcome to the batdetect2 docs.
|
||||
|
||||
This documentation is being reorganized using the Diataxis framework.
|
||||
See the current planning and migration inventory here:
|
||||
## What is batdetect2?
|
||||
|
||||
- {doc}`documentation_plan`
|
||||
`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.
|
||||
|
||||
The current default model is trained for 17 UK species but you can also train
|
||||
new models from your own annotated data.
|
||||
|
||||
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)
|
||||
|
||||
## What you can do
|
||||
|
||||
- Run inference on your recordings and export predictions for downstream
|
||||
analysis:
|
||||
{doc}`tutorials/run-inference-on-folder`
|
||||
- Train a custom model on your own annotated data:
|
||||
{doc}`reference/cli/train`
|
||||
- Evaluate model performance on a held-out test set:
|
||||
{doc}`reference/cli/evaluate`
|
||||
- Integrate batdetect2 into Python scripts and notebooks:
|
||||
{doc}`reference/index`
|
||||
|
||||
```{warning}
|
||||
Treat outputs as model predictions, not ground truth.
|
||||
Always validate on reviewed local data before using results for ecological
|
||||
inference.
|
||||
```
|
||||
|
||||
## Where to start
|
||||
|
||||
If you are new, start with {doc}`getting_started`.
|
||||
|
||||
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`.
|
||||
|
||||
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.
|
||||
|
||||
| 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` |
|
||||
|
||||
## 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
|
||||
documentation_plan
|
||||
faq
|
||||
tutorials/index
|
||||
how_to/index
|
||||
reference/index
|
||||
@ -20,9 +85,9 @@ explanation/index
|
||||
legacy/index
|
||||
```
|
||||
|
||||
## Audience paths
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
:caption: Contributing
|
||||
|
||||
- Ecologists who want low-code workflows should start with
|
||||
{doc}`tutorials/index`.
|
||||
- Python-savvy ecologists and bioacousticians can jump to
|
||||
{doc}`how_to/index` and {doc}`reference/index`.
|
||||
development/index
|
||||
```
|
||||
|
||||
65
faq.md
65
faq.md
@ -1,65 +0,0 @@
|
||||
# BatDetect2 - FAQ
|
||||
|
||||
## Installation
|
||||
|
||||
#### Do I need to know Python to be able to use this?
|
||||
No. To simply run the code on your own data you do not need any knowledge of Python. However, a small bit of familiarity with the terminal (i.e. command line) in Windows/Linux/OSX may make things easier.
|
||||
|
||||
|
||||
#### Are there any plans for an R version?
|
||||
Currently no. All the scripts export simple `.csv` files that can be read using any programming language of choice.
|
||||
|
||||
|
||||
#### How do I install the code?
|
||||
The codebase has been tested under Windows 10, Ubuntu, and OSX. Read the instructions in the main readme to get started. If you are having problems getting it working and you feel like you have tried everything (e.g. confirming that your Anaconda Python distribution is correctly installed) feel free to open an issue on GitHub.
|
||||
|
||||
|
||||
## Performance
|
||||
|
||||
#### The model does not work very well on my data?
|
||||
Our model is based on a machine learning approach and as such if your data is very different from our training set it may not work as well. Feel free to use our annotation tools to label some of your own data and retrain the model. Even better, if you have large quantities of audio data with reliable species data that you are willing to share with the community please get in touch.
|
||||
|
||||
|
||||
#### The model is incorrectly classifying insects/noise/... as bats?
|
||||
Fine-tuning the model on your data can make a big difference. See previous answer.
|
||||
|
||||
|
||||
#### The model fails to correctly detect feeding buzzes and social calls?
|
||||
This is a limitation of our current training data. If you have such data or would be willing to label some for us please get in touch.
|
||||
|
||||
|
||||
#### Calls that are clearly belonging to the same call sequence are being predicted as coming from different species?
|
||||
Currently we do not do any sophisticated post processing on the results output by the model. We return a probability associated with each species for each call. You can use these predictions to clean up the noisy predictions for sequences of calls.
|
||||
|
||||
|
||||
#### Can I trust the model outputs?
|
||||
The models developed and shared as part of this repository should be used with caution. While they have been evaluated on held out audio data, great care should be taken when using the model outputs for any form of biodiversity assessment. Your data may differ, and as a result it is very strongly recommended that you validate the model first using data with known species to ensure that the outputs can be trusted.
|
||||
|
||||
|
||||
#### The code works well but it is slow?
|
||||
Try a different/faster computer. On a reasonably recent desktop it takes about 13 seconds (on the GPU) or 1.3 minutes (on the CPU) to process 7.5 minutes of audio. In general, we observe a factor of ~5-10 speed up using recent Nvidia GPUs compared to CPU only systems.
|
||||
|
||||
|
||||
#### My audio files are very big and as a result the code is slow.
|
||||
If your audio files are very long in duration (i.e. multiple minutes) it might be better to split them up into several smaller files. Have a look at the instructions and scripts in our annotation GUI codebase for how to crop your files into shorter ones - see [here](https://github.com/macaodha/batdetect2_GUI).
|
||||
|
||||
|
||||
## Training a new model
|
||||
|
||||
#### Can I train a model on my own bat data with different species?
|
||||
Yes. You just need to provide annotations in the correct format.
|
||||
|
||||
|
||||
#### Will this work for frequency-division or zero-crossing recordings?
|
||||
No. The code assumes that we can convert the input audio into a spectrogram.
|
||||
|
||||
|
||||
#### Will this code work for non-bat audio data e.g. insects or birds?
|
||||
In principle yes, however you may need to change some of the training hyper-parameters to ignore high frequency information when you re-train. Please open an issue on GitHub if you have a specific request.
|
||||
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
#### Can I use the code for commercial purposes or incorporate raw source code or trained models into my commercial system?
|
||||
No. This codebase is currently only for non-commercial use. See the license.
|
||||
Loading…
Reference in New Issue
Block a user