added documentation

Author: anna-grim

src/segmentation_skeleton_metrics/skeleton_graph.py

@@ -39,6 +39,7 @@ class SkeletonGraph(nx.Graph):
         A 3D array that contains a voxel coordinate for each node.
 
     """
+
     colors = [
         "# COLOR 1.0 0.0 1.0",  # pink
         "# COLOR 0.0 1.0 1.0",  # cyan
@@ -375,8 +376,20 @@ def to_zipped_swc(self, zip_writer):
             zip_writer.writestr(self.filename, text_buffer.getvalue())
 
     def get_color(self):
+        """
+        Gets the display color of the skeleton to be written to an SWC file.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        str
+            String representing the color in the format "# COLOR R G B".
+
+        """
         if self.is_groundtruth:
-             return "# COLOR 1.0 1.0 1.0"
+            return "# COLOR 1.0 1.0 1.0"
         else:
             return util.sample_once(SkeletonGraph.colors)
-            

src/segmentation_skeleton_metrics/skeleton_metric.py

@@ -49,13 +49,6 @@ class SkeletonMetric:
         (7) Expected Run Length (ERL)
         (8) Normalized ERL
 
-    Class attributes
-    ----------------
-    merge_dist : float
-        ...
-    min_label_cnt : int
-        ...
-
     """
 
     def __init__(
@@ -146,7 +139,7 @@ def __init__(
             "Edge Accuracy",
             "ERL",
             "Normalized ERL",
-            "GT Run Length"
+            "GT Run Length",
         ]
         self.metrics = pd.DataFrame(index=row_names, columns=col_names)
 
@@ -561,7 +554,7 @@ def is_fragment_merge(self, key, label, kdtree):
 
         """
         for fragment_graph in self.find_graph_from_label(label):
-            if fragment_graph.run_length < 10**6:
+            if fragment_graph.run_length < 10 ** 6:
                 # Search for leaf far from ground truth
                 visited = set()
                 for leaf in gutil.get_leafs(fragment_graph):
@@ -579,8 +572,11 @@ def is_fragment_merge(self, key, label, kdtree):
                     )
             else:
                 segment_id = util.get_segment_id(fragment_graph.filename)
+                run_length = fragment_graph.run_length
                 self.merged_labels.add((key, segment_id, -1))
-                print(f"Skipping {segment_id} - run_length={fragment_graph.run_length}")
+                print(
+                    f"Skipping {segment_id} - run_length={run_length}"
+                )
 
     def find_merge_site(self, key, kdtree, fragment_graph, source, visited):
         for _, node in nx.dfs_edges(fragment_graph, source=source):
@@ -605,7 +601,9 @@ def find_merge_site(self, key, kdtree, fragment_graph, source, visited):
                                 "Segment_ID": segment_id,
                                 "GroundTruth_ID": key,
                                 "Voxel": tuple([int(t) for t in voxel]),
-                                "World": tuple([float(round(t, 2)) for t in xyz]),
+                                "World": tuple(
+                                    [float(round(t, 2)) for t in xyz]
+                                ),
                             }
                         )
 
@@ -615,8 +613,8 @@ def find_merge_site(self, key, kdtree, fragment_graph, source, visited):
                                 fragment_graph, self.merge_writer
                             )
                             gutil.write_graph(
-                                 self.gt_graphs[key], self.merge_writer
-                             )
+                                self.gt_graphs[key], self.merge_writer
+                            )
                         return
 
     def is_valid_merge(self, graph, kdtree, root):
@@ -643,7 +641,7 @@ def is_valid_merge(self, graph, kdtree, root):
                     queue.append((j, d_j))
                     visited.add(j)
         return True if n_hits > 16 else False
-    
+
     def process_merge_sites(self):
         if self.merge_sites:
             # Remove duplicates

src/segmentation_skeleton_metrics/utils/swc_util.py

@@ -178,9 +178,7 @@ def read_from_paths(self, paths):
             for path in paths:
                 filename = os.path.basename(path)
                 if self.confirm_read(filename):
-                    threads.append(
-                        executor.submit(self.read_from_path, path)
-                    )
+                    threads.append(executor.submit(self.read_from_path, path))
 
             # Store results
             swc_dicts = deque()
@@ -217,9 +215,7 @@ def read_from_zips(self, zip_dir):
             processes = list()
             for f in zip_names:
                 zip_path = os.path.join(zip_dir, f)
-                processes.append(
-                    executor.submit(self.read_from_zip, zip_path)
-                )
+                processes.append(executor.submit(self.read_from_zip, zip_path))
 
             # Store results
             swc_dicts = deque()
@@ -318,6 +314,22 @@ def read_from_gcs(self, gcs_dict):
         raise Exception(f"GCS Pointer is invalid -{gcs_dict}-")
 
     def read_from_gcs_swcs(self, bucket_name, swc_paths):
+        """
+        Reads SWC files stored in a GCS bucket.
+
+        Parameters
+        ----------
+        gcs_dict : dict
+            Dictionary with the keys "bucket_name" and "path" that specify
+            where the SWC files are located in a GCS bucket.
+
+        Returns
+        -------
+        Dequeue[dict]
+            List of dictionaries whose keys and values are the attribute
+            names and values from an SWC file.
+
+        """
         pbar = tqdm(total=len(swc_paths), desc="Read SWCs")
         with ThreadPoolExecutor() as executor:
             # Assign threads
@@ -337,6 +349,22 @@ def read_from_gcs_swcs(self, bucket_name, swc_paths):
         return swc_dicts
 
     def read_from_gcs_swc(self, bucket_name, path):
+        """
+        Reads a single SWC file stored in a GCS bucket.
+
+        Parameters
+        ----------
+        gcs_dict : dict
+            Dictionary with the keys "bucket_name" and "path" that specify
+            where a single SWC file is located in a GCS bucket.
+
+        Returns
+        -------
+        dict
+            Dictionaries whose keys and values are the attribute names and
+            values from an SWC file.
+
+        """
         # Initialize cloud reader
         client = storage.Client()
         bucket = client.bucket(bucket_name)
@@ -348,6 +376,22 @@ def read_from_gcs_swc(self, bucket_name, path):
         return self.parse(content, filename)
 
     def read_from_gcs_zips(self, bucket_name, zip_paths):
+        """
+        Reads SWC files stored in a ZIP archives stored in a GCS bucket.
+
+        Parameters
+        ----------
+        zip_content : bytes
+            Content of a ZIP archive.
+
+        Returns
+        -------
+        Dequeue[dict]
+            List of dictionaries whose keys and values are the attribute
+            names and values from an SWC file.
+
+
+        """
         swc_dicts = deque()
         for zip_path in tqdm(zip_paths, desc="Read SWCs"):
             swc_dicts.extend(self.read_from_gcs_zip(bucket_name, zip_path))

src/segmentation_skeleton_metrics/utils/util.py

@@ -167,7 +167,7 @@ def update_txt(path, text):
 
     """
     print(text)
-    with open(path, 'a') as file:
+    with open(path, "a") as file:
         file.write(text + "\n")
 
 
@@ -248,14 +248,47 @@ def list_gcs_subdirectories(bucket_name, prefix):
     return subdirs
 
 
-def read_txt_from_gcs(bucket_name, file_name):
+def read_txt_from_gcs(bucket_name, filename):
+    """
+    Reads a txt file stored in a GCS bucket.
+
+    Parameters
+    ----------
+    bucket_name : str
+        Name of bucket to be read from.
+    filename : str
+        Name of txt file to be read.
+
+    Returns
+    -------
+    str
+        Contents of txt file.
+
+    """
     client = storage.Client()
     bucket = client.bucket(bucket_name)
-    blob = bucket.blob(file_name)
+    blob = bucket.blob(filename)
     return blob.download_as_text()
 
 
 def upload_directory_to_gcs(bucket_name, source_dir, destination_dir):
+    """
+    Uploads the contents of a local directory to a GCS bucket.
+
+    Parameters
+    ----------
+    bucket_name : str
+        Name of bucket to be read from.
+    source_dir : str
+        Path to the local directory whose contents should be uploaded.
+    destination_dir : str
+        Prefix path in the GCS bucket under which the files will be stored.
+
+    Returns
+    -------
+    None
+
+    """
     client = storage.Client()
     bucket = client.bucket(bucket_name)
     for root, _, files in os.walk(source_dir):