Merge pull request #7 from rosalindfranklininstitute/docs

Docs

Author: MasterVexillen

GeoLlama/calc_by_slice.py

@@ -1,4 +1,3 @@
-
 # Copyright 2023 Rosalind Franklin Institute
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,7 +16,7 @@
 ## Module             : GeoLlama.calc_by_slice  ##
 ## Created            : Neville Yee             ##
 ## Date created       : 02-Oct-2023             ##
-## Date last modified : 09-Oct-2023             ##
+## Date last modified : 19-Apr-2024             ##
 ##################################################
 
 import itertools
@@ -88,7 +87,20 @@ def create_slice_views(volume: npt.NDArray[any],
                        coords: list,
                        std_window: int=15,
                        gaussian_sigma: int=None,
-) -> (npt.NDArray[any], npt.NDArray[any], npt.NDArray[any]):
+) -> (npt.NDArray[any], npt.NDArray[any]):
+    """
+    Create slice views from full tomogram for downstream processes
+
+    Args:
+    volume (ndarray) : input 3D image (tomogram)
+    coords (list) : list of coordinates for creation of 2D slice views
+    std_window (int) : width of window for metric calculation for 2D slices
+    gaussian_sigma (int) : Sigma parameter for Gaussian blurring kernal
+
+    Returns:
+    ndarray, ndarray
+    """
+
     std_half = std_window // 2
     z_range = (max(0, coords[0]-std_half), min(coords[0]+std_window-std_half, volume.shape[0]-1))
     x_range = (max(0, coords[1]-std_half), min(coords[1]+std_window-std_half, volume.shape[1]-1))
@@ -233,6 +245,20 @@ def evaluate_slice(slice_coords: list,
 ) -> (float, float, float, int,
       npt.NDArray, npt.NDArray, npt.NDArray, npt.NDArray,
 ):
