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

Update worked example notebooks
maps-as-data · Feb 22, 2024 · 4ae6026 · 4ae6026
2 parents a429260 + 1d1ca54
commit 4ae6026
Show file tree

Hide file tree

Showing 19 changed files with 4,144 additions and 11,608 deletions.
diff --git a/docs/source/Contribution-guide/Contribution-guide.rst b/docs/source/Contribution-guide/Contribution-guide.rst
@@ -30,7 +30,7 @@ Pre-requisites
 Regardless of how you will be contributing to MapReader, you will need to:
 
 1. Ensure you have a `GitHub account <https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account>`_ set up.
-2. Be able to use GitHub issues and pull requests - if you are unfamiliar with these, please look at our :doc:`GitHub guide <Contribution-guide/GitHub-guide>` before continuing.
+2. Be able to use GitHub issues and pull requests - if you are unfamiliar with these, please look at our :doc:`GitHub guide </Contribution-guide/GitHub-guide>` before continuing.
 3. Set up a virtual python environment and install MapReader (as per our :doc:`Installation instructions </Install>`).
 4. Have read this guide.
 

diff --git a/docs/source/Developers-guide.rst b/docs/source/Developers-guide.rst
@@ -1,5 +1,5 @@
 Developer's Guide
-================
+=================
 
 Managing version numbers
 ------------------------

diff --git a/docs/source/Project-cv.rst b/docs/source/Project-cv.rst
@@ -1,5 +1,5 @@
 Project Curriculum Vitae
-===========
+=========================
 
 .. Notes to editors:
 .. 1. Add links to slides/videos (always add slides to [email protected] drive)

diff --git a/docs/source/Worked-examples/Worked-examples.rst b/docs/source/Worked-examples/Worked-examples.rst
@@ -1,26 +1,56 @@
 Worked Examples
 ================
 
-.. todo:: Explain these different use cases
-
-.. list-table::
-   :widths: 25 25 25
-   :header-rows: 0
-   :stub-columns: 0
-
-   * - **classification_one_inch_maps**
-         .. image:: https://raw.githubusercontent.com/Living-with-machines/MapReader/main/figs/tutorial_classification_one_inch_maps_001.png
-            :width: 200px
-     - **classification_plant_phenotype**
-         .. image:: https://raw.githubusercontent.com/Living-with-machines/MapReader/main/figs/tutorial_classification_plant_phenotype.png
-            :width: 200px
-     - **classification_mnist**
-         .. image:: https://raw.githubusercontent.com/Living-with-machines/MapReader/main/figs/tutorial_classification_mnist.png
-            :width: 200px
-
-.. toctree::
-   :maxdepth: 1
-
-   Classification of one-inch OS maps <one_inch_pipeline>
-   Classification of plant phenotypes <plant_pipeline>
-   Classification of mnist dataset <mnist_pipeline>
+We have provided a number of worked examples to demonstrate how to use the MapReader package.
+These examples can be found in the `worked_examples <https://github.com/Living-with-machines/MapReader/tree/main/worked_examples>`_ directory of the repository.
+
+Maps and geospatial images
+--------------------------
+
+MapReader was developed for maps and geospatial images.
+
+Classification of one-inch OS maps
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: https://raw.githubusercontent.com/Living-with-machines/MapReader/main/figs/tutorial_classification_one_inch_maps_001.png
+   :width: 400px
+   :target: https://github.com/Living-with-machines/MapReader/tree/main/worked_examples/geospatial
+
+We have provided two examples of how to use MapReader to identify railspace patches in one-inch OS maps.
+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.
+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.
+It can be found `here <https://github.com/Living-with-machines/MapReader/blob/main/worked_examples/geospatial/context_classification_one_inch_maps/Pipeline.ipynb>`__.
+
+Non-geospatial images
+---------------------
+
+MapReader can also for non-geospatial images.
+We have provided two examples of this.
+
+Classification of plant phenotypes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: https://raw.githubusercontent.com/Living-with-machines/MapReader/main/figs/tutorial_classification_plant_phenotype.png
+   :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.
+Importantly, this worked example demonstrates how to use MapReader with non-georeferenced images (e.g. non-georeferenced map images).
+It can be found `here <ttps://github.com/Living-with-machines/MapReader/blob/main/worked_examples/non-geospatial/classification_plant_phenotype/Pipeline.ipynb>`__.
+
+Classification of MNIST digits
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: https://raw.githubusercontent.com/Living-with-machines/MapReader/main/figs/tutorial_classification_mnist.png
+   :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.
+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>`__.
diff --git a/docs/source/Worked-examples/mnist_pipeline.ipynb b/docs/source/Worked-examples/mnist_pipeline.ipynb
diff --git a/docs/source/Worked-examples/one_inch_pipeline.ipynb b/docs/source/Worked-examples/one_inch_pipeline.ipynb
diff --git a/docs/source/Worked-examples/plant_pipeline.ipynb b/docs/source/Worked-examples/plant_pipeline.ipynb
diff --git a/mapreader/annotate/annotator.py b/mapreader/annotate/annotator.py
@@ -842,7 +842,7 @@ def render(self) -> None:
             else:
                 display(image.convert("RGB"))
             add_ins = []
-            if self.at[ix, "url"]:
+            if "url" in self.loc[ix].keys():
                 url = self.at[ix, "url"]
                 text = f'<p><a href="{url}" target="_blank">Click to see entire map.</a></p>'
                 add_ins += [widgets.HTML(text)]
@@ -968,7 +968,7 @@ def get_labelled_data(
             )
 
         return filtered_df[
-            self.label_col, self.patch_paths_col, "parent_id", "pixel_bounds"
+            [self.label_col, self.patch_paths_col, "parent_id", "pixel_bounds"]
         ]
 
     @property

diff --git a/mapreader/load/images.py b/mapreader/load/images.py
@@ -1189,6 +1189,9 @@ def _add_patch_to_parent(self, patch_id: str) -> None:
         """
         patch_parent = self.patches[patch_id]["parent_id"]
 
+        if patch_parent is None:
+            return
+
         if patch_parent not in self.parents.keys():
             self.load_parents(parent_ids=patch_parent)