Merge pull request #5 from alasdairwilson/add_timeseries

Add timeseries

docs/tutorial/index.rst

@@ -89,8 +89,27 @@ All of these functions also work with `RippleImageSeries` objects, e.g.
     series.images[0].plot()
     plt.show()
 
+Note, here we have passed the overwrite keyword since those contour methods already exist.
+
 For a more detailed explanation of how to use these functions, see the :ref:`reference` section.
 
+Visualising an Image Series
+****************************
+
+We have multiple methods attached to rimg and rimgs that help visualise the interface.
+
+First we can produce animated .gif files easily:
+
+.. code-block:: python
+
+    series.animate("example_series.gif")
+
+We can also produce a timeseries plot of any of the contours in our series:
+
+.. code-block:: python
+
+    series.timeseries("Upper Boundary")
+
 Saving and loading data
 ************************
 

examples/visualisation/plotting_a_timeseries.py

@@ -0,0 +1,46 @@
+"""
+===================================
+Plotting a timeseries of a contour
+===================================
+
+A RippleImageSeries is simply a container class for a list of RippleImages.
+
+This example demonstrates how to plot a RippleImageSeries using inbuilt plotting methods.
+"""
+
+from matplotlib import pyplot as plt
+
+from ripplemapper.analyse import (add_a_star_contours, add_boundary_contours,
+                                  add_chan_vese_contours)
+from ripplemapper.classes import RippleImageSeries
+from ripplemapper.data.example import example_dir
+from ripplemapper.io import load_dir_to_obj
+
+#################################################################
+#
+# We can create a list of RippleImages from a list of image files.
+# In this example we use the load_dir_to_obj method to load all images in a directory into RippleImage objects.
+#
+# Passing this list to the RippleImageSeries constructor will create a RippleImageSeries object.
+
+ripple_images = load_dir_to_obj(example_dir)
+series = RippleImageSeries(ripple_images)
+add_boundary_contours(series, sigma=2)
+add_a_star_contours(series)
+add_chan_vese_contours(series)
+
+#################################################################
+#
+# We can plot a timeseries of this object, showing how the same contour evolves over time.
+#
+# We can refer to the contour via index:
+
+series.timeseries(1)
+plt.show()
+
+#################################################################
+#
+# or via the method name:
+
+series.timeseries('A* traversal')
+plt.show()

ripplemapper/analyse.py

@@ -20,6 +20,7 @@ def add_boundary_contours(ripple_images: list[RippleImage] | RippleImage | Rippl
         ripple_images = [ripple_images]
     for ripple_image in ripple_images:
         if len(ripple_image.contours) > 0:
+            # TODO: refactor to use new get_contour method
             indexes = []
             for i in range(len(ripple_image.contours)):
                 if ripple_image.contours[i].method == 'Upper Boundary':
@@ -57,6 +58,7 @@ def add_a_star_contours(ripple_images: list[RippleImage] | RippleImage | RippleI
         if len(ripple_image.contours) < 2:
             warnings.warn(f"RippleImage object must have at least two contours, skipping image: {ripple_image.source_file}")
             continue
+        # TODO: refactor to use new get_contour method
         methods = [contour.method for contour in ripple_image.contours]
         if 'A* traversal' in methods:
             if overwrite:
@@ -92,6 +94,7 @@ def add_chan_vese_contours(ripple_images: list[RippleImage] | RippleImage | Ripp
         ripple_images = [ripple_images]
     for ripple_image in ripple_images:
         if len(ripple_image.contours) > 0:
+            # TODO: refactor to use new get_contour method
             methods = [contour.method for contour in ripple_image.contours]
             if 'Chan-Vese' in methods:
                 if overwrite:

ripplemapper/classes.py

@@ -11,7 +11,8 @@
 from ripplemapper.contour import smooth_bumps
 from ripplemapper.image import preprocess_image
 from ripplemapper.io import load_image
-from ripplemapper.visualisation import plot_contours, plot_image
+from ripplemapper.visualisation import (plot_contours, plot_image,
+                                        plot_timeseries)
 
 __all__ = ['RippleContour', 'RippleImage', 'RippleImageSeries']
 
@@ -100,6 +101,18 @@ def add_contour(self, *args):
         contour = RippleContour(*args, image=self)
         self.contours.append(contour)
 
+    def get_contour(self, contour: str | int):
+        """Return a given contour for the image."""
+        if isinstance(contour, int):
+            return self.contours[contour]
+        elif isinstance(contour, str):
+            for cont in self.contours:
+                if contour.lower() in cont.method.lower():
+                    return cont
+        else:
+            raise ValueError("Invalid input, expected an integer or method string")
+
+
     def smooth_contours(self, **kwargs):
         """Smooth all the contours in the image."""
         self.contours = [contour.smooth(**kwargs) for contour in self.contours]
@@ -194,6 +207,13 @@ def save(self, fname: str = False, save_image_data: bool = False):
             image.save(fname=image_fname, save_image_data=save_image_data)
         return fname
 
+    def timeseries(self, contour: str | int = 0, **kwargs):
+        """Plot a timeseries of the same contour."""
+        contours = [img.get_contour(contour) for img in self.images]
+        labels = [img.source_file.split('/')[-1] for img in self.images]
+        plot_timeseries(contours, labels)
+
+
     def _load(self, file: str):
         """Load the image series from a file."""
         with gzip.open(file, 'rb') as f:

ripplemapper/tests/test_class_methods.py

@@ -3,9 +3,20 @@
 import matplotlib.pyplot as plt
 import pytest
 
+from ripplemapper.analyse import add_boundary_contours
 from ripplemapper.classes import RippleContour
 
 
+def test_get_contour_index(loaded_example_image_with_contours):
+    contour = loaded_example_image_with_contours.get_contour(0)
+    assert contour is not None
+
+def test_get_contour_method(loaded_example_image_with_contours):
+    method = "Lower Boundary"
+    contour = loaded_example_image_with_contours.get_contour(method)
+    assert contour is not None
+    assert contour.method == method
+
 def test_ripple_contour_to_physical(loaded_example_contour):
     # Assuming the function is not yet implemented
     loaded_example_contour.to_physical()
@@ -19,6 +30,11 @@ def test_ripple_contour_plot(loaded_example_contour):
     loaded_example_contour.plot()
     plt.close()
 
+def test_timeseries_plot(loaded_example_image_series):
+    add_boundary_contours(loaded_example_image_series)
+    loaded_example_image_series.timeseries(0)
+    plt.close()
+
 def test_ripple_contour_smooth(loaded_example_contour):
     loaded_example_contour.smooth()
     # Assuming the smooth function does not return anything but modifies in place

ripplemapper/visualisation.py

@@ -3,6 +3,7 @@
 import matplotlib.pyplot as plt
 import numpy as np
 
+__all__ = ['plot_contours', 'plot_image', 'plot_timeseries']
 
 def plot_contours(ripple_contours, *args, **kwargs):
     """Plot the contour."""
@@ -56,3 +57,11 @@ def plot_image(ripple_image, include_contours: bool=True, cmap: str='gray',  **k
         for contour in ripple_image.contours:
             plt.plot(contour.values[:][1], contour.values[:][0], label=contour.method)
         plt.legend()
+
+
+def plot_timeseries(contours, labels, **kwargs):
+    """Plot a timeseries of contours."""
+    for i, contour in enumerate(contours):
+        plt.plot(contour.values[1], contour.values[0], label=labels[i], **kwargs)
+    plt.gca().invert_yaxis()
+    plt.legend()