Merge pull request #966 from kitzeslab/docs

Add "Classifiers 101" to documentation
kitzeslab · Mar 25, 2024 · 379952a · 379952a
2 parents cf77a56 + 5d39aa7
commit 379952a
Show file tree

Hide file tree

Showing 87 changed files with 433 additions and 14 deletions.
diff --git a/README.md b/README.md
@@ -1,3 +1,5 @@
+# OpenSoundscape
+
 [![CI Status](https://github.com/kitzeslab/opensoundscape/workflows/CI/badge.svg)](https://github.com/kitzeslab/opensoundscape/actions?query=workflow%3ACI)
 [![Documentation Status](https://readthedocs.org/projects/opensoundscape/badge/?version=latest)](http://opensoundscape.org/en/latest/?badge=latest)
 
@@ -14,7 +16,7 @@ OpenSoundscape includes utilities which can be strung together to create data an
 * estimate the location of sound sources from synchronized recordings
 
 
-OpenSoundscape's source code can be found on [GitHub] (https://github.com/kitzeslab/opensoundscape) and its documentation can be found on [OpenSoundscape.org](https://opensoundscape.org).
+OpenSoundscape's documentation can be found on [OpenSoundscape.org](https://opensoundscape.org).
 
 ## Show me the code!
 

diff --git a/docs/classifier_guide/guide.md b/docs/classifier_guide/guide.md
diff --git a/docs/classifier_guide/media/F0.png b/docs/classifier_guide/media/F0.png
diff --git a/docs/classifier_guide/media/F1.png b/docs/classifier_guide/media/F1.png
diff --git a/docs/classifier_guide/media/F10.png b/docs/classifier_guide/media/F10.png
diff --git a/docs/classifier_guide/media/F10A.png b/docs/classifier_guide/media/F10A.png
diff --git a/docs/classifier_guide/media/F11.png b/docs/classifier_guide/media/F11.png
diff --git a/docs/classifier_guide/media/F11A.png b/docs/classifier_guide/media/F11A.png
diff --git a/docs/classifier_guide/media/F12.png b/docs/classifier_guide/media/F12.png
diff --git a/docs/classifier_guide/media/F12A.png b/docs/classifier_guide/media/F12A.png
diff --git a/docs/classifier_guide/media/F13.png b/docs/classifier_guide/media/F13.png
diff --git a/docs/classifier_guide/media/F13A.png b/docs/classifier_guide/media/F13A.png
diff --git a/docs/classifier_guide/media/F14.png b/docs/classifier_guide/media/F14.png
diff --git a/docs/classifier_guide/media/F15.png b/docs/classifier_guide/media/F15.png
diff --git a/docs/classifier_guide/media/F16.png b/docs/classifier_guide/media/F16.png
diff --git a/docs/classifier_guide/media/F17.png b/docs/classifier_guide/media/F17.png
diff --git a/docs/classifier_guide/media/F18.png b/docs/classifier_guide/media/F18.png
diff --git a/docs/classifier_guide/media/F19.png b/docs/classifier_guide/media/F19.png
diff --git a/docs/classifier_guide/media/F1A.png b/docs/classifier_guide/media/F1A.png
diff --git a/docs/classifier_guide/media/F2.png b/docs/classifier_guide/media/F2.png
diff --git a/docs/classifier_guide/media/F20.png b/docs/classifier_guide/media/F20.png
diff --git a/docs/classifier_guide/media/F21.png b/docs/classifier_guide/media/F21.png
diff --git a/docs/classifier_guide/media/F22.png b/docs/classifier_guide/media/F22.png
diff --git a/docs/classifier_guide/media/F23.png b/docs/classifier_guide/media/F23.png
diff --git a/docs/classifier_guide/media/F24.png b/docs/classifier_guide/media/F24.png
diff --git a/docs/classifier_guide/media/F2A.png b/docs/classifier_guide/media/F2A.png
diff --git a/docs/classifier_guide/media/F3.png b/docs/classifier_guide/media/F3.png
diff --git a/docs/classifier_guide/media/F3A.png b/docs/classifier_guide/media/F3A.png
diff --git a/docs/classifier_guide/media/F4.png b/docs/classifier_guide/media/F4.png
diff --git a/docs/classifier_guide/media/F4A.png b/docs/classifier_guide/media/F4A.png
diff --git a/docs/classifier_guide/media/F5.png b/docs/classifier_guide/media/F5.png
diff --git a/docs/classifier_guide/media/F5A.png b/docs/classifier_guide/media/F5A.png
diff --git a/docs/classifier_guide/media/F6.png b/docs/classifier_guide/media/F6.png
diff --git a/docs/classifier_guide/media/F6A.png b/docs/classifier_guide/media/F6A.png
diff --git a/docs/classifier_guide/media/F7.png b/docs/classifier_guide/media/F7.png
diff --git a/docs/classifier_guide/media/F7A.png b/docs/classifier_guide/media/F7A.png
diff --git a/docs/classifier_guide/media/F8.png b/docs/classifier_guide/media/F8.png
diff --git a/docs/classifier_guide/media/F8A.png b/docs/classifier_guide/media/F8A.png
diff --git a/docs/classifier_guide/media/F9.png b/docs/classifier_guide/media/F9.png
diff --git a/docs/classifier_guide/media/F9A.png b/docs/classifier_guide/media/F9A.png
diff --git a/docs/classifier_guide/media/image1.png b/docs/classifier_guide/media/image1.png
diff --git a/docs/classifier_guide/media/image10.png b/docs/classifier_guide/media/image10.png
diff --git a/docs/classifier_guide/media/image11.png b/docs/classifier_guide/media/image11.png
diff --git a/docs/classifier_guide/media/image12.png b/docs/classifier_guide/media/image12.png
diff --git a/docs/classifier_guide/media/image13.png b/docs/classifier_guide/media/image13.png
diff --git a/docs/classifier_guide/media/image14.png b/docs/classifier_guide/media/image14.png
diff --git a/docs/classifier_guide/media/image15.png b/docs/classifier_guide/media/image15.png
diff --git a/docs/classifier_guide/media/image16.png b/docs/classifier_guide/media/image16.png
diff --git a/docs/classifier_guide/media/image17.png b/docs/classifier_guide/media/image17.png
diff --git a/docs/classifier_guide/media/image18.png b/docs/classifier_guide/media/image18.png
diff --git a/docs/classifier_guide/media/image19.png b/docs/classifier_guide/media/image19.png
diff --git a/docs/classifier_guide/media/image2.png b/docs/classifier_guide/media/image2.png
diff --git a/docs/classifier_guide/media/image20.png b/docs/classifier_guide/media/image20.png
diff --git a/docs/classifier_guide/media/image21.png b/docs/classifier_guide/media/image21.png
diff --git a/docs/classifier_guide/media/image22.png b/docs/classifier_guide/media/image22.png
diff --git a/docs/classifier_guide/media/image23.png b/docs/classifier_guide/media/image23.png
diff --git a/docs/classifier_guide/media/image24.png b/docs/classifier_guide/media/image24.png
diff --git a/docs/classifier_guide/media/image25.png b/docs/classifier_guide/media/image25.png
diff --git a/docs/classifier_guide/media/image26.png b/docs/classifier_guide/media/image26.png
diff --git a/docs/classifier_guide/media/image27.png b/docs/classifier_guide/media/image27.png
diff --git a/docs/classifier_guide/media/image28.png b/docs/classifier_guide/media/image28.png
diff --git a/docs/classifier_guide/media/image29.png b/docs/classifier_guide/media/image29.png
diff --git a/docs/classifier_guide/media/image3.png b/docs/classifier_guide/media/image3.png
diff --git a/docs/classifier_guide/media/image30.png b/docs/classifier_guide/media/image30.png
diff --git a/docs/classifier_guide/media/image31.png b/docs/classifier_guide/media/image31.png
diff --git a/docs/classifier_guide/media/image32.png b/docs/classifier_guide/media/image32.png
diff --git a/docs/classifier_guide/media/image33.png b/docs/classifier_guide/media/image33.png
diff --git a/docs/classifier_guide/media/image34.png b/docs/classifier_guide/media/image34.png
diff --git a/docs/classifier_guide/media/image35.png b/docs/classifier_guide/media/image35.png
diff --git a/docs/classifier_guide/media/image36.png b/docs/classifier_guide/media/image36.png
diff --git a/docs/classifier_guide/media/image37.png b/docs/classifier_guide/media/image37.png
diff --git a/docs/classifier_guide/media/image38.png b/docs/classifier_guide/media/image38.png
diff --git a/docs/classifier_guide/media/image39.png b/docs/classifier_guide/media/image39.png
diff --git a/docs/classifier_guide/media/image4.png b/docs/classifier_guide/media/image4.png
diff --git a/docs/classifier_guide/media/image40.png b/docs/classifier_guide/media/image40.png
diff --git a/docs/classifier_guide/media/image41.png b/docs/classifier_guide/media/image41.png
diff --git a/docs/classifier_guide/media/image42.png b/docs/classifier_guide/media/image42.png
diff --git a/docs/classifier_guide/media/image43.png b/docs/classifier_guide/media/image43.png
diff --git a/docs/classifier_guide/media/image5.png b/docs/classifier_guide/media/image5.png
diff --git a/docs/classifier_guide/media/image6.png b/docs/classifier_guide/media/image6.png
diff --git a/docs/classifier_guide/media/image7.png b/docs/classifier_guide/media/image7.png
diff --git a/docs/classifier_guide/media/image8.png b/docs/classifier_guide/media/image8.png
diff --git a/docs/classifier_guide/media/image9.png b/docs/classifier_guide/media/image9.png
diff --git a/docs/classifier_guide/overview.md b/docs/classifier_guide/overview.md
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,6 +1,9 @@
 OpenSoundscape
 ==============
 
+.. image:: https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white
+   :target: https://github.com/kitzeslab/opensoundscape
+
 OpenSoundscape (OPSO) is free and open source Python utility library analyzing bioacoustic data. 
 
 OpenSoundscape includes utilities which can be strung together to create data analysis pipelines, including functions to:
@@ -14,9 +17,6 @@ OpenSoundscape includes utilities which can be strung together to create data an
 * estimate the location of sound sources from synchronized recordings
 
 
-OpenSoundscape's source code can be found on `GitHub <https://github.com/kitzeslab/opensoundscape>`__ and its documentation can be found on `OpenSoundscape.org <https://opensoundscape.org>`__.
-
-
 Table of Contents
 ~~~~~~~~~~~~~~~~~~
 
@@ -110,14 +110,14 @@ Suggested citation:
    :hidden:
    :caption: Classifiers 101
 
-   classifier_guide/overview
+   classifier_guide/guide.md
    classifier_guide/why_classify
    classifier_guide/data_organization
    classifier_guide/create_training_dataset
    classifier_guide/train_cnn
    classifier_guide/evaluate_cnn
    classifier_guide/retrain_cnn
-
+   
 .. toctree::
    :maxdepth: 1
    :hidden:

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,7 +1,7 @@
 sphinx>=7.2.6
 ipykernel
 nbsphinx
-docutils>=0.18.1
+docutils>=0.18.1,<0.19
 mistune<2.0.0
 sphinx-copybutton>=0.5.2
 sphinx-rtd-theme>=1.3.0

diff --git a/docs/tutorials/train_cnn.ipynb b/docs/tutorials/train_cnn.ipynb
@@ -422,11 +422,12 @@
     "## Create train, validation, and test datasets\n",
     "\n",
     "To train and test a model, we use three datasets:\n",
+    "\n",
     "* The **training dataset** is used to fit your machine learning model to the audio data. \n",
     "* The **validation dataset** is a held-out dataset that is used to select hyperparameters (e.g. how many epochs to train for) during training\n",
     "* The **test dataset** is another held-out dataset that we use to check how the model performs on data that were not available at all during training.\n",
     "\n",
-    "While both the training and validation datasets are used while trained the model, the test dataset is never touched until the model is fully trained and completed.\n",
+    "While both the training and validation datasets are used while training the model, the test dataset is never touched until the model is fully trained and completed.\n",
     "\n",
     "The training and validation datasets may be gathered from the same source as each other. In contrast, the test dataset is often gathered from a different source to assess whether the model's performance generalizes to a real-world problem. For example, training and validation data might be drawn from an online database like Xeno-Canto, whereas the testing data is from your own field data. \n",
     "\n",
@@ -1222,9 +1223,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "opso_dev",
+   "display_name": "opso-dev",
    "language": "python",
-   "name": "opso_dev"
+   "name": "opso-dev"
   },
   "language_info": {
    "codemirror_mode": {
@@ -1236,7 +1237,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.13"
+   "version": "3.9.16"
   }
  },
  "nbformat": 4,