Merge pull request #1066 from kitzeslab/develop

Release 0.11.0

.github/workflows/poetry.yml

@@ -37,33 +37,35 @@ jobs:
         run: /home/runner/.local/bin/poetry run pytest
       - name: Poetry run black check
         run: /home/runner/.local/bin/poetry run black . --check --diff
-  test_macos:
-    runs-on: macos-latest
-    strategy:
-      matrix:
-        python-version: ["3.9", "3.10", "3.11"]
-      # Ensure that all flavours are run to completion even if an other flavor failed
-      fail-fast: false
-    steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install libsndfile
-        run: brew install libsndfile
-      - name: Install ffmpeg v4
-        run: brew install ffmpeg
-      - name: Install poetry
-        run: curl -sSL https://install.python-poetry.org | python
-      - name: Poetry install
-        run: /Users/runner/.local/bin/poetry install
-      - name: Workaround for missing pytorch dependencies during poetry install
-        run: /Users/runner/.local/bin/poetry run pip install torch
-      - name: Poetry run pytest
-        run: /Users/runner/.local/bin/poetry run pytest
-      - name: Poetry run black check
-        run: /Users/runner/.local/bin/poetry run black . --check --diff
+  # temporarily disabling macos tests as they are failing due to mps out of memory errors
+  # that we can't seem to fix. - SL 2024-06-21
+  # test_macos:
+  #   runs-on: macos-latest
+  #   strategy:
+  #     matrix:
+  #       python-version: ["3.9", "3.10", "3.11"]
+  #     # Ensure that all flavours are run to completion even if an other flavor failed
+  #     fail-fast: false
+  #   steps:
+  #     - uses: actions/checkout@v2
+  #     - name: Set up Python ${{ matrix.python-version }}
+  #       uses: actions/setup-python@v2
+  #       with:
+  #         python-version: ${{ matrix.python-version }}
+  #     - name: Install libsndfile
+  #       run: brew install libsndfile
+  #     - name: Install ffmpeg v4
+  #       run: brew install ffmpeg
+  #     - name: Install poetry
+  #       run: curl -sSL https://install.python-poetry.org | python
+  #     - name: Poetry install
+  #       run: /Users/runner/.local/bin/poetry install
+  #     - name: Workaround for missing pytorch dependencies during poetry install
+  #       run: /Users/runner/.local/bin/poetry run pip install torch
+  #     - name: Poetry run pytest
+  #       run: /Users/runner/.local/bin/poetry run pytest
+  #     - name: Poetry run black check
+  #       run: /Users/runner/.local/bin/poetry run black . --check --diff
 ## ------------------------------------------------------------------------
 ## The below job installs opensoundscape on a windows machine using WSL.
 ## It is commented out, as it keeps hanging on the final step 'Poetry run pytest'

.gitignore

@@ -10,3 +10,11 @@ docs/tutorials/woodcock_labeled_data
 docs/tutorials/annotated_data
 .vscode
 docs/tutorials/wandb
