megadetector 5.0.7__py3-none-any.whl → 5.0.9__py3-none-any.whl

md_visualization/plot_utils.py

@@ -1,56 +1,53 @@
-########
-#
-# plot_utils.py
-# 
-# Utility functions for plotting.
-#
-# NOTE: Do NOT import matplotlib.pyplot here to avoid the interactive backend.
-# Thus, the matplotlib.figure.Figure objects returned by the functions here do not
-# need to be "closed" with `plt.close(fig)`.
-# 
-########
+"""
 
-#%% Imports
+plot_utils.py
+
+Utility functions for plotting, particularly for plotting confusion matrices
+and precision-recall curves.
 
-from typing import Any, Optional, Sequence, Tuple, Union
+"""
+
+#%% Imports
 
 import numpy as np
-import matplotlib.figure  # this also imports mpl.{cm, axes, colors}
+
+# This also imports mpl.{cm, axes, colors}
+import matplotlib.figure
 
 
 #%% Plotting functions
 
-def plot_confusion_matrix(
-        matrix: np.ndarray,
-        classes: Sequence[str],
-        normalize: bool = False,
-        title: str = 'Confusion matrix',
-        cmap: Union[str, matplotlib.colors.Colormap] = matplotlib.cm.Blues,
-        vmax: Optional[float] = None,
-        use_colorbar: bool = True,
-        y_label: bool = True,        
-        fmt: str = '{:.0f}',
-        fig=None
-        ) -> matplotlib.figure.Figure:
+def plot_confusion_matrix(matrix,
+                          classes,
+                          normalize=False,
+                          title='Confusion matrix',
+                          cmap=matplotlib.cm.Blues,
+                          vmax=None,
+                          use_colorbar=True,
+                          y_label=True,
+                          fmt= '{:.0f}',
+                          fig=None):
     """
-    Plot a confusion matrix. By default, assumes values in the given matrix
-    are percentages. If the matrix contains counts, normalization can be applied
-    by setting `normalize=True`.
+    Plots a confusion matrix.
 
     Args:
-        matrix: np.ndarray, shape [num_classes, num_classes], confusion matrix
-            where rows are ground-truth classes and cols are predicted classes.
-        classes: list of str, class names for each row/column
-        normalize: bool, whether to perform row-wise normalization to sum 1
-        title: str, figure title
-        cmap: colormap, default: matplotlib.cm.Blues
-        vmax: float, value corresponding s to the largest value of the colormap.
-            If None, the maximum value in *matrix* will be used. Default: None
-        use_colorbar: bool, whether to show colorbar
-        y_label: bool, whether to show class names on the y-axis
-        fmt: str, format string
-
-    Returns: matplotlib.figure.Figure, a reference to the figure
+        matrix (np.ndarray): shape [num_classes, num_classes], confusion matrix
+            where rows are ground-truth classes and columns are predicted classes
+        classes (list of str): class names for each row/column
+        normalize (bool, optional): whether to perform row-wise normalization; 
+            by default, assumes values in the confusion matrix are percentages
+        title (str, optional): figure title
+        cmap (matplotlib.colors.colormap): colormap for cell backgrounds
+        vmax (float, optional), value corresponding to the largest value of the colormap;
+            if None, the maximum value in [matrix] will be used
+        use_colorbar (bool, optional): whether to show colorbar
+        y_label (bool, optional): whether to show class names on the y axis
+        fmt (str): format string for rendering numeric values
+        fig (Figure): existing figure to which we should render, otherwise creates
+            a new figure
+        
+    Returns: 
+        matplotlib.figure.Figure: the figure we rendered to or created
     """
     
     num_classes = matrix.shape[0]
