kitzeslab · sammlapp · Oct 28, 2024 · Oct 28, 2024 · Oct 28, 2024 · Nov 3, 2024
diff --git a/.gitignore b/.gitignore
@@ -16,8 +16,8 @@ lightning_logs/
 docs/tutorials/*.ckpt
 docs/tutorials/BirdNET*
 docs/tutorials/*.WAV
-docs/tutorials/*.csv
-
+docs/tutorials/ruffed_grouse_validation_set
+docs/tutorials/great_plains_toad_dataset
 docs/tutorials/annotation_Files.zip
 docs/tutorials/mp3_Files.zip
 docs/tutorials/rana_sierrae_2022.zip

diff --git a/README.md b/README.md
@@ -95,7 +95,11 @@ Audio.from_file(path, start_timestamp=start_time,duration=audio_length)
 
 ### 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 repository that can be installed as a package and are compatible with OpenSoundscape. To install, use
-`pip install bioacoustics-model-zoo==0.12.0`
+`pip install --upgrade bioacoustics-model-zoo`
+
+To install additional dependencies for specific models, use patterns like 
+
+`pip install --upgrade bioacoustics-model-zoo[hawkears]`
 
 Load up a model and apply it to your own audio right away:
 
@@ -105,15 +109,24 @@ import bioacoustics_model_zoo as bmz
 #list available models
 print(bmz.utils.list_models())
 
-#generate class predictions and embedding vectors with Perch
-perch = bmz.Perch()
-scores = perch.predict(files)
-embeddings = perch.generate_embeddings(files)
+#generate class predictions and embedding vectors with HawkEars...
+hawkears = bmz.HawkEars()
+scores = hawkears.predict(files)
+embeddings = hawkears.embed(files)
 
-#...or BirdNET
+#...or BirdNET...
+# (you'll need ai-edge-litert in your environment, run `pip install bioacoustics-model-zoo[birdnet]`)
 birdnet = bmz.BirdNET()
 scores = birdnet.predict(files)
-embeddings = birdnet.generate_embeddings(files)
+embeddings = birdnet.embed(files)
+
+# or Perch2
+# `pip install bioacoustics-model-zoo[perch]` will install tensorflow and tensorflow-hub
+#...or BirdNET...
+# (you'll need ai-edge-litert in your environment, run `pip install bioacoustics-model-zoo[birdnet]`)
+perch2 = bmz.Perch2()
+scores = perch2.predict(files)
+embeddings = perch2.embed(files)
 ```
 
 See the tutorial notebooks for examples of training and fine-tuning models from the model zoo with your own annotations. 

diff --git a/docs/conf.py b/docs/conf.py
@@ -94,6 +94,7 @@ def setup(app):
     "librosa",
     "ray",
     "torch",
+    "torchaudio",
     "sklearn",
     "numpy",
     "schema",

diff --git a/docs/index.rst b/docs/index.rst
@@ -106,7 +106,8 @@ Suggested citation:
    tutorials/customize_cnn_training
    tutorials/preprocess_audio_dataset
    tutorials/acoustic_localization
-   tutorials/signal_processing
+   tutorials/RIBBIT_pulse_rate_demo
+   tutorials/ruffed_grouse_detector
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/tutorials/RIBBIT_pulse_rate_demo.ipynb b/docs/tutorials/RIBBIT_pulse_rate_demo.ipynb
diff --git a/docs/tutorials/predict_with_cnn.ipynb b/docs/tutorials/predict_with_cnn.ipynb
diff --git a/docs/tutorials/preprocess_audio_dataset.ipynb b/docs/tutorials/preprocess_audio_dataset.ipynb
diff --git a/docs/tutorials/ruffed_grouse_detector.ipynb b/docs/tutorials/ruffed_grouse_detector.ipynb
diff --git a/docs/tutorials/signal_processing.ipynb b/docs/tutorials/signal_processing.ipynb
diff --git a/docs/tutorials/spectrogram.ipynb b/docs/tutorials/spectrogram.ipynb
@@ -274,7 +274,7 @@
                 "\n",
                 "Using higher overlap percentages can sometimes yield better time resolution in a spectrogram, but will take more computational time to generate. \n",
                 "\n",
-                "As an alternative to specifying window overlap using `overlap_samples`, you can instead specify overlap using `overlap_fraction`.\n",
+                "As an alternative to specifying window overlap using `overlap_samples`, you can instead specify overlap using `overlap_fraction` or `hop_samples`. \n",
                 "\n",
                 "#### Spectrogram parameter tradeoffs\n",
                 "\n",

diff --git a/docs/tutorials/train_cnn.ipynb b/docs/tutorials/train_cnn.ipynb
diff --git a/docs/tutorials/training_birdnet_and_perch.ipynb b/docs/tutorials/training_birdnet_and_perch.ipynb
@@ -40,7 +40,7 @@
                 "|Link to tutorial|How to run tutorial|\n",
                 "| :- | :- |\n",
                 "| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/kitzeslab/opensoundscape/blob/master/docs/tutorials/train_cnn.ipynb) | The link opens the tutorial in Google Colab. Uncomment the \"installation\" line in the first cell to install OpenSoundscape. |\n",
-                "| [![Download via DownGit](https://img.shields.io/badge/GitHub-Download-teal?logo=github)](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/kitzeslab/opensoundscape/blob/master/docs/tutorials/train_cnn.ipynb) | The link downloads the tutorial file to your computer. Follow the [Jupyter installation instructions](https://opensoundscape.org/en/latest/installation/jupyter.html), then open the tutorial file in Jupyter. |"
+                "| [![Download via DownGit](https://img.shields.io/badge/GitHub-Download-teal?logo=github)](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/kitzeslab/opensoundscape/blob/master/docs/tutorials/train_birdnet_and_perch.ipynb) | The link downloads the tutorial file to your computer. Follow the [Jupyter installation instructions](https://opensoundscape.org/en/latest/installation/jupyter.html), then open the tutorial file in Jupyter. |"
             ]
         },
         {
@@ -73,7 +73,7 @@
         },
         {
             "cell_type": "code",
-            "execution_count": 1,
+            "execution_count": null,
             "metadata": {},
             "outputs": [
                 {
@@ -105,7 +105,7 @@
                 "%config InlineBackend.figure_format = 'retina'\n",
                 "\n",
                 "# opensoundscape transfer learning tools\n",
-                "from opensoundscape.ml.shallow_classifier import MLPClassifier, quick_fit, fit_classifier_on_embeddings\n"
+                "from opensoundscape.ml.shallow_classifier import MLPClassifier, fit_classifier_on_embeddings\n"
             ]
         },
         {
@@ -297,7 +297,7 @@
                 "\n",
                 "The BirdNET and Perch models provided in the Bioacoustics Model Zoo have a `.tf_model` attribute containing the TensorFlow inference model and a `.network` attribute containing a trainable PyTorch classification head, specifically an instance of the MLPCLassifier class. To train a custom classifier on the embeddings extracted by these models, we just need to (1) embed the training and validation samples, then (2) pass the embeddings and labels to the `.network.fit()` method. \n",
                 "\n",
-                "This is equivalent to passing the `.network` to the the `opensoundscape.ml.shallow_classifier.quick_fit()` method, so you can also experiment with generating your own classification heads (e.g. various instances of MLPClassifier) and fitting each of them on the embeddings. See the transfer learning tutorial for further examples. "
+                "This is equivalent to passing the `.network` to the the `opensoundscape.ml.shallow_classifier.fit()` method, so you can also experiment with generating your own classification heads (e.g. various instances of MLPClassifier) and fitting each of them on the embeddings. See the transfer learning tutorial for further examples. "
             ]
         },
         {
@@ -1639,7 +1639,7 @@
                 "\n",
                 "- fit_classifier_on_embeddings(): this function wraps together the embedding step with the classifier fitting step into a single operation, with support for generating augmented variations of training samples. It returns the embeddings and labels, in case you want to train additional classifiers on them\n",
                 "\n",
-                "- MLPClassifier: this class creates a neural network with one or more fully connected layers. This object can be trained by passing it to quick_fit() or fit_classifier_on_embeddings(), or by running the MLPClassifier.fit() method (equivalent to quick_fit()). The input size should match the embedding size of the embedding model, and the output size should match the number of classes your model predicts on. "
+                "- MLPClassifier: this class creates a neural network with one or more fully connected layers. This object can be trained by passing it to fit() or fit_classifier_on_embeddings(), or by running the MLPClassifier.fit() method (equivalent to fit(model)). The input size should match the embedding size of the embedding model, and the output size should match the number of classes your model predicts on. "
             ]
         }
     ],