Docstrings added

brainprint/brainprint.py

@@ -359,6 +359,21 @@ def __init__(
             test_freesurfer()
 
     def run(self, subject_id: str, destination: Path = None) -> Dict[str, Path]:
+        """
+        Run Brainprint analysis for a specified subject.
+
+        Parameters
+        ----------
+        subject_id : str
+            The ID of the subject to analyze.
+        destination : Path, optional
+            The destination directory for analysis results, by default None.
+
+        Returns
+        -------
+        Dict[str, Path]
+            A dictionary containing paths to the generated analysis results.
+        """
         self._eigenvalues = self._eigenvectors = self._distances = None
         subject_dir = validate_subject_dir(self.subjects_dir, subject_id)
         destination = create_output_paths(
@@ -389,12 +404,38 @@ def run(self, subject_id: str, destination: Path = None) -> Dict[str, Path]:
         return self.export_results(destination=destination, subject_id=subject_id)
 
     def export_results(self, destination: Path, subject_id: str) -> None:
+        """
+        Export Brainprint analysis results to a CSV file.
+
+        Parameters
+        ----------
+        destination : Path
+            The destination directory for analysis results.
+        subject_id : str
+            The ID of the subject being analyzed.
+
+        Returns
+        -------
+        None
+        """
         csv_name = "{subject_id}.brainprint.csv".format(subject_id=subject_id)
         csv_path = destination / csv_name
         return export_brainprint_results(
             csv_path, self._eigenvalues, self._eigenvectors, self._distances
         )
 
     def cleanup(self, destination: Path) -> None:
+        """
+        Clean up temporary files generated during the analysis.
+
+        Parameters
+        ----------
+        destination : Path
+            The destination directory for analysis results.
+
+        Returns
+        -------
+        None
+        """
         if not self.keep_temp:
             shutil.rmtree(destination / "temp")

brainprint/surfaces.py

@@ -81,6 +81,21 @@ def create_aseg_surface(
 
 
 def create_aseg_surfaces(subject_dir: Path, destination: Path) -> Dict[str, Path]:
+    """
+    Create surfaces from FreeSurfer aseg labels.
+
+    Parameters
+    ----------
+    subject_dir : Path
+        Path to the subject's FreeSurfer directory.
+    destination : Path
+        Path to the destination directory for saving surfaces.
+
+    Returns
+    -------
+    Dict[str, Path]
+        A dictionary mapping label names to the corresponding Path objects of created surfaces.
+    """
     # Define aseg labels
 
     # combined and individual aseg labels:
@@ -129,8 +144,22 @@ def create_aseg_surfaces(subject_dir: Path, destination: Path) -> Dict[str, Path
         for label, indices in aseg_labels.items()
     }
 
-
 def create_cortical_surfaces(subject_dir: Path, destination: Path) -> Dict[str, Path]:
+    """
+    Create cortical surfaces from FreeSurfer labels.
+
+    Parameters
+    ----------
+    subject_dir : Path
+        Path to the subject's FreeSurfer directory.
+    destination : Path
+        Path to the destination directory where the surfaces will be saved.
+
+    Returns
+    -------
+    Dict[str, Path]
+        A dictionary mapping label names to the corresponding Path objects of created surfaces.
+    """
     cortical_labels = {
         "lh-white-2d": "lh.white",
         "rh-white-2d": "rh.white",
@@ -145,10 +174,26 @@ def create_cortical_surfaces(subject_dir: Path, destination: Path) -> Dict[str,
         for label, name in cortical_labels.items()
     }
 
-
 def create_surfaces(
     subject_dir: Path, destination: Path, skip_cortex: bool = False
 ) -> Dict[str, Path]:
+    """
+    Create surfaces based on FreeSurfer labels.
+
+    Parameters
+    ----------
+    subject_dir : Path
+        Path to the subject's FreeSurfer directory.
+    destination : Path
+        Path to the destination directory where the surfaces will be saved.
+    skip_cortex : bool, optional
+        If True, cortical surfaces will not be created (default is False).
+
+    Returns
+    -------
+    Dict[str, Path]
+        A dictionary mapping label names to the corresponding Path objects of created surfaces.
+    """
     surfaces = create_aseg_surfaces(subject_dir, destination)
     if not skip_cortex:
         cortical_surfaces = create_cortical_surfaces(subject_dir, destination)
@@ -157,6 +202,24 @@ def create_surfaces(
 
 
 def read_vtk(path: Path):
+    """
+    Read a VTK file and return a triangular mesh.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the VTK file to be read.
+
+    Returns
+    -------
+    TriaMesh
+        A triangular mesh object representing the contents of the VTK file.
+
+    Raises
+    ------
+    RuntimeError
+        If there is an issue reading the VTK file or if the file is empty.
+    """
     try:
         triangular_mesh = TriaMesh.read_vtk(path)
     except Exception: