adding docstrings

Author: charliebudd

src/eca/dataset.py

@@ -5,24 +5,42 @@
 from PIL import Image
 
 class DataSource(Flag):
+    """Flag to indicate origin dataset."""
     CHOLEC = auto()
     ROBUST = auto()
     BOTH = CHOLEC | ROBUST
 
 class AnnotationType(Flag):
+    """Flag to indicate type of annotation."""
     AREA = auto()
     MASK = auto()
     BOTH = AREA | MASK
 
 class ECADataset():
-    def __init__(self, data_directory="eca-data", data_source=DataSource.BOTH, annotation_type=AnnotationType.AREA, include_cropped=True, include_source_info=False) -> None:
+    """
+    Dataloader for the ECA dataset.
+
+    Args:
+        data_directory: root directory of the ECA data.
+        data_source: flag denoting the origin dataset(s) samples will be taken from.
+        annotation_type: flag denoting the type of annotation(s) provided.
+        include_cropped: whether or not to include additional cropped samples.
+        include_source_info: whether or not to include the source information of the sample.
+    """
+    def __init__(
+        self,
+        data_directory: str = "eca-data",
+        data_source: DataSource = DataSource.BOTH,
+        annotation_type: AnnotationType = AnnotationType.AREA,
+        include_cropped: bool = True,
+        include_source_info: bool = False
+    ) -> None:
         super().__init__()
         self.data_directory = data_directory
         self.annotation_type = annotation_type
         self.data_source = data_source
         self.include_cropped = include_cropped
         self.include_source_info = include_source_info
-
         try:
             self.sample_list = self.__get_sample_list()
         except FileNotFoundError:

src/eca/scoring.py

@@ -1,4 +1,5 @@
 import numpy as np
+from typing import Sequence, Optional, Tuple
 
 class Line():
     def __init__(self, a, b) -> None:
@@ -179,7 +180,26 @@ def get_smallest_dist(polygon, point):
             other_point = closest
     return smallest_dist, other_point
 
-def content_area_hausdorff(circle_a, circle_b, frame_size, n_points=100, normalise=True):
+def content_area_hausdorff(
+    circle_a: Optional[Sequence[int]],
+    circle_b: Optional[Sequence[int]],
+    frame_size: Sequence[int],
+    n_points: int = 100,
+    normalise: bool = True
+) -> Tuple[float, Optional[Sequence[Sequence[int]]]]:
+    """
+    Hausdorff distance between two content areas.
+
+    Args:
+        circle_a: circle for the first content area (can be None).
+        circle_b: circle for the second content area (can be None).
+        frame_size: size of the image in question.
+        n_points: number of points used when discretising the edges of the content areas.
+        normalise: whether or not to normalise the result as if the image were 1080x1920.
+    Returns:
+        float: score in pixels (optionally normalised)
+        tuple: the coordinates of the two points found to give the final score.
+    """
 
     if (circle_a == circle_b):
         return 0.0, None