oceanproc 0.1.0__py3-none-any.whl

oceanproc/grouplevel/computations.py

@@ -0,0 +1,80 @@
+from numba import jit
+import torch
+import nibabel as nib
+import numpy as np
+import scipy
+from .utils import set_device
+
+# @jit(nopython=True)
+# def ols(y, x):
+    # if len(y.shape) != 2:
+        # raise ValueError(f"Shape of random variable vector y must be of length 2. y.shape: {y.shape}")
+    # elif len(x.shape) != 2:
+        # raise ValueError(f"Shape of design matrix x must be of length 2. x.shape: {x.shape}")
+    # elif y.shape[0] != x.shape[0]:
+        # raise ValueError(f"The number of rows in y and x must match.\ny rows: {y.shape[0]}\nx rows: {x.shape[0]}")
+    # beta_hat = np.linalg.inv(np.transpose(x) @ x) @ np.transpose(x) @ y
+    # residuals = y - (x @ beta_hat)
+    # return (beta_hat, residuals)
+
+
+def ols_regression_over_dscalars(combined_dscalars: nib.cifti2.cifti2.Cifti2Image,
+                                 design_mat: np.ndarray|torch.Tensor):
+    device = set_device()
+    y = torch.from_numpy(combined_dscalars.get_fdata(), device=device)  
+    if isinstance(design_mat, np.ndarray):
+        x = torch.from_numpy(design_mat)
+    if not torch.is_tensor(x):
+        raise TypeError("design_mat must be a torch tensor or numpy ndarray")
+    x = x.to(device)
+    beta_hat = torch.linalg.pinv(torch.transpose(x, 0, 1) @ x) @ torch.transpose(x, 0, 1) @ y
+    residuals = y - (x @ beta_hat)
+    return (beta_hat, residuals)
+
+
+def ttest_1samp_over_dscalars(combined_dscalars: nib.cifti2.cifti2.Cifti2Image,
+                              output_path: str,
+                              popmean: np.ndarray,
+                              alpha: float = 0.05,
+                              tails: int = 1):
+    assert tails in (1,2), "tails must be either 1 or 2"
+    assert alpha > 0 and alpha < 1, "alpha must be between 0 and 1"
+    device = set_device()
+    popmean = torch.from_numpy(popmean, device=device)
+    data = torch.from_numpy(combined_dscalars.get_fdata(), device=device)
+    n = data.shape[0]
+    df = n -1
+    sample_means = torch.mean(data, 0)
+    mean_differences = sample_means - popmean
+    standard_error = torch.std(data, 0) / (n**0.5)
+    t_mat = mean_differences / standard_error
+    t_mat = t_mat.to("cpu")
+    p_mat = tails * scipy.stats.t.sf(t_mat, 30)
+    img = combined_dscalars.__class__(p_mat, combined_dscalars.header)
+    nib.save(img, output_path)
+
+
+# @jit(nopython=True)
+# def ttest_1samp_over_dscalars(combined_dscalars: nib.cifti2.cifti2.Cifti2Image,
+                              # output_path: str,
+                              # popmean: float = 0,
+                              # alpha: float = 0.05,
+                              # tails: int = 1):
+    # assert tails in (1,2), "tails must be either 1 or 2"
+    # assert alpha > 0 and alpha < 1, "alpha must be between 0 and 1"
+    # n = combined_dscalars.shape[0]
+    # df = n - 1
+    # sample_means = np.mean(combined_dscalars, axis=0)
+    # sample_error = (np.std(combined_dscalars, axis=0)) / np.sqrt(n)
+    # diff_mean = sample_means - popmean
+    # t_scores = diff_mean / sample_error
+    # p_values = tails * (1 - scipy.stats.t.cdf(abs(t_scores), df))
+    # p_values = np.array([p_values])
+    # header = nib.cifti2.cifti2.Cifti2Header(p_values)
+    # img = nib.cifti2.cifti2.Cifti2Image(dataobj=p_values, header=header)
+    # nib.save(img, output_path)
+
+    
+
+
+     

