MAINT: update documentation, CI and pinned versions

.travis.yml

@@ -1,7 +1,7 @@
 language: python
 
 python:
-  - "3.5"
+  - "3.7"
   - "2.7"
 
 install:
@@ -13,5 +13,5 @@ script:
 jobs:
   include:
     - stage: "Linter"
-      python: 3.5
+      python: 3.7
       script: make lint

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.5.4] - 2021-04-27
+* Update documentation and docstrings
+* Add python 3.7 to CI
+* Update requirements.txt with new pinned versions
+
 ## [0.5.3] - 2021-04-27
 * Shorten `event.dblclick is True` to `event.dblclick` and
  `event.dblclick is False` to `not event.dblclick`

README.org

@@ -68,19 +68,30 @@ image, type
 #+begin_SRC python 
 my_roi.display_mean(image)
 #+end_SRC
+Note that you can only pass 2D images to =display_mean()=! If you have e.g.
+an RGB-image with dimension 3, you need to make the call like so:
+#+begin_SRC python
+mask = my_roi.display_mean(rgb_image[:, :, 0])
+#+end_SRC
 
 *** Extracting a binary mask image
-The function =get_mask(image)= creates a binary mask for a certain ROI
-instance, that is, a 2D numpy array of the size of the image array,
+The function =get_mask()= creates a binary mask for a certain ROI
+instance, that is, a 2D numpy array of the size of the (2D) image array,
 whose elements are =True= if they lie inside the ROI polygon,
 and =False= otherwise.
 #+begin_SRC python 
 mask = my_roi.get_mask(image)
 plt.imshow(mask) # show the binary signal mask
 #+end_SRC
 
-This mask image can be used to e.g. calculate the mean pixel intensity
-in an image over that ROI:
+Note that you can only pass 2D images to =get_mask()=, If you have e.g.
+an RGB-image with dimension 3, you need to make the call like so:
+#+begin_SRC python
+mask = my_roi.get_mask(rgb_image[:, :, 0])
+#+end_SRC
+
+The resulting mask image can then be used to e.g. calculate the mean pixel
+intensity in an image over that ROI:
 #+begin_SRC python 
 mean = plt.mean(image[mask])
 #+end_SRC

requirements.txt

@@ -1,6 +1,9 @@
 matplotlib==2.2.0; python_version < '3'
-matplotlib==3.0.3; python_version > '3'
-numpy==1.14.3
-pytest==4.0.0
-pytest-cov==2.6.0
-flake8==3.5.0
+matplotlib==3.1.3; python_version > '3'
+numpy==1.14.3; python_version < '3'
+numpy==1.18.1; python_version > '3'
+pytest==4.0.0; python_version < '3'
+pytest==5.4.3; python_version > '3'
+pytest-cov==2.6.0; python_version < '3'
+pytest-cov==2.11.1; python_version > '3'
+flake8==3.7.9

roipoly/roipoly.py

@@ -79,8 +79,22 @@ def show_figure():
         else:
             plt.show(block=True)
 
-    def get_mask(self, current_image):
-        ny, nx = np.shape(current_image)
+    def get_mask(self, image):
+        """Get binary mask of the ROI polygon.
+
+        Parameters
+        ----------
+        image: numpy array (2D)
+            Image that the mask should be based on. Only used for determining
+            the shape of the binary mask (which is made equal to the shape of
+            the image)
+
+        Returns
+        -------
+        numpy array (2D)
+
+        """
+        ny, nx = np.shape(image)
         poly_verts = ([(self.x[0], self.y[0])]
                       + list(zip(reversed(self.x), reversed(self.y))))
         # Create vertex coordinates for each grid cell...
@@ -90,8 +104,8 @@ def get_mask(self, current_image):
         points = np.vstack((x, y)).T
 
         roi_path = MplPath(poly_verts)
-        grid = roi_path.contains_points(points).reshape((ny, nx))
-        return grid
+        mask = roi_path.contains_points(points).reshape((ny, nx))
+        return mask
 
     def display_roi(self, **linekwargs):
         line = plt.Line2D(self.x + [self.x[0]], self.y + [self.y[0]],
@@ -100,14 +114,39 @@ def display_roi(self, **linekwargs):
         ax.add_line(line)
         plt.draw()
 
-    def get_mean_and_std(self, current_image):
-        mask = self.get_mask(current_image)
-        mean = np.mean(np.extract(mask, current_image))
-        std = np.std(np.extract(mask, current_image))
+    def get_mean_and_std(self, image):
+        """Get statistics about pixel values of an image inside the ROI.
+
+        Parameters
+        ----------
+        image: numpy array (2D)
+            Image on which the statistics should be calculated
+
+        Returns
+        -------
+        list of float:
+            mean and standard deviation of the pixel values inside the ROI
+
+        """
+        mask = self.get_mask(image)
+        mean = np.mean(np.extract(mask, image))
+        std = np.std(np.extract(mask, image))
         return mean, std
 
-    def display_mean(self, current_image, **textkwargs):
-        mean, std = self.get_mean_and_std(current_image)
+    def display_mean(self, image, **textkwargs):
+        """Display statistics about pixel values of an image inside the ROI.
+
+        Parameters
+        ----------
+        image: numpy array (2D)
+            Image on which the statistics should be calculated
+
+        Returns
+        -------
+        None
+
+        """
+        mean, std = self.get_mean_and_std(image)
         string = "%.3f +- %.3f" % (mean, std)
         plt.text(self.x[0], self.y[0],
                  string, color=self.color,

roipoly/version.py

@@ -1 +1 @@
-__version__ = '0.5.3'
+__version__ = '0.5.4'