397 standardise docstrings

hazenlib/ACRObject.py

@@ -10,14 +10,14 @@ def __init__(self, dcm_list):
         self.dcm_list = dcm_list
         # Load files as DICOM and their pixel arrays into 'images'
         self.images, self.dcms = self.sort_images()
-        # Store the DCM object of slice 7 as it is used often
-        self.slice7_dcm = self.dcms[6]
         # Store the pixel spacing value from the first image (expected to be the same for all)
         self.pixel_spacing = self.dcms[0].PixelSpacing
         # Check whether images of the phantom are the correct orientation
         self.orientation_checks()
         # Determine whether image rotation is necessary
         self.rot_angle = self.determine_rotation()
+        # Store the DCM object of slice 7 as it is used often
+        self.slice7_dcm = self.dcms[6]
         # Find the centre coordinates of the phantom (circle)
         self.centre, self.radius = self.find_phantom_center()
         # Store a mask image of slice 7 for reusability
@@ -35,6 +35,11 @@ def sort_images(self):
             A sorted stack of dicoms
         """
 
+        # TODO: implement a check if phantom was placed in other than axial position
+        # This is to be able to flag to the user the caveat of measurments if deviating from ACR guidance
+
+        # x = np.array([dcm.ImagePositionPatient[0] for dcm in self.dcm_list])
+        # y = np.array([dcm.ImagePositionPatient[1] for dcm in self.dcm_list])
         z = np.array([dcm.ImagePositionPatient[2] for dcm in self.dcm_list])
         dicom_stack = [self.dcm_list[i] for i in np.argsort(z)]
         img_stack = [dicom.pixel_array for dicom in dicom_stack]
@@ -151,6 +156,7 @@ def find_phantom_center(self):
         """
         img = self.images[6]
         dx, dy = self.pixel_spacing
+
         img_blur = cv2.GaussianBlur(img, (1, 1), 0)
         img_grad = cv2.Sobel(img_blur, 0, dx=1, dy=1)
 
@@ -164,20 +170,23 @@ def find_phantom_center(self):
             minRadius=int(180 / (2 * dy)),
             maxRadius=int(200 / (2 * dx)),
         ).flatten()
-
         centre = [int(i) for i in detected_circles[:2]]
         radius = int(detected_circles[2])
         return centre, radius
 
     def get_mask_image(self, image, mag_threshold=0.05, open_threshold=500):
-        """
+        """Create a masked pixel array
         Mask an image by magnitude threshold before applying morphological opening to remove small unconnected
         features. The convex hull is calculated in order to accommodate for potential air bubbles.
 
-        Returns
-        -------
-        np.array:
-            The masked image.
+        Args:
+            image (_type_): _description_
+            mag_threshold (float, optional): magnitude threshold. Defaults to 0.05.
+            open_threshold (int, optional): open threshold. Defaults to 500.
+
+        Returns:
+            np.array:
+                The masked image.
         """
         test_mask = self.circular_mask(
             self.centre, (80 // self.pixel_spacing[0]), image.shape

hazenlib/tasks/acr_geometric_accuracy.py

@@ -6,7 +6,7 @@
 Calculates geometric accuracy for slices 1 and 5 of the ACR phantom.
 
 This script calculates the horizontal and vertical lengths of the ACR phantom in Slice 1 in accordance with the ACR Guidance.
 This script calculates the horizontal, vertical and diagonal lengths of the ACR phantom in Slice 5 in accordance with the ACR Guidance.
 The average distance measurement error, maximum distance measurement error and coefficient of variation of all distance
 measurements is reported as recommended by IPEM Report 112, "Quality Control and Artefacts in Magnetic Resonance Imaging".
 
@@ -33,11 +33,23 @@
 
 
 class ACRGeometricAccuracy(HazenTask):
+    """Geometric accuracy measurement class for DICOM images of the ACR phantom
+
+    Inherits from HazenTask class
+    """
+
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
         self.ACR_obj = ACRObject(self.dcm_list)
 
     def run(self) -> dict:
+        """Main function for performing geometric accuracy measurement
+        using the first and fifth slices from the ACR phantom image set
+
+        Returns:
+            dict: results are returned in a standardised dictionary structure specifying the task name, input DICOM Series Description + SeriesNumber + InstanceNumber, task measurement key-value pairs, optionally path to the generated images for visualisation
+        """
+
         # Identify relevant slices
         slice1_dcm = self.ACR_obj.dcms[0]
         slice5_dcm = self.ACR_obj.dcms[4]
@@ -89,6 +101,14 @@
         return results
 
     def get_geometric_accuracy_slice1(self, dcm):
+        """Measure geometric accuracy for slice 1
+
+        Args:
+            dcm (pydicom.Dataset): DICOM image object
+
+        Returns:
+            tuple of float: horizontal and vertical distances
+        """
         img = dcm.pixel_array
 
         mask = self.ACR_obj.get_mask_image(self.ACR_obj.images[6])
@@ -147,6 +167,14 @@
         return length_dict["Horizontal Distance"], length_dict["Vertical Distance"]
 
     def get_geometric_accuracy_slice5(self, dcm):
+        """Measure geometric accuracy for slice 5
+
+        Args:
+            dcm (pydicom.Dataset): DICOM image object
+
+        Returns:
+            tuple of floats: horizontal and vertical distances, as well as diagonals (SW, SE)
+        """
         img = dcm.pixel_array
         mask = self.ACR_obj.get_mask_image(self.ACR_obj.images[6])
         cxy = self.ACR_obj.centre
@@ -234,6 +262,15 @@
         )
 
     def diagonal_lengths(self, img, cxy):
+        """Measure diagonal lengths
+
+        Args:
+            img (np.array): dcm.pixel_array
+            cxy (list): x,y coordinates and radius of the circle
+
+        Returns:
+            tuple of dictionaries: _description_
+        """
         res = self.ACR_obj.pixel_spacing
         eff_res = np.sqrt(np.mean(np.square(res)))
         img_rotate = skimage.transform.rotate(img, 45, center=(cxy[0], cxy[1]))
@@ -280,6 +317,14 @@
 
     @staticmethod
     def distortion_metric(L):
+        """Calculate the distortion metric based on length
+
+        Args:
+            L (tuple): horizontal and vertical distances from slices 1 and 5
+
+        Returns:
+            tuple of floats: mean_err, max_err, cov_l
+        """
         err = [x - 190 for x in L]
         mean_err = np.mean(err)
 

hazenlib/tasks/acr_ghosting.py

@@ -25,11 +25,23 @@
 
 
 class ACRGhosting(HazenTask):
+    """Ghosting measurement class for DICOM images of the ACR phantom
+
+    Inherits from HazenTask class
+    """
+
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
+        # Initialise ACR object
         self.ACR_obj = ACRObject(self.dcm_list)
 
     def run(self) -> dict:
+        """Main function for performing ghosting measurement
+        using slice 7 from the ACR phantom image set
+
+        Returns:
+            dict: results are returned in a standardised dictionary structure specifying the task name, input DICOM Series Description + SeriesNumber + InstanceNumber, task measurement key-value pairs, optionally path to the generated images for visualisation
+        """
         # Initialise results dictionary
         results = self.init_result_dict()
         results["file"] = self.img_desc(self.ACR_obj.slice7_dcm)
@@ -50,6 +62,14 @@
         return results
 
     def get_signal_ghosting(self, dcm):
+        """Calculate signal ghosting
+
+        Args:
+            dcm (pydicom.Dataset): DICOM image object
+
+        Returns:
+            float: percentage ghosting value
+        """
         img = dcm.pixel_array
         res = dcm.PixelSpacing  # In-plane resolution from metadata
         r_large = np.ceil(80 / res[0]).astype(

hazenlib/tasks/acr_slice_position.py

@@ -38,11 +38,23 @@
 
 
 class ACRSlicePosition(HazenTask):
+    """Slice position measurement class for DICOM images of the ACR phantom
+
+    Inherits from HazenTask class
+    """
+
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
+        # Initialise ACR object
         self.ACR_obj = ACRObject(self.dcm_list)
 
     def run(self) -> dict:
+        """Main function for performing slice position measurement
+        using the first and last slices from the ACR phantom image set
+
+        Returns:
+            dict: results are returned in a standardised dictionary structure specifying the task name, input DICOM Series Description + SeriesNumber + InstanceNumber, task measurement key-value pairs, optionally path to the generated images for visualisation
+        """
         # Identify relevant slices
         dcms = [self.ACR_obj.dcms[0], self.ACR_obj.dcms[-1]]
 
@@ -63,13 +75,24 @@ def run(self) -> dict:
                 )
                 traceback.print_exc(file=sys.stdout)
                 continue
+
         # only return reports if requested
         if self.report:
             results["report_image"] = self.report_files
 
         return results
 
     def find_wedges(self, img, mask, res):
+        """Find wedges in the pixel array
+
+        Args:
+            img (np.array): dcm.pixel_array
+            mask (np.array): dcm.pixel_array of the image mask
+            res (float): dcm.PixelSpacing
+
+        Returns:
+            tuple: arrays of x and y coordinates of wedges
+        """
         # X COORDINATES
         x_investigate_region = np.ceil(35 / res[0]).astype(
             int
@@ -177,6 +200,14 @@ def find_wedges(self, img, mask, res):
         return x_pts, y_pts
 
     def get_slice_position(self, dcm):
+        """Measure slice position
+
+        Args:
+            dcm (pydicom.Dataset): DICOM image object
+
+        Returns:
+            float: bar length difference
+        """
         img = dcm.pixel_array
         res = dcm.PixelSpacing  # In-plane resolution from metadata
         mask = self.ACR_obj.mask_image
@@ -195,20 +226,21 @@ def get_slice_position(self, dcm):
             1, len(line_prof_L) + (1 / interp_factor), (1 / interp_factor)
         )
 
-        interp_line_prof_L = scipy.interpolate.interp1d(x, line_prof_L)(
-            new_x
-        )  # interpolate left line profile
-        interp_line_prof_R = scipy.interpolate.interp1d(x, line_prof_R)(
-            new_x
-        )  # interpolate right line profile
+        # interpolate left line profile
+        interp_line_prof_L = scipy.interpolate.interp1d(x, line_prof_L)(new_x)
+
+        # interpolate right line profile
+        interp_line_prof_R = scipy.interpolate.interp1d(x, line_prof_R)(new_x)
 
-        delta = interp_line_prof_L - interp_line_prof_R  # difference of line profiles
+        # difference of line profiles
+        delta = interp_line_prof_L - interp_line_prof_R
         peaks, _ = ACRObject.find_n_highest_peaks(
             abs(delta), 2, 0.5 * np.max(abs(delta))
         )  # find two highest peaks
 
+        # if only one peak, set dummy range
         if len(peaks) == 1:
-            peaks = [peaks[0] - 50, peaks[0] + 50]  # if only one peak, set dummy range
+            peaks = [peaks[0] - 50, peaks[0] + 50]
 
         # set multiplier for right or left shift based on sign of peak
         pos = (
@@ -221,8 +253,11 @@ def get_slice_position(self, dcm):
         static_line_L = interp_line_prof_L[peaks[0] : peaks[1]]
         static_line_R = interp_line_prof_R[peaks[0] : peaks[1]]
 
-        lag = np.linspace(-50, 50, 101, dtype=int)  # create array of lag values
-        err = np.zeros(len(lag))  # initialise array of errors
+        # create array of lag values
+        lag = np.linspace(-50, 50, 101, dtype=int)
+
+        # initialise array of errors
+        err = np.zeros(len(lag))
 
         for k, lag_val in enumerate(lag):
             difference = static_line_R - np.roll(
@@ -238,16 +273,14 @@ def get_slice_position(self, dcm):
             # calculate difference
             err[k] = 1e10 if np.isnan(difference).all() else np.nanmean(difference)
 
-        temp = np.argwhere(err == np.min(err[err > 0]))[
-            0
-        ]  # find minimum non-zero error
-        shift = (
-            -lag[temp][0] if pos == 1 else lag[temp][0]
-        )  # find shift corresponding to above error
-
-        dL = (
-            pos * np.abs(shift) * (1 / interp_factor) * res[1]
-        )  # calculate bar length difference
+        # find minimum non-zero error
+        temp = np.argwhere(err == np.min(err[err > 0]))[0]
+
+        # find shift corresponding to above error
+        shift = -lag[temp][0] if pos == 1 else lag[temp][0]
+
+        # calculate bar length difference
+        dL = pos * np.abs(shift) * (1 / interp_factor) * res[1]
 
         if self.report:
             import matplotlib.pyplot as plt