@@ -97,24 +94,29 @@ def plot_confusion_matrix(
 
     return fig
 
+# ...def plot_confusion_matrix(...)
 
-def plot_precision_recall_curve(
-        precisions: Sequence[float], recalls: Sequence[float],
-        title: str = 'Precision/recall curve',
-        xlim=(0.0,1.05),ylim=(0.0,1.05)
-        ) -> matplotlib.figure.Figure:
+
+def plot_precision_recall_curve(precisions, 
+                                recalls, 
+                                title='Precision/recall curve',
+                                xlim=(0.0,1.05),
+                                ylim=(0.0,1.05)):
     """
-    Plots the precision recall curve given lists of (ordered) precision
+    Plots a precision/recall curve given lists of (ordered) precision
     and recall values.
 
     Args:
-        precisions: list of float, precision for corresponding recall values,
-            should have same length as *recalls*.
-        recalls: list of float, recall for corresponding precision values,
-            should have same length as *precisions*.
-        title: str, plot title
-
-    Returns: matplotlib.figure.Figure, reference to the figure
+        precisions (list of float): precision for corresponding recall values,
+            should have same length as [recalls].
+        recalls (list of float): recall for corresponding precision values,
+            should have same length as [precisions].
+        title (str, optional): plot title
+        xlim (tuple, optional): x-axis limits as a length-2 tuple
+        ylim (tuple, optional): y-axis limits as a length-2 tuple
+
+    Returns: 
+        matplotlib.figure.Figure: the (new) figure
     """
     
     assert len(precisions) == len(recalls)
@@ -138,27 +140,24 @@ def plot_precision_recall_curve(
     return fig
 
 
-def plot_stacked_bar_chart(data: np.ndarray,
-                           series_labels: Sequence[str],
-                           col_labels: Optional[Sequence[str]] = None,
-                           x_label: Optional[str] = None,
-                           y_label: Optional[str] = None,
-                           log_scale: bool = False
-                           ) -> matplotlib.figure.Figure:
+def plot_stacked_bar_chart(data, series_labels=None, col_labels=None,
+                           x_label=None, y_label=None, log_scale=False):
     """
-    For plotting e.g. species distribution across locations.
+    Plot a stacked bar chart, for plotting e.g. species distribution across locations.
+    
     Reference: https://stackoverflow.com/q/44309507
 
     Args:
-        data: 2-D np.ndarray or nested list, rows (series) are species, columns
+        data (np.ndarray or list of list): data to plot; rows (series) are species, columns
             are locations
-        series_labels: list of str, e.g., species names
-        col_labels: list of str, e.g., location names
-        x_label: str
-        y_label: str
-        log_scale: bool, whether to plot y-axis in log-scale
-
-    Returns: matplotlib.figure.Figure, reference to figure
+        series_labels (list of str, optional): series labels, typically species names
+        col_labels (list of str, optional): column labels, typically location names
+        x_label (str, optional): x-axis label
+        y_label (str, optional): y-axis label
+        log_scale (bool, optional) whether to plot the y axis in log-scale
+
+    Returns: 
+        matplotlib.figure.Figure: the (new) figure
     """
     
     data = np.asarray(data)
@@ -200,28 +199,29 @@ def plot_stacked_bar_chart(data: np.ndarray,
     return fig
 
 
-def calibration_ece(true_scores: Sequence[int], pred_scores: Sequence[float],
-                    num_bins: int) -> Tuple[np.ndarray, np.ndarray, float]:
-    """
+def calibration_ece(true_scores, pred_scores, num_bins):
+    r"""
     Expected calibration error (ECE) as defined in equation (3) of
-        Guo et al. "On Calibration of Modern Neural Networks." (2017).
+    Guo et al. "On Calibration of Modern Neural Networks." (2017).
 
     Implementation modified from sklearn.calibration.calibration_curve()
-    in order to implement ECE calculation. See
-        https://github.com/scikit-learn/scikit-learn/issues/18268
+    in order to implement ECE calculation. See:
+    
+    https://github.com/scikit-learn/scikit-learn/issues/18268
 
     Args:
-        pred_scores: list of float, length N, pred_scores[i] is the predicted
-            confidence that example i is positive
-        true_scores: list of int, length N, binary-valued (0 = neg, 1 = pos)
-        num_bins: int, number of bins to use (`M` in eq. (3) of Guo 2017)
+        true_scores (list of int): true values, length N, binary-valued (0 = neg, 1 = pos)
+        pred_scores (list of float): predicted confidence values, length N, pred_scores[i] is the 
+            predicted confidence that example i is positive
+        num_bins (int): number of bins to use (`M` in eq. (3) of Guo 2017)
 
     Returns:
-        accs: np.ndarray, shape [M], type float64, accuracy in each bin,
-            M <= num_bins because bins with no samples are not returned
-        confs: np.ndarray, shape [M], type float64, mean model confidence in
-            each bin
-        ece: float, expected calibration error
+        tuple: a length-three tuple containing:
+            - accs: np.ndarray, shape [M], type float64, accuracy in each bin,
+              M <= num_bins because bins with no samples are not returned        
+            - confs: np.ndarray, shape [M], type float64, mean model confidence in
+              each bin
+            - ece: float, expected calibration error
     """
     
     assert len(true_scores) == len(pred_scores)
@@ -242,32 +242,25 @@ def calibration_ece(true_scores: Sequence[int], pred_scores: Sequence[float],
     return accs, confs, ece
 
 
-def plot_calibration_curve(true_scores: Sequence[int],
-                           pred_scores: Sequence[float],
-                           num_bins: int,
-                           name: str = 'calibration',
-                           plot_perf: bool = True,
-                           plot_hist: bool = True,
-                           ax: Optional[matplotlib.axes.Axes] = None,
-                           **fig_kwargs: Any
-                           ) -> matplotlib.figure.Figure:
+def plot_calibration_curve(true_scores, pred_scores, num_bins,
+                           name='calibration', plot_perf=True, plot_hist=True,
+                           ax=None, **fig_kwargs):
     """
-    Plot a calibration curve.
-
-    Consider rewriting / removing this function if
-        https://github.com/scikit-learn/scikit-learn/pull/17443
-    is merged into an actual scikit-learn release.
+    Plots a calibration curve.
 
     Args:
-        see calibration_ece() for args
-        name: str, label in legend for the calibration curve
-        plot_perf: bool, whether to plot y=x line indicating perfect calibration
-        plot_hist: bool, whether to plot histogram of counts
-        ax: optional matplotlib Axes, if given then no legend is drawn, and
-            fig_kwargs are ignored
-        fig_kwargs: only used if ax is None
-
-    Returns: matplotlib Figure
+        true_scores (list of int): true values, length N, binary-valued (0 = neg, 1 = pos)
+        pred_scores (list of float): predicted confidence values, length N, pred_scores[i] is the 
+            predicted confidence that example i is positive
+        num_bins (int): number of bins to use (`M` in eq. (3) of Guo 2017)
+        name (str, optional): label in legend for the calibration curve
+        plot_perf (bool, optional): whether to plot y=x line indicating perfect calibration
+        plot_hist (bool, optional): whether to plot histogram of counts
+        ax (Axes, optional): if given then no legend is drawn, and fig_kwargs are ignored
+        fig_kwargs (dict, optional): only used if [ax] is None
+
+    Returns:
+        matplotlib.figure.Figure: the (new) figure
     """
     
     accs, confs, ece = calibration_ece(true_scores, pred_scores, num_bins)

md_visualization/render_images_with_thumbnails.py

@@ -1,21 +1,23 @@
-########
-# 
-# render_images_with_thumbnails.py
-# 
-# Render an output image with one primary and crops from many secondary images,
-# used to check whether suspicious detections are actually false positives or not.
-#
-########
+"""
 
-#%% Constants
+render_images_with_thumbnails.py
+
+Renders an output image with one primary image and crops from many secondary images,
+used primarily to check whether candidate repeat detections are actually false positives or not.
+
+"""
+
+#%% Imports
 
 import math
 import os
 import random
 
-from md_visualization import visualization_utils as vis_utils
 from PIL import Image
 
+from md_visualization import visualization_utils as vis_utils
+from md_utils import path_utils
+
 
 #%% Support functions
 
@@ -24,10 +26,13 @@ def crop_image_with_normalized_coordinates(
         bounding_box):
     """
     Args:
-        image: image to crop
-        bounding_box: tuple formatted as (x,y,w,h), where (0,0) is the
-        upper-left of the image, and coordinates are normalized
-        (so (0,0,1,1) is a box containing the entire image).
+        image (PIL.Image): image to crop
+        bounding_box (tuple): tuple formatted as (x,y,w,h), where (0,0) is the
+            upper-left of the image, and coordinates are normalized
+            (so (0,0,1,1) is a box containing the entire image).
+            
+    Returns:
+        PIL.Image: cropped image
     """
     
     im_width, im_height = image.size
@@ -39,7 +44,6 @@ def crop_image_with_normalized_coordinates(
     return image.crop((x, y, x+w, y+h))
 
 
-
 #%% Main function
 
 def render_images_with_thumbnails(
@@ -64,20 +68,19 @@ def render_images_with_thumbnails(
     ratio of the primary image. 
     
     Args:
-        primary_image_filename: filename of the primary image to load as str
-        primary_image_width: width at which to render the primary image; if this is 
-            None, will render at the original image width.
-        secondary_image_filename_list: list of strs that are the filenames of
-            the secondary images.
-        secondary_image_bounding_box_list: list of tuples, one per secondary
+        primary_image_filename (str): filename of the primary image to load as str
+        primary_image_width (int): width at which to render the primary image; if this is 
+            None, will render at the original image width
+        secondary_image_filename_list (list): list of filenames of the secondary images
+        secondary_image_bounding_box_list (list): list of tuples, one per secondary
             image. Each tuple is a bounding box of the secondary image,
             formatted as (x,y,w,h), where (0,0) is the upper-left of the image,
             and coordinates are normalized (so (0,0,1,1) is a box containing
             the entire image.
-        cropped_grid_width: width of all the cropped images
-        output_image_filename: str of the filename to write the output image        
-        primary_image_location: 'right' or left'; reserving 'top', 'bottom', etc.
-            for future use.
+        cropped_grid_width (int): width of the cropped-image area
+        output_image_filename (str): filename to write the output image        
+        primary_image_location (str, optional): 'right' or left'; reserving 'top', 'bottom', etc.
+            for future use
     """
 
     # Check to make sure the arguments are reasonable
@@ -183,6 +186,8 @@ def render_images_with_thumbnails(
     # Write output image to disk
     output_image.save(output_image_filename)    
 
+# ...def render_images_with_thumbnails(...)
+
 
 #%% Interactive driver
 
@@ -216,18 +221,15 @@ if False:
             output_image_filename,
             primary_image_location='right')    
 
-    from md_utils import path_utils
     path_utils.open_file(output_image_filename)
     
     
 #%% Command-line driver
 
+# This is just a test driver, this module is not meant to be run from the command line.
+
 def main():
-    
-    #%%
-    
-    from md_utils import path_utils
-    
+        
     # Load images from a test directory.
     #
     # Make the first image in the directory the primary image, 
@@ -268,8 +270,6 @@ def main():
     
     from md_utils import path_utils
     path_utils.open_file(output_image_filename)
-    
-    #%%
-    
+        
 if __name__ == '__main__':
     main()