+untracked/
+docs/tutorials/rana_sierrae_2022
+lightning_logs/
+docs/tutorials/*.ckpt
+docs/tutorials/BirdNET*
+docs/tutorials/*.WAV
+docs/tutorials/*.csv
+

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/psf/black
-    rev: 22.8.0
+    rev: 24.8.0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python

README.md

@@ -9,8 +9,9 @@ OpenSoundscape includes utilities which can be strung together to create data an
 
 * load and manipulate audio files
 * create and manipulate spectrograms
-* train convolutional neural networks (CNNs) on spectrograms with PyTorch
+* train deep learning models to recognize sounds
 * run pre-trained CNNs to detect vocalizations
+* tune pre-trained CNNs to custom classification tasks
 * detect periodic vocalizations with RIBBIT
 * load and manipulate Raven annotations
 * estimate the location of sound sources from synchronized recordings
@@ -49,7 +50,7 @@ Details about installation are available on the OpenSoundscape documentation at
 
 #### How do I install OpenSoundscape?
 
-* Most users should install OpenSoundscape via pip, preferably within a virtual environment: `pip install opensoundscape==0.10.2`. 
+* Most users should install OpenSoundscape via pip, preferably within a virtual environment: `pip install opensoundscape==0.11.0`. 
 * To use OpenSoundscape in Jupyter Notebooks (e.g. for tutorials), follow the installation instructions for your operating system, then follow the "Jupyter" instructions.
 * Contributors and advanced users can also use Poetry to install OpenSoundscape using the "Contributor" instructions
 
@@ -61,7 +62,7 @@ Details about installation are available on the OpenSoundscape documentation at
 * Most computer cluster users should follow the Linux installation instructions
 
 
-### Use Audio and Spectrogram classes
+### Use Audio and Spectrogram classes to inspect audio data
 ```python
 from opensoundscape import Audio, Spectrogram
 
@@ -85,7 +86,27 @@ path = '/path/to/audiomoth_file.WAV' #an AudioMoth recording
 Audio.from_file(path, start_timestamp=start_time,duration=audio_length)
 ```
 
-### Use a pre-trained CNN to make predictions on long audio files
+### Load and use a model from the Bioacoustics Model Zoo
+The [Bioacoustics Model Zoo](https://github.com/kitzeslab/bioacoustics-model-zoo) hosts models in a respository that can be accessed via `torch.hub` and are compatible with OpenSoundscape. Load up a model and apply it to your own audio right away:
+
+```python
+from opensoundscape.ml import bioacoustics_model_zoo as bmz
+
+#list available models
+print(bmz.list_models())
+
+#generate class predictions and embedding vectors with Perch
+perch = bmz.load("Perch")
+scores = perch.predict(files)
+embeddings = perch.generate_embeddings(files)
+
+#...or BirdNET
+birdnet = bmz.load("BirdNET")
+scores = birdnet.predict(files)
+embeddings = birdnet.generate_embeddings(files)
+```
+
+### Load a pre-trained CNN from a local file, and make predictions on long audio files
 ```python
 from opensoundscape import load_model
 
@@ -113,7 +134,7 @@ all_annotations = BoxedAnnotations.from_raven_files(raven_file_paths,audio_file_
 class_list = ['IBWO','BLJA']
 
 # create labels for fixed-duration (2 second) clips 
-labels = all_annotations.one_hot_clip_labels(
+labels = all_annotations.clip_labels(
   cip_duration=2,
   clip_overlap=0,
   min_label_overlap=0.25,
@@ -125,20 +146,25 @@ train_df, validation_df = train_test_split(labels, test_size=0.3)
 
 # create a CNN and train on the labeled data
 model = CNN(architecture='resnet18', sample_duration=2, classes=class_list)
+
+# train the model to recognize the classes of interest in audio data
 model.train(train_df, validation_df, epochs=20, num_workers=8, batch_size=256)
 ```
 
-### Train a CNN with labeled audio data (one label per audio file):
+### Train a custom classifier on BirdNET or Perch embeddings
+
 ```python
-from opensoundscape import CNN
-from sklearn.model_selection import train_test_split
+from opensoundscape.ml import bioacoustics_model_zoo as bmz
 
-#load a DataFrame of one-hot audio clip labels
-df = pd.read_csv('my_labels.csv') #index: paths; columns: classes
-train_df, validation_df = train_test_split(df,test_size=0.2)
+# load a model from the model zoo
+model = bmz.load('BirdNET') #or bmz.load('Perch')
 
-#create a CNN and train on 2-second spectrograms for 20 epochs
-model = CNN('resnet18', classes=df.columns, sample_duration=2.0)
-model.train(train_df, validation_df, epochs=20)
-#the best model is automatically saved to a file `./best.model`
-```
+# define classes for your custom classifier
+model.change_classes(train_df.columns)
+
+# fit the trainable PyTorch classifier on your labels
+model.train(train_df,val_df,num_augmentation_variants=4,batch_size=64)
+
+# run inference using your custom classifier on audio data
+model.predict(audio_files)
+```

docs/classifier_guide/guide.md

@@ -15,7 +15,7 @@ Fig. 1. A ~15 s spectrogram containing the songs of six bird species. Some examp
 ## Kinds of classifiers 
 Many different types of classifiers for sound exist, but we typically use something called a **Convolutional Neural Network**, or **"CNN"** for short. This is a type of classifier created using machine learning. This type of classifier uses spectrograms to assign a score to sound clips based on how confident it is that a sound clip belongs in one of the classes it has been trained to recognize. CNNs can have any number of desired classes which can range from all the vocalizations produced by a bird species, to specific vocalizations of a bird species, to sounds such as gunshots. Fig. 1 could represent all of the classes in an example CNN.
 
-CNNs are not the only solution, nor the best solution to sound classification in every case. CNNs work best when a sound is relatively complex like the songs of most songbirds and when sounds are highly variable or inconsistent. Some animal sounds are much more like simple, repeated pulses which are highly consistent but could be mistaken for other environmental sounds by a naive observer. For such purposes, this lab has also developed other classifiers which rely on the periodic structure of simple sounds to classify them, which we often refer to as **signal processing** algorithms. [RIBBIT](http://opensoundscape.org/en/latest/tutorials/RIBBIT_pulse_rate_demo.html) (which stands for "Repeat-Interval Based Bioacoustic Identification Tool") is one of these classifiers which can be used for animals such as certain frogs (see Fig. 2 below for an example). Another was created specifically to classify the accelerating pulses of Ruffed Grouse drums <a href="https://doi.org/10.1002/wsb.1395" target="_blank"> (Lapp <em>et al.</em> 2022 <em>Wildl.Soc. Bull.</em>  e1395)</a>. This document focuses on the training of CNNs, but be aware that signal processing algorithms are options for sound classification.
+CNNs are not the only solution, nor the best solution to sound classification in every case. CNNs work best when a sound is relatively complex like the songs of most songbirds and when sounds are highly variable or inconsistent. Some animal sounds are much more like simple, repeated pulses which are highly consistent but could be mistaken for other environmental sounds by a naive observer. For such purposes, this lab has also developed other classifiers which rely on the periodic structure of simple sounds to classify them, which we often refer to as **signal processing** algorithms. [RIBBIT](http://opensoundscape.org/en/latest/tutorials/signal_processing.html) (which stands for "Repeat-Interval Based Bioacoustic Identification Tool") is one of these classifiers which can be used for animals such as certain frogs (see Fig. 2 below for an example). Another was created specifically to classify the accelerating pulses of Ruffed Grouse drums <a href="https://doi.org/10.1002/wsb.1395" target="_blank"> (Lapp <em>et al.</em> 2022 <em>Wildl.Soc. Bull.</em>  e1395)</a>. This document focuses on the training of CNNs, but be aware that signal processing algorithms are options for sound classification.
 
 ![](./media/image17.png)
 

docs/conf.py

@@ -11,11 +11,11 @@
 import os
 import sys
 
-# local import for linking to GitHub source code
-from sphinx_linkcode import make_linkcode_resolve
-
 sys.path.insert(0, os.path.abspath("../"))
 
+# local import for linking to GitHub source code
+from docs.sphinx_linkcode import make_linkcode_resolve
+
 
 # -- Project information -----------------------------------------------------
 
@@ -24,7 +24,7 @@
 author = "Sam Lapp, Tessa Rhinehart, Louis Freeland-Haynes, Jatin Khilnani, Alexandra Syunkova, Leonardo Viotti, Santiago Ruiz Guzman, Justin Kitzes"
 
 # The full version, including alpha/beta/rc tags
-release = "0.10.2"
+release = "0.11.0"
 
 
 # -- General configuration ---------------------------------------------------
@@ -107,10 +107,14 @@ def setup(app):
     "wandb",
     "pytorch_grad_cam",
     "aru_metadata_parser",
+    "crowsetta",
     "pytz",
     "pillow",
     "PIL",
     "tqdm",
+    "noisereduce",
+    "torchmetrics",
+    "lightning",
 ]
 
 master_doc = "index"