Minor documentation updates

docs/tutorials/cnn.ipynb

@@ -92,8 +92,8 @@
       "                                 Dload  Upload   Total   Spent    Left  Speed\n",
       "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\n",
       "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\n",
-      "100     7    0     7    0     0      6      0 --:--:--  0:00:01 --:--:--     0\n",
-      "100 9499k  100 9499k    0     0  4778k      0  0:00:01  0:00:01 --:--:-- 20.5M\n"
+      "100     7    0     7    0     0      5      0 --:--:--  0:00:01 --:--:--     5\n",
+      "100 9499k  100 9499k    0     0  3663k      0  0:00:02  0:00:02 --:--:-- 7642k\n"
      ]
     },
     {
@@ -468,7 +468,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -477,6 +477,16 @@
     "model = CNN('resnet18',classes=classes,sample_duration=2.0,single_target=True)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "_CAVEAT_: the default audio preprocessing in this class bandpasses spectrograms to 0-11025 Hz. If your audio has a sample rate of less than 22050 Hz, the preprocessing will raise an error because the spectrogram will not contain the expected frequencies. In this case you could change the parameters of the bandpass action, or simply disable the bandpass action:\n",
+    "```\n",
+    "model.preprocessor.pipeline.bandpass.bypass=True\n",
+    "```"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -487,7 +497,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 11,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -1980,7 +1990,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.12"
+   "version": "3.9.13"
   }
  },
  "nbformat": 4,

docs/tutorials/preprocessors.ipynb

@@ -28,7 +28,28 @@
     "\n",
     "it also uses the Dataset classes to demonstrate\n",
     "- how to load one sample per file path\n",
-    "- how to load long audio files as a series of shorter clips"
+    "- how to load long audio files as a series of shorter clips\n",
+    "\n",
+    "\n",
+    "### Modifying the preprocessor of the CNN class\n",
+    "When training a CNN model in OpenSoundscape, you will create an object of the CNN class. There are two ways to modify the preprocessing:\n",
+    "\n",
+    "1) modify the model.preprocessor directly\n",
+    "The model contains a preprocessor object that you can modify, for instance:\n",
+    "```\n",
+    "model.preprocessor.pipeline.bandpass.bypass = True\n",
+    "```\n",
+    "\n",
+    "2) overwrite the preprocessor with a new one:\n",
+    "```\n",
+    "my_preprocessor = SpectrogramPreprocessor(....) #this tutorial will help you with how to make this object\n",
+    "model.preprocessor = my_preprocessor\n",
+    "```\n",
+    "Note that if you want to create a preprocessor with overlay augmentation, it's easiest to use option 2 and initialize the preprocessor with an overlay_df. \n",
+    "\n",
+    "Note on augmentations: \n",
+    "- While training, the CNN class will use all actions in the preprocessor's pipeline. \n",
+    "- When runing validation or prediction, by default, the CNN will bypass actions with action.is_augmentation==True."
    ]
   },
   {
@@ -1087,6 +1108,26 @@
     "dataset[0]['X'].plot()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# adding the preprocessor to a CNN"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can always overwrite the preprocessor of a CNN model object with a new one:\n",
+    "```\n",
+    "my_preprocessor = SpectrogramPreprocessor(....) \n",
+    "...\n",
+    "model.preprocessor = my_preprocessor\n",
+    "```\n",
+    "_WARNING_: Be careful! If your new preprocessor has a different sample duration (eg 3 seconds instead of 2) or shape (eg [100,100,3] instead of [224,224,1]), these new values will also take effect when using the CNN. "
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

opensoundscape/ribbit.py

@@ -106,7 +106,7 @@ def ribbit(
         plot=False: if True, plot the power spectral density for each clip
 
     Returns:
-        DataFrame of index=('start_time','end_time'), columns=['score'],
+        DataFrame with columns ['start_time','end_time','score'],
         with a row for each clip.
 
     Notes

opensoundscape/torch/architectures/cnn_architectures.py

@@ -19,7 +19,7 @@
 Then you can initialize a model object from
 `opensoundscape.torch.models.cnn` with your architecture:
 
-`model=PytorchModel(my_arch,classes)`
+`model=CNN(my_arch,classes,sample_duration)`
 
 or override an existing model's architecture:
 
@@ -28,8 +28,6 @@
 Note: the InceptionV3 architecture must be used differently than other
 architectures - the easiest way is to simply use the InceptionV3 class in
 opensoundscape.torch.models.cnn.
-
-Note 2: For resnet architectures, if num_channels != 3, averages the conv1 weights across all channels.
 """
 from torchvision import models
 from torch import nn

tests/test_cnn.py

@@ -180,7 +180,7 @@ def test_train_predict_inception(train_df):
 
 
 def test_train_predict_architecture(train_df):
-    """test passing a specific architecture to PytorchModel"""
+    """test passing architecture object to CNN class"""
     arch = alexnet(2, use_pretrained=False)
     model = cnn.CNN(arch, [0, 1], sample_duration=2)
     model.train(