diff --git a/brainprint/brainprint.py b/brainprint/brainprint.py index fb1febd..7bdab56 100644 --- a/brainprint/brainprint.py +++ b/brainprint/brainprint.py @@ -1,5 +1,5 @@ """ -Definition of the brainprint analysis execution functions. +Definition of the brainprint analysis execution functions.. """ import shutil @@ -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,6 +404,20 @@ 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( @@ -396,5 +425,17 @@ def export_results(self, destination: Path, subject_id: str) -> None: ) 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") diff --git a/brainprint/surfaces.py b/brainprint/surfaces.py index 65e4081..73b4d5f 100644 --- a/brainprint/surfaces.py +++ b/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] + Dictionary of label names mapped to corresponding surface Path objects. + """ # Define aseg labels # combined and individual aseg labels: @@ -131,6 +146,21 @@ def create_aseg_surfaces(subject_dir: Path, destination: Path) -> Dict[str, Path 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] + Dictionary mapping label names to associated surface Paths. + """ cortical_labels = { "lh-white-2d": "lh.white", "rh-white-2d": "rh.white", @@ -149,6 +179,23 @@ def create_cortical_surfaces(subject_dir: Path, destination: Path) -> Dict[str, 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] + Dict 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 +204,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: