Merge pull request #418 from Living-with-machines/rw_docs

Update instructions for worked examples

docs/source/Worked-examples/Worked-examples.rst

@@ -4,6 +4,18 @@ Worked Examples
 We have provided a number of worked examples to demonstrate how to use MapReader.
 These examples can be found in the `worked_examples <https://github.com/Living-with-machines/MapReader/tree/main/worked_examples>`_ directory of the repository.
 
+To run these, you will need to clone the MapReader repository and open the notebooks located in the `worked_examples` directory.
+This can be done by running the following commands in your terminal:
+
+.. code-block:: bash
+
+   git clone https://github.com/Living-with-machines/MapReader.git
+   cd MapReader/worked_examples/
+   jupyter notebook
+
+.. note:: Make sure you set your notebook kernel to use your MapReader environment!
+
+
 Geospatial images: Maps and earth observation imagery
 -----------------------------------------------------
 
@@ -21,12 +33,35 @@ Both examples demonstrate how to use MapReader with maps hosted on a tileserver.
 
 Our examples show a full end-to-end use of the MapReader pipeline, including downloading, loading and patchifying map images, annotating patches to create training data, training a model and using the model to classify patches.
 
-The first examples demonstrates how to use MapReader to classify patches using a standard patch-level classification model in which patches are used as inputs to the model.
+The ``classification_one_inch_maps`` example demonstrates how to use MapReader to classify patches using a standard patch-level classification model in which patches are used as inputs to the model.
 It can be found `here <https://github.com/Living-with-machines/MapReader/blob/main/worked_examples/geospatial/classification_one_inch_maps/Pipeline.ipynb>`__.
 
-The second example demonstrates how to use MapReader to classify patches using a context-level classification model in which patches and their surrounding patches (i.e. context) are used as inputs to the model.
+The ``context_classification_one_inch_maps`` example demonstrates how to use MapReader to classify patches using a context-level classification model in which patches and their surrounding patches (i.e. context) are used as inputs to the model.
 It can be found `here <https://github.com/Living-with-machines/MapReader/blob/main/worked_examples/geospatial/context_classification_one_inch_maps/Pipeline.ipynb>`__.
 
+
+Annotation examples
+~~~~~~~~~~~~~~~~~~~
+
+Alongside the classification examples, we have provided two worked examples of how to use our annotator.
+
+The ``how-to-annotate-patches`` example demonstrates how to use the annotator to create training data for patch classification using OS one-inch maps. It can be found `here <https://github.com/Living-with-machines/MapReader/blob/geospatial_readme/worked_examples/geospatial/annotation_examples/how-to-annotate-patches.ipynb>`__.
+
+The ``how-to-annotate-model-predictions`` example shows how the annotator could also be used to evaluate the predictions from a classification model. It can be found `here <https://github.com/Living-with-machines/MapReader/blob/geospatial_readme/worked_examples/geospatial/annotation_examples/how-to-annotate-model-predictions.ipynb>`__.
+
+.. note::
+   The "predictions" in the second example are random values used for demonstration purposes. In reality, instead of loading in ``patch_df.csv``, you would load a ``predictions_patch_df.csv`` generated by MapReader after inference to annotate model predictions.
+
+
+Workshop notebooks
+~~~~~~~~~~~~~~~~~~
+
+In the worked examples directory, we also have a number of notebooks that were used in our workshops.
+These are **not** updated to align with the most recent version of MapReader, but instead they are dated and contain information about the MapReader version used at the time of the workshop.
+
+If you want to run one of these you will need to install the version of MapReader that was used at the time of the workshop.
+
+
 Non-geospatial images
 ---------------------
 
@@ -40,7 +75,7 @@ Classification of plant phenotypes
    :width: 400px
    :target: https://github.com/Living-with-machines/MapReader/blob/main/worked_examples/non-geospatial/classification_plant_phenotype/Pipeline.ipynb
 
-In our plant phenotypes example, we demonstrate how to use MapReader to classify plant phenotypes in images of plants.
+In our ``classification_plant_phenotype`` example, we demonstrate how to use MapReader to classify plant phenotypes in images of plants.
 Importantly, this worked example demonstrates how to use MapReader with non-georeferenced images (e.g. non-georeferenced map images).
 It can be found `here <https://github.com/Living-with-machines/MapReader/blob/main/worked_examples/non-geospatial/classification_plant_phenotype/Pipeline.ipynb>`__.
 
@@ -51,6 +86,6 @@ Classification of MNIST digits
    :width: 400px
    :target: https://github.com/Living-with-machines/MapReader/blob/main/worked_examples/non-geospatial/classification_mnist/Pipeline.ipynb
 
-In our MNIST example, we demonstrate how to use MapReader to classify MNIST digits.
+In our ``classification_mnist`` example, we demonstrate how to use MapReader to classify MNIST digits.
 Importantly, this example demonstrates how to use MapReader to classify whole images instead of patches and therefore how MapReader can generalize to much broader use cases.
 It can be found `here <https://github.com/Living-with-machines/MapReader/blob/main/worked_examples/non-geospatial/classification_mnist/Pipeline.ipynb>`__.