+    """
+    Function for creation and evaluation of one 2D slice from tomogram given coordinates of intersection point
+
+    Args:
+    slice_coords (list) : list containing coordinates of intersection point for image slicing
+    volume (ndarray) : tomogram for evaluation
+    pixel_size_nm (float) : pixel size of tomogram (internally binned)
+    use_view (str) : view (orientation of slice) used for evaluation
+    pt_thres (int) : acceptance limit (number of feature pixels) of slices
+    autocontrast (bool) : whether to apply autocontrast on slices before evaluation
+
+    Returns:
+    float, float, float, int, ndarray, ndarray, ndarray, ndarray
+    """
 
     view_zy, view_zx = create_slice_views(
         volume=volume,
@@ -367,11 +393,26 @@ def evaluate_slice(slice_coords: list,
             surface_bottom_1, surface_bottom_2)
 
 
-def evaluate_full_lamella(volume,
-                          pixel_size_nm,
-                          autocontrast,
-                          cpu=1,
+def evaluate_full_lamella(volume: npt.NDArray[any],
+                          pixel_size_nm: float,
+                          autocontrast: bool,
+                          cpu: int=1,
+) -> (
+    npt.NDArray, npt.NDArray, float, float, float, float, tuple
 ):
+    """
+    Evaluation of full lamella geometry
+
+    Args:
+    volume (ndarray) : Tomogram to be evaluated
+    pixel_size_nm (float) : Pixel size (after binning) of tomogram
+    autocontrast (bool) : whether to apply autocontrast on slices before evaluation
+    cpu (int) : number of cores used in parallel calculation of slices
+
+    Returns:
+    ndarray, ndarray, float, float, float, float, tuple
+
+    """
     x_slice_list = np.arange(int(volume.shape[1]*0.2),
                              int(volume.shape[1]*0.8),
                              int(volume.shape[1]*0.025))

GeoLlama/evaluate.py

@@ -16,7 +16,7 @@
 ## Module             : GeoLlama.evaluate  ##
 ## Created            : Neville Yee        ##
 ## Date created       : 05-Oct-2023        ##
-## Date last modified : 05-Oct-2023        ##
+## Date last modified : 19-Apr-2024        ##
 #############################################
 
 
@@ -38,7 +38,13 @@
 
 def find_files(path: str) -> list:
     """
-    Some docstrings
+    Function to find appropriate files from given path
+
+    Args:
+    path (str) : Path to folder holding tomograms
+
+    Returns:
+    list
     """
 
     criterion = Path(path).glob("**/*.mrc")
@@ -48,6 +54,15 @@ def find_files(path: str) -> list:
 
 
 def save_figure(surface_info, save_path, binning):
+    """
+    Export data and interpolated surfaces as PNG file
+
+    Args:
+    surface_info (tuple) : Outputs (tuple) of GeoLlama evaluation module
+    save_path (str) : Path to PNG file being exported
+    binning (int) : Internal binning factor of tomogram
+    """
+
     xx_top, yy_top, surface_top, xx_bottom, yy_bottom, surface_bottom, _, _ = surface_info
 
     fig, ax = plt.subplots(subplot_kw={"projection": "3d"},
@@ -72,6 +87,14 @@ def save_figure(surface_info, save_path, binning):
 
 
 def save_text_model(surface_info, save_path, binning):
+    """
+    Export data and interpolated model as text file for conversion and visualisation in IMOD.
+
+    Args:
+    surface_info (tuple) : Outputs (tuple) of GeoLlama evaluation module
+    save_path (str) : Path to text file being exported
+    binning (int) : Internal binning factor of tomogram
+    """
     xx_top, yy_top, surface_top, xx_bottom, yy_bottom, surface_bottom, model_top, model_bottom = surface_info
 
     contour_top = np.full((len(model_top),1), 1, dtype=int)
@@ -101,7 +124,18 @@ def eval_single(
         autocontrast: bool,
 ):
     """
-    Some docstring
+    Evaluate geometry of a single tomogram given source file
+
+    Args:
+    fname (str) : Path to tomogram file
+    pixel_size (float) : Pixel size of tomogram in nm
+    binning (int) : Internal binning factor for GeoLlama evaluation
+    cpu (int) : Number of cores used for parallel calculations
+    bandpass (bool) : Whether to include bandpass as a preprocessing step
+    autocontrast (bool) : Whether to include autocontrast as a preprocessing step
+
+    Returns:
+    ndarray, ndarray, ndarray, ndarray, ndarray, ndarray, ndarray
     """
 
     tomo, pixel_size = io.read_mrc(
@@ -138,7 +172,18 @@ def eval_batch(
         autocontrast: bool,
 ) -> (pd.DataFrame, pd.DataFrame):
     """
-    Some docstring
+    Evaluate geometry of tomograms given path to folder containing tomograms, then output statistics as pandas DataFrames.
+
+    Args:
+    filelist (list) : List containing paths to tomograms
+    pixel_size (float) : Pixel size of tomogram in nm
+    binning (int) : Internal binning factor for GeoLlama evaluation
+    cpu (int) : Number of cores used for parallel calculations
+    bandpass (bool) : Whether to include bandpass as a preprocessing step
+    autocontrast (bool) : Whether to include autocontrast as a preprocessing step
+
+    Returns:
+    DataFrame, DataFrame
     """
 
     thickness_mean_list = []

GeoLlama/io.py

@@ -30,6 +30,17 @@
 def read_mrc(fname: str,
              px_size_nm: float,
              downscale: int=2) -> (npt.NDArray[any], float):
+    """
+    Function to read in MRC image file.
+
+    Args:
+    fname (str) : Path to image file
+    px_size_nm (float) : Pixel size of original tomogram in nm
+    downscale (int) : Internal binning factor
+
+    Returns:
+    ndarray, float
+    """
 
     with mrcfile.open(fname) as f:
         data = f.data