doc: skeleton graph

Author: anna-grim

demo/demo.py

@@ -1,3 +1,13 @@
+"""
+Created on Wed Dec 21 19:00:00 2022
+
+@author: Anna Grim
+@email: [email protected]
+
+Code that runs of demo of using this library to compute skeleton metrics.
+
+"""
+
 import numpy as np
 from xlwt import Workbook
 
@@ -6,18 +16,32 @@
 
 
 def evaluate():
+    """
+    Evaluates the accuracy of a predicted segmentation by comparing it to a
+    set of ground truth skeletons, then reports and saves various performance
+    metrics.
+
+    Parameters
+    ----------
+    None
+
+    Returns
+    -------
+    None
+
+    """
     # Initializations
     pred_labels = TiffReader(pred_labels_path)
     skeleton_metric = SkeletonMetric(
-        target_swcs_pointer,
+        groundtruth_pointer,
         pred_labels,
-        fragments_pointer=pred_swcs_pointer,
+        fragments_pointer=fragments_pointer,
         output_dir=output_dir,
     )
     full_results, avg_results = skeleton_metric.run()
 
     # Report results
-    print(f"Averaged Results...")
+    print(f"\nAveraged Results...")
     for key in avg_results.keys():
         print(f"   {key}: {round(avg_results[key], 4)}")
 
@@ -57,8 +81,8 @@ def save_results(path, stats):
     # Initializations
     output_dir = "./"
     pred_labels_path = "./pred_labels.tif"
-    pred_swcs_pointer = "./pred_swcs.zip"
-    target_swcs_pointer = "./target_swcs.zip"
+    fragments_pointer = "./pred_swcs.zip"
+    groundtruth_pointer = "./target_swcs.zip"
 
     # Run
     evaluate()

src/segmentation_skeleton_metrics/skeleton_graph.py

@@ -1,3 +1,14 @@
+"""
+Created on Wed Dec 21 19:00:00 2022
+
+@author: Anna Grim
+@email: [email protected]
+
+
+Implementation of a custom subclass of NetworkX.Graph called SkeletonGraph.
+
+"""
+
 from scipy.spatial import distance
 
 import networkx as nx
@@ -7,30 +18,128 @@
 
 
 class SkeletonGraph(nx.Graph):
+    """
+    A subclass of the NetworkX.Graph that represents a skeleton graph with
+    additional functionality for handling labels and voxel coordinates
+    corresponding to the nodes. Note that node IDs directly index into the
+    "labels" and "voxels" attributes.
+
+    Attributes
+    ----------
+    anisotropy : ArrayLike
+        Image to physical coordinates scaling factors to account for the
+        anisotropy of the microscope.
+    run_length : float
+        Physical path length of the graph.
+    labels : numpy.ndarray
+        A 1D array that contains a label value associated with each node.
+    voxels : numpy.ndarray
+        A 3D array that contains a voxel coordinate of each node.
+
+    """
 
     def __init__(self, anisotropy=(1.0, 1.0, 1.0)):
+        """
+        Initializes a SkeletonGraph, including setting the anisotropy and
+        initializing the run length attribute.
+
+        Parameters
+        ----------
+        anisotropy : ArrayLike, optional
+            Image to physical coordinates scaling factors to account for the
+            anisotropy of the microscope. The default is (1.0, 1.0, 1.0).
+
+        Returns
+        -------
+        None
+
+        """
         # Call parent class
         super(SkeletonGraph, self).__init__()
 
         # Instance attributes
-        self.anisotropy = anisotropy
+        self.anisotropy = np.array(anisotropy)
         self.run_length = 0
 
-    def set_labels(self):
+    def init_labels(self):
+        """
+        Initializes the "labels" attribute for the graph.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+
+        """
         self.labels = np.zeros((self.number_of_nodes()), dtype=int)
 
+    def init_voxels(self, voxels):
+        """
+        Initializes the "voxels" attribute for the graph.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+
+        """
+        self.voxels = np.array(voxels, dtype=np.int32)
+
     def set_nodes(self):
+        """
+        Adds nodes to the graph. The nodes are assigned indices from 0 to the
+        total number of voxels in the image.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+
+        """
         num_nodes = len(self.voxels)
         self.add_nodes_from(np.arange(num_nodes))
 
-    def set_voxels(self, voxels):
-        self.voxels = np.array(voxels, dtype=np.int32)
-
     # --- Getters ---
     def get_labels(self):
+        """
+        Gets the unique label values in the "labels" attribute.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        numpy.ndarray
+            A 1D array of unique labels assigned to nodes in the graph.
+
+        """
         return np.unique(self.labels)
 
     def nodes_with_label(self, label):
+        """
+        Gets the IDs of nodes that have the specified label value.
+
+        Parameters
+        ----------
+        label : int
+            Label value to search for in the "labels" attribute.
+
+        Returns
+        -------
+        numpy.ndarray
+            A 1D array of node IDs that have the specified label.
+
+        """
         return np.where(self.labels == label)[0]
 
     # --- Computation ---
@@ -69,14 +178,31 @@ def physical_dist(self, i, j):
         Returns
         -------
         float
-            Distance between physical coordinates of the given nodes.
+            Euclidea distance between physical coordinates of the given nodes.
 
         """
         xyz_i = self.voxels[i] * self.anisotropy
         xyz_j = self.voxels[j] * self.anisotropy
         return distance.euclidean(xyz_i, xyz_j)
 
     def get_bbox(self, nodes):
+        """
+        Calculates the bounding box that contains the voxel coordinates for a
+        given collection of nodes.
+
+        Parameters
+        ----------
+        nodes : Container
+            A collection of node indices for which to compute the bounding box.
+
+        Returns
+        -------
+        dict
+            Dictionary containing the bounding box coordinates:
+            - "min": minimum voxel coordinates along each axis.
+            - "max": maximum voxel coordinates along each axis.
+
+        """
         bbox_min = np.inf * np.ones(3)
         bbox_max = np.zeros(3)
         for i in nodes:

src/segmentation_skeleton_metrics/skeleton_metric.py

@@ -220,7 +220,7 @@ def label_graphs(self, key, batch_size=64):
             threads.append(executor.submit(self.get_patch_labels, key, batch))
 
             # Process results
-            self.graphs[key].set_labels()
+            self.graphs[key].init_labels()
             for thread in as_completed(threads):
                 node_to_label = thread.result()
                 for i, label in node_to_label.items():

src/segmentation_skeleton_metrics/utils/graph_util.py

@@ -89,7 +89,7 @@ def to_graph(self, swc_dict):
         """
         # Initialize graph
         graph = SkeletonGraph(anisotropy=self.anisotropy)
-        graph.set_voxels(swc_dict["voxel"])
+        graph.init_voxels(swc_dict["voxel"])
 
         # Build graph
         if not self.coords_only:

src/segmentation_skeleton_metrics/utils/swc_util.py

@@ -25,9 +25,9 @@
 
 from collections import deque
 from concurrent.futures import (
+    as_completed,
     ProcessPoolExecutor,
     ThreadPoolExecutor,
-    as_completed,
 )
 from io import StringIO
 from tqdm import tqdm