oceanproc/grouplevel/design_mat_utils.py

@@ -0,0 +1,54 @@
+import pandas as pd
+import numpy as np
+import re
+from pathlib import Path
+
+def _read_design_matrix(path: str,
+                        sep: str = None,
+                        dtype: type = None) -> np.typing.ArrayLike:
+    if sep is None and re.match(r'^.*\.csv$', path):
+        sep = ','
+    elif sep is None and re.match(r'^.*\.tsv$', path):
+        sep = '\t'
+    if sep is None:
+        raise ValueError("Unrecognized separator in design matrix file (should either be a .csv or .tsv file)")
+    df = pd.DataFrame(path, sep=sep)
+    return df.to_numpy()
+
+
+def design_helper(bids_path: Path, output_file: Path):
+    assert bids_path.exists() and bids_path.is_dir(), "The supplied BIDS Path must be an existing directory"
+    assert output_file.suffix == ".csv", "The supplied output file must be of type '.csv'"
+    entry_list = []
+    subs = sorted([d for d in bids_path.glob("sub-*") if d.is_dir()])
+    for sub_dir in subs:
+        ses_dirs = sorted([d for d in sub_dir.glob("ses-*") if d.is_dir()])
+        for ses_dir in ses_dirs:
+            beta_files = sorted([f for f in ses_dir.glob("func/sub-*_ses-*_task-*_desc-*model-*-beta-*-frame-*.nii*") if f.is_file()])
+            for file in beta_files:
+                name = file.name
+                underscore_split = name.split("_")
+                sub = underscore_split[0].split("-")[-1]
+                ses = underscore_split[1].split("-")[-1]
+                task = underscore_split[2].split("-")[-1]
+                desc_split = underscore_split[4].split("-")
+                model = desc_split[desc_split.index("model") + 1]
+                beta = desc_split[desc_split.index("beta") + 1]
+                frame = desc_split[desc_split.index("frame") + 1].split(".")[0]
+                file_type = "surface" if name.split(".")[1] == "dscalar" else "volume"
+                entry_list.append(
+                    {
+                        "sub" : sub,
+                        "ses" : ses,
+                        "task" : task,
+                        "model" : model,
+                        "beta" : beta,
+                        "frame" : frame,
+                        "file_type" : file_type,
+                        "path" : str(file.resolve())
+                    }
+                )
+    design_scaffold = pd.DataFrame(entry_list)
+    design_scaffold.to_csv(output_file, index=False)
+
+

oceanproc/grouplevel/dscalar_utils.py

@@ -0,0 +1,51 @@
+import re
+import os
+from glob import glob
+from pathlib import Path
+import nibabel as nib
+import numpy as np
+
+
+def _find_all_dscalars(func_dir: str|Path) -> list[str]:
+    """
+    Return a list of all paths to dscalars in func_dir.
+    :param func_dir: path to a subject's functional derivatives directory
+    :type func_dir: pathlib.Path or str
+    :return: a list of absolute paths to dscalars
+    :rtype: list[str]
+    """
+    rel_paths = glob(os.path.join(func_dir, "*dscalar.nii"))
+    return [os.path.abspath(p) for p in rel_paths]
+
+def _filter_dscalar_paths_by_regressor(dscalar_paths: list[str],
+                                      regressors: list[str]) -> list[str]:
+    """
+    Returns a list of paths to .dscalar.nii files containing the names of given regressors.
+    :param dscalar_paths: list of absolute paths to a set of dscalar files
+    :type dscalar_paths: list[str]
+    :param regressors: list of names of regressors contained in the dscalar base name
+    :type regressors: list[str]
+    """
+    if len(regressors) < 1:
+        raise ValueError("List of regressor names must not be empty.")
+    filtered_dscalars = []
+    for regressor in regressors:
+        filtered_dscalars.extend([p for p in dscalar_paths if re.search(regressor, os.path.basename(p))])
+    return filtered_dscalars
+
+def _load_dscalars(dscalar_paths: list[str]) -> list[nib.cifti2.cifti2.Cifti2Image]:
+    assert len(dscalar_paths) > 0, "Lenght of dscalar paths list must be greater than 0"
+    dscalars = []
+    for p in dscalar_paths:
+        dscalars.append(nib.load(p))
+    return dscalars
+
+def _combine_dscalars(dscalars: list[nib.cifti2.cifti2.Cifti2Image]) -> np.typing.ArrayLike:
+    assert len(dscalars) > 0, "Length of dscalars list must be greater than 0"
+    header = dscalars[0].header
+    combined_data = np.array([img.get_fdata().squeeze() for img in dscalars])
+    scalar_axis = nib.cifti2.cifti2_axes.ScalarAxis([f"betamap{i+1}" for i in range(combined_data.shape[0])])
+    brain_model_axis = header.get_axis(1)
+    combined_img = nib.Cifti2Image(combined_data, (scalar_axis, brain_model_axis))
+    return combined_img
+

