Feat report summary (#159)

* doc: skeleton metrics and swc_loading

* feat: fix label misalignments

* doc: skeletongraph and dataloading

---------

Co-authored-by: anna-grim <[email protected]>

Author: anna-grim

src/segmentation_skeleton_metrics/data_handling/graph_loading.py

@@ -26,6 +26,10 @@
 
 
 class DataLoader:
+    """
+    A class that loads ground truth and fragment graphs and provides tools for
+    labeling ground truth graphs.
+    """
 
     def __init__(
         self,
@@ -34,6 +38,23 @@ def __init__(
         use_anisotropy=False,
         verbose=True
     ):
+        """
+        Instantiates a DataLoader object.
+
+        Parameters
+        ----------
+        label_handler : LabelHander
+            Handles mapping between raw segmentation labels and consolidated
+            class IDs.
+        anisotropy : Tuple[int], optional
+            Image to physical coordinates scaling factors to account for the
+            anisotropy of the microscope. Default is (1.0, 1.0, 1.0).
+        use_anisotropy : bool, optional
+            Indication of whether to apply the anisotropy to the coordinates
+            from the fragment SWC files. Default is False.
+        verbose : bool, optional
+            Indication of whether to display a progress bar. Default is True.
+        """
         # Instance attributes
         self.anisotropy = anisotropy
         self.label_handler = label_handler
@@ -275,6 +296,21 @@ def to_graph(self, swc_dict):
         return {graph.name: graph}
 
     def _init_graph(self, swc_dict):
+        """
+        Initializes and returns a graph object from a parsed SWC dictionary.
+
+        Parameters
+        ----------
+        swc_dict : dict
+            Dictionary whose keys and values are the attribute names and
+            values from an SWC file.
+    
+        Returns
+        -------
+        SkeletonGraph
+            An initialized LabeledGraph or FragmentGraph instance with voxel
+            data, filename, and node count set.
+        """
         # Instantiate graph
         if self.is_groundtruth:
             graph = LabeledGraph(
@@ -304,7 +340,7 @@ def _label_graph(self, graph):
 
         Parameters
         ----------
-        graph : SkeletonGraph
+        graph : LabeledGraph
             Graph to be labeled.
         """
         with ThreadPoolExecutor() as executor:
@@ -427,14 +463,14 @@ def check_misalignment(graph, visited_edges, nb, root):
 
         Parameters
         ----------
-        graph : networkx.Graph
+        graph : LabeledGraph
             Graph that represents a ground truth neuron.
-        visited_edges : List[tuple]
+        visited_edges : List[Frozenset[int]]
             List of edges in "graph" that have been visited.
         nb : int
             Neighbor of "root".
         root : int
-            Node where possible split starts (i.e. zero-valued label).
+            Node where possible misalignment starts (i.e. zero-valued label).
         """
         # Search graph
         label_collisions = set()
@@ -542,7 +578,7 @@ def build_labels_graph(self, connections_path):
 
         Returns
         -------
-        networkx.Graph
+        LabeledGraph
             Graph with nodes that represent labels and edges are based on the
             connections read from the "connections_path".
         """
@@ -614,7 +650,7 @@ def get_node_labels(self, graph):
 
         Parameters
         ----------
-        graph : SkeletonGraph
+        graph : LabeledGraph
             Graph from which to retrieve the node labels.
 
         Returns

src/segmentation_skeleton_metrics/data_handling/skeleton_graph.py

@@ -75,6 +75,15 @@ def __init__(self, anisotropy=(1.0, 1.0, 1.0), name=None):
         self.voxels = None
 
     def init_kdtree(self, use_voxels=True):
+        """
+        Builds a KD-Tree from the node coordinates.
+
+        Parameters
+        ----------
+        use_voxeles : bool, optional
+            Indication of whether to use voxel or physical coordinates.
+            Default is True.
+        """
         if use_voxels:
             self.kdtree = KDTree(self.voxels)
         else:
@@ -194,6 +203,9 @@ def get_radius(self):
         return 3
 
     def prune_branches(self):
+        """
+        Placeholder method to be implemented by subclasses.
+        """
         pass
 
     # --- Writers ---
@@ -209,6 +221,16 @@ def to_zipped_swc(self, zip_writer):
         """
         # Subroutines
         def write_entry(node, parent):
+            """
+            Writes a line in an SWC file
+
+            Parameters
+            ----------
+            node : int
+                Node ID.
+            parent : int
+                Node ID of the parent of "node".
+            """
             x, y, z = tuple(self.voxels[i] * self.anisotropy)
             r = self.get_radius()
             node_id = cnt
@@ -239,8 +261,24 @@ def write_entry(node, parent):
 
 
 class LabeledGraph(SkeletonGraph):
+    """
+    Subclass of SkeletonGraph with the provides support for node-level
+    labeling and tracking label assignments.
+    """
 
     def __init__(self, anisotropy=(1.0, 1.0, 1.0), name=None):
+        """
+        Instantiates a LabeledGraph object.
+
+        Parameters
+        ----------
+        anisotropy : ArrayLike
+            Image to physical coordinates scaling factors to account for the
+            anisotropy of the microscope.
+        name : str or None
+            Name of the graph which is derived from the SWC filename. Default
+            is None.
+        """
         # Call parent class
         super().__init__(anisotropy=anisotropy, name=name)
 
@@ -396,6 +434,9 @@ def get_radius(self):
 
 
 class FragmentGraph(SkeletonGraph):
+    """
+    Subclass of SkeletonGraph for skeletons derived from the segmentation.
+    """
 
     def __init__(
         self,
@@ -404,6 +445,24 @@ def __init__(
         label=None,
         segment_id=None,
     ):
+        """
+        Instantiates a FragmentGraph object.
+
+        Parameters
+        ----------
+        anisotropy : ArrayLike, optional
+            Image to physical coordinates scaling factors to account for the
+            anisotropy of the microscope. Default is (1.0, 1.0, 1.0).
+        name : str or None, optional
+            Name of the graph which is derived from the SWC filename. Default
+            is None.
+        label : int, optional
+            Graph-level label that corresponds to a node-level label given to
+            a ground truth graph. Default is None.
+        segment_id : int, optional
+            Segment ID of the segment the given skeleton was obtained from.
+            Default is None.
+        """
         # Call parent class
         super().__init__(anisotropy=anisotropy, name=name)
 

src/segmentation_skeleton_metrics/evaluate.py

@@ -4,7 +4,8 @@
 @author: Anna Grim
 @email: [email protected]
 
-...
+Code that provides a wrapper for loading data and calling the SkeletMetric
+subclasses.
 
 """