oceanproc/grouplevel/run.py

@@ -0,0 +1,18 @@
+import pathlib
+import os
+from glob import glob
+
+
+def find_beta_maps(output_dir: pathlib.Path|str,
+                   sub: str):
+    beta_map_paths = [] 
+    for beta_map in glob(
+        os.path.join(
+            output_dir,
+            f"sub-{sub}",
+            "func",
+            "*desc-*activation*"
+        )
+    ):
+        beta_map_paths.append(beta_map)
+    return beta_map_paths

oceanproc/grouplevel/utils.py

@@ -0,0 +1,4 @@
+import torch
+
+def set_device():
+    return torch.device('cuda' if torch.cuda.is_available() else 'cpu')

oceanproc/ocean_proc.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+
+import argparse
+import sys
+from pathlib import Path
+import logging
+import datetime
+from .bids_wrapper import dicom_to_bids
+from .group_series import map_fmap_to_func, map_fmap_to_func_with_pairing_file
+from .fmriprep_wrapper import process_data
+from .events_long import create_events_and_confounds
+from .utils import exit_program_early, prompt_user_continue, default_log_format, add_file_handler, export_args_to_file, flags, debug_logging, log_linebreak
+from .oceanparse import OceanParser
+import shlex
+import shutil
+from subprocess import Popen, PIPE
+from textwrap import dedent
+
+logging.basicConfig(level=logging.INFO,
+                    handlers=[logging.StreamHandler(stream=sys.stdout)],
+                    format=default_log_format)
+logger = logging.getLogger() 
+
+@debug_logging
+def make_work_directory(dir_path:Path, subject:str, session:str) -> Path:
+    dir_to_make = dir_path / f"sub-{subject}_ses-{session}"
+    if dir_to_make.exists():
+        want_to_delete = prompt_user_continue(dedent("""
+            A work directory already exists for this subject and session. 
+            Would you like to delete its contents and start fresh?
+            """))
+        if want_to_delete:
+            logger.debug("removing the old working directory and its contents")
+            shutil.rmtree(dir_to_make)
+        else:
+            return dir_to_make
+    dir_to_make.mkdir()
+    logger.info(f"creating a new working directory at the path: {dir_to_make}")
+    return dir_to_make
+
+
+def main():
+    parser = OceanParser(
+            prog="oceanproc", 
+            description="Ocean Labs adult MRI preprocessing",
+            exit_on_error=False,
+            fromfile_prefix_chars="@",
+            epilog="An arguments file can be accepted with @FILEPATH"
+        )
+    session_arguments = parser.add_argument_group("Session Specific")
+    config_arguments = parser.add_argument_group("Configuration Arguments", "These arguments are saved to a file if the '--export_args' option is used")
+
+    session_arguments.add_argument("--subject", "-su", required=True,
+                        help="The identifier of the subject to preprocess")
+    session_arguments.add_argument("--session", "-se", required=True,
+                        help="The identifier of the session to preprocess")
+    session_arguments.add_argument("--source_data", "-sd", type=Path, required=True,
+                        help="The path to the directory containing the raw DICOM files for this subject and session")
+    session_arguments.add_argument("--xml_path", "-x", type=Path, required=True,
+                        help="The path to the xml file for this subject and session")
+    session_arguments.add_argument("--skip_dcm2bids", action="store_true",
+                        help="Flag to indicate that dcm2bids does not need to be run for this subject and session")
+    session_arguments.add_argument("--skip_fmap_pairing", action="store_true",
+                        help="Flag to indicate that the pairing of fieldmaps to BOLD runs does not need to be performed for this subject and session")
+    session_arguments.add_argument("--skip_fmriprep", action="store_true",
+                        help="Flag to indicate that fMRIPrep does not need to be run for this subject and session")
+    session_arguments.add_argument("--skip_event_files", action="store_true",
+                        help="Flag to indicate that the making of a long formatted events file is not needed for the subject and session")
+    session_arguments.add_argument("--export_args", "-ea", type=Path,
+                        help="Path to a file to save the current configuration arguments")
+    session_arguments.add_argument("--keep_work_dir", action="store_true",
+                        help="Flag to stop the deletion of the fMRIPrep working directory")
+    session_arguments.add_argument("--debug", action="store_true",
+                        help="Flag to run the program in debug mode for more verbose logging")
+    session_arguments.add_argument("--fmap_pairing_file",
+                                   help="Path to JSON containing info on how to pair fieldmaps to BOLD runs.",
+                                   type=Path)
+
+    config_arguments.add_argument("--bids_path", "-b", type=Path, required=True,
+                        help="The path to the directory containing the raw nifti data for all subjects, in BIDS format") 
+    config_arguments.add_argument("--derivs_path", "-d", type=Path, required=True,
+                        help="The path to the BIDS formated derivatives directory for this subject")
+    config_arguments.add_argument("--derivs_subfolder", "-ds", default="fmriprep",
+                        help="The subfolder in the derivatives directory where bids style outputs should be stored. The default is 'fmriprep'.")
+    config_arguments.add_argument("--bids_config", "-c", type=Path, required=True,
+                        help="The path to the dcm2bids config file to use for this subject and session")
+    config_arguments.add_argument("--nordic_config", "-n", type=Path,
+                        help="The path to the second dcm2bids config file to use for this subject and session. This implies that the session contains NORDIC data")
+    config_arguments.add_argument("--nifti", action=argparse.BooleanOptionalAction,
+                        help="Flag to specify that the source directory contains files of type NIFTI (.nii/.jsons) instead of DICOM")
+    config_arguments.add_argument("--anat_only", action='store_true',
+                        help="Flag to specify only anatomical images should be processed.")
+    config_arguments.add_argument("--fd_spike_threshold", "-fd", type=float, default=0.9,
+                        help="framewise displacement threshold (in mm) to determine outlier framee (Default is 0.9).")
+    config_arguments.add_argument("--skip_bids_validation", action="store_true",
+                        help="Specifies skipping BIDS validation (only enabled for fMRIprep step)")
+    config_arguments.add_argument("--fs_subjects_dir", "-fs", type=Path,
+                        help="The path to the directory that contains previous FreeSurfer outputs/derivatives to use for fMRIPrep. If empty, this is the path where new FreeSurfer outputs will be stored.")
+    config_arguments.add_argument("--work_dir", "-w", type=Path, required=True,
+                        help="The path to the working directory used to store intermediate files")
+    config_arguments.add_argument("--fs_license", "-l", type=Path, required=True,
+                        help="The path to the license file for the local installation of FreeSurfer")
+    config_arguments.add_argument("--fmriprep_version", "-fv", default="23.1.4", dest="image",
+                        help="The version of fmriprep to use. The default is 23.1.4. It is reccomended that an entire study use the same version.")
+    args = parser.parse_args()
+
+    try:
+        assert args.derivs_path.is_dir(), "Derivatives directory must exist but it cannot be found"
+        assert args.bids_path.is_dir(), "Raw Bids directory must exist but it cannot be found"
+        assert args.source_data.is_dir(), "Source data directory must exist but it cannot be found"
+        assert args.work_dir.is_dir(), "Work directroy must exist but it cannot be found"
+    except AssertionError as e:
+        logger.exception(e)
+        exit_program_early(e)
+
+    ##### Export the current configuration arguments to a file #####
+    if args.export_args:
+        try:
+            assert args.export_args.parent.exists() and args.export_args.suffix, "Argument export path must be a file path in a directory that exists"
+            logger.info(f"####### Exporting Configuration Arguments to: '{args.export_args}' #######")
+            export_args_to_file(args, config_arguments, args.export_args)
+        except Exception as e:
+            logger.exception(e)
+            exit_program_early(e)
+
+    args.image = f"nipreps/fmriprep:{args.image}"
+
+    args.derivs_path = args.derivs_path / args.derivs_subfolder
+
+    log_dir = args.derivs_path / f"sub-{args.subject}/log"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_path = log_dir / f"sub-{args.subject}_ses-{args.session}_oceanproc_desc-{datetime.datetime.now().strftime('%m-%d-%y_%I-%M%p')}.log"
+    add_file_handler(logger, log_path)
+
+    if args.debug:
+        flags.debug = True
+        logger.setLevel(logging.DEBUG)
+
+    logger.info("Starting oceanproc...")
+    logger.info(f"Log will be stored at {log_path}")
+
+    # log the input arguments
+    for k,v in (dict(args._get_kwargs())).items():
+        logger.info(f" {k} : {v}")
+
+    args.work_dir = make_work_directory(dir_path=args.work_dir, 
+                                        subject=args.subject, 
+                                        session=args.session)
+
+    ##### Convert raw DICOMs to BIDS structure #####
+    if not args.skip_dcm2bids:
+        dicom_to_bids(
+            subject=args.subject,
+            session=args.session,
+            source_dir=args.source_data,
+            bids_dir=args.bids_path,
+            xml_path=args.xml_path,
+            bids_config=args.bids_config,
+            nordic_config=args.nordic_config,
+            nifti=args.nifti
+        )
+
+    ##### Pair field maps to functional runs #####
+    bids_session_dir = args.bids_path / f"sub-{args.subject}/ses-{args.session}"
+
+    if not args.anat_only and not args.skip_fmap_pairing:
+        if args.fmap_pairing_file:
+            map_fmap_to_func_with_pairing_file(
+                bids_session_dir,
+                args.fmap_pairing_file
+            )
+        else:
+            map_fmap_to_func(
+                xml_path=args.xml_path, 
+                bids_dir_path=bids_session_dir
+            )
+
+
+    ##### Run fMRIPrep #####
+    all_opts = dict(args._get_kwargs())
+    fmrip_options = {"work_dir", 
+                     "fs_license", 
+                     "fs_subjects_dir", 
+                     "skip_bids_validation", 
+                     "fd_spike_threshold", 
+                     "anat_only",
+                     "image"}
+
+    if not args.skip_fmriprep:
+        process_data(
+            subject=args.subject, 
+            session=args.session,
+            bids_path=args.bids_path,
+            derivs_path=args.derivs_path,
+            remove_work_folder=None if args.keep_work_dir else args.work_dir,
+            **{o:all_opts[o] for o in fmrip_options}
+        )
+
+    
+    ##### Create long formatted event files #####
+    if not args.skip_event_files:
+        create_events_and_confounds(
+            bids_path=args.bids_path,
+            derivs_path=args.derivs_path,
+            sub=args.subject,
+            ses=args.session,
+            fd_thresh=args.fd_spike_threshold
+        )
+    
+    log_linebreak()
+    logger.info("####### [DONE] Finished all processing, exiting now #######")
+
+    
+if __name__ == "__main__":
+    main()

oceanproc/oceanparse.py

@@ -0,0 +1,107 @@
+import argparse
+import json
+import sys
+
+
+
+class OceanParser(argparse.ArgumentParser):
+
+    def convert_arg_line_to_args(self, arg_line: str) -> list[str]:
+        """
+        Overridded method of argparse.ArgumentParser class.
+
+        Enables the ability to list the argument flag and its value on the same line
+        when reading arguments from a file. Multiple arguments and their values can 
+        also be on the same line.
+
+        :param arg_line: a line of text read from a file
+        :type arg_line: str
+        :return: list of arguments and their values parsed from the 'arg_line' argument
+        :rtype: list[str]
+        """
+        return arg_line.strip().split()
+        # return super().convert_arg_line_to_args(arg_line)
+    
+
+    def _read_args_from_files(self, arg_strings:list[str]):
+        """
+        Overridded method of argparse.ArgumentParser class.
+
+        Reads in each argument string from the input list and checks if any 
+        string is a reference to an argument-file by checking if the value of 
+        the first character is equal to self.fromfile_prefix_chars. If so, 
+        attempts to open this string as a file, and read its contents into the
+        the new_arg_strings list as new arguments. The abilities to read in JSON 
+        files, along with file arguments being prepended to the list have been
+        added to this function
+
+        :param arg_strings: as list of arguments read in from the command line
+        :type arg_strings: list[str]
+        :return: list of old and new (if any) arguments and their values
+        :rtype: list[str]
+        """
+        # expand arguments referencing files
+        new_arg_strings = []
+        for arg_string in arg_strings:
+
+            # for regular arguments, just add them back into the list
+            if not arg_string or arg_string[0] not in self.fromfile_prefix_chars:
+                new_arg_strings.append(arg_string)
+
+            # replace arguments referencing files with the file content
+            else:
+                try:
+                    with open(arg_string[1:]) as args_file:
+                        file_arg_strings = []
+                        if arg_string.endswith(".json"):
+                            jd = json.load(args_file)
+                            for k,v in jd.items():
+                                file_arg_strings.append(k)
+                                if isinstance(v, list):
+                                    for val in v:
+                                        file_arg_strings.append(str(val))
+                                elif isinstance(v, str):
+                                    if not v or not v.strip():
+                                        continue
+                                    else:
+                                        file_arg_strings.append(v)
+                                else:
+                                    file_arg_strings.append(str(v))
+                        else:
+                            for arg_line in args_file.read().splitlines():
+                                for arg in self.convert_arg_line_to_args(arg_line):
+                                    file_arg_strings.append(arg)
+                        file_arg_strings = self._read_args_from_files(file_arg_strings)
+                        new_arg_strings = file_arg_strings + new_arg_strings
+                except OSError:
+                    err = sys.exc_info()[1]
+                    self.error(str(err))
+        # return the modified argument list
+        return new_arg_strings
+    
+    def print_usage(self, file=None):
+        """
+        Overridded method of argparse.ArgumentParser class.
+
+        Prints the usage message for the argparse.ArgumentParser object.
+        An example format for an arguments file input as been appended
+
+        :param file: a file to print this usage message to (defaults to sys.stdout if None)
+        :type file: IO[str]
+        """
+        if file is None:
+            file = sys.stdout
+        self._print_message(self.format_usage().rstrip("\n") + "  @[ARG_FILE]\n", 
+                            file)
+
+class NoOverride(argparse.Action):
+    """
+        Custom class that inherits from the argparse.Action class.
+
+        Creates a custom action for an argument that doesn't allow namespace
+        values to be overridden by later inputs
+        """
+    def __call__(self, parser, namespace, values, option_string=None):
+        breakpoint()
+        if getattr(namespace, self.dest, None) == None:
+                setattr(namespace, self.dest, values)