oceanproc 0.1.0__tar.gz

oceanproc-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.1
+Name: oceanproc
+Version: 0.1.0
+Summary: MRI preprocessing for WUSTL Ocean labs
+Author: Ramone Agard
+Author-email: agardr@wustl.edu
+Requires-Python: >=3.10,<3.13
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: asttokens (>=2.4.1,<3.0.0)
+Requires-Dist: beautifulsoup4 (>=4.12.0)
+Requires-Dist: flask (>=3.0.3,<4.0.0)
+Requires-Dist: matplotlib (>=3.9.1,<4.0.0)
+Requires-Dist: nilearn (>=0.10.4,<0.11.0)
+Requires-Dist: numba (>=0.60.0,<0.61.0)
+Requires-Dist: numpy (>=1.26.0)
+Requires-Dist: pandas (>=2.2.2,<3.0.0)
+Requires-Dist: scipy (>=1.13.0)
+Requires-Dist: sphinx-rtd-theme (>=2.0.0,<3.0.0)
+Requires-Dist: torch (>=2.5.1,<3.0.0)
+Requires-Dist: torchaudio (>=2.5.1,<3.0.0)
+Requires-Dist: torchvision (>=0.20.1,<0.21.0)
+Description-Content-Type: text/markdown
+
+# Ocean-Proc
+MRI preprocessing for WUSTL Ocean labs
+

oceanproc-0.1.0/README.md

@@ -0,0 +1,2 @@
+# Ocean-Proc
+MRI preprocessing for WUSTL Ocean labs

oceanproc-0.1.0/oceanproc/__init__.py

@@ -0,0 +1 @@
+__all__ = ["bids_wrapper", "events_long", "group_series", "ocean_proc", "oceanparse"]

oceanproc-0.1.0/oceanproc/bids_wrapper.py

@@ -0,0 +1,331 @@
+#!/usr/bin/env python3
+
+from argparse import ArgumentParser
+from collections import OrderedDict
+from glob import glob
+from pathlib import Path
+import json
+import os
+import re
+import shlex
+import shutil
+import subprocess
+from textwrap import dedent
+import xml.etree.ElementTree as et
+from .utils import exit_program_early, prompt_user_continue, prepare_subprocess_logging, debug_logging, log_linebreak, flags
+import logging
+
+logger = logging.getLogger(__name__)
+
+@debug_logging
+def remove_unusable_runs(xml_file:Path, bids_data_path:Path, subject:str):
+    """
+    Will remove unusable scans from list of scans after dcm2bids has run.
+
+    :param xml_file: Path to XML file containing quality information generated by XNAT.
+    :type xml_file: pathlib.Path
+    :param bids_data_path: Path to directory containing BIDS-compliant data for the given subject.
+    :type bids_data_path: pathlib.Path
+    :param subject: Subject ID used in BIDS-compliant data (for example, if 'sub-5000', subject is '5000').
+    :type subject: str
+
+    """
+    log_linebreak()
+    logger.info("####### Removing the scans marked 'unusable' #######\n")
+
+    if not xml_file.exists():
+        exit_program_early(f"Path {str(xml_file)} does not exist.")
+        
+    tree = et.parse(xml_file)
+    prefix = "{" + str(tree.getroot()).split("{")[-1].split("}")[0] + "}"
+    scan_element_list = list(tree.iter(f"{prefix}scans"))
+    
+    if len(scan_element_list) != 1:
+        exit_program_early(f"Error parsing the xml file provided. Found none or more than one scan groups")
+    
+    scans = scan_element_list[0]
+    quality_pairs = {int(s.get("ID")) : s.find(f"{prefix}quality").text
+                     for s in scans}
+    
+    if len(quality_pairs) == 0:
+        exit_program_early("Could not find scan quality information in the given xml file.") 
+
+    logger.debug(f"scan quality information: {quality_pairs}")
+    
+    json_paths = sorted(list(p for p in (bids_data_path / f"sub-{subject}/").rglob("*.json"))) # if re.search(json_re, p.as_posix()) != None)
+    nii_paths = sorted(list(p for p in (bids_data_path / f"sub-{subject}/").rglob("*.nii.gz"))) # if re.search(json_re, p.as_posix()) != None)
+
+    if len(json_paths) == 0 or len(nii_paths) == 0:
+        exit_program_early("Could not find Nifti or JSON sidecar files in the bids directory.")
+
+    if len(json_paths) != len(nii_paths):
+        exit_program_early("Unequal amount of NIFTI and JSON files found")
+ 
+    for p_json, p_nii in zip(json_paths, nii_paths):
+        j = json.load(p_json.open()) 
+        if quality_pairs[j["SeriesNumber"]] == "unusable":
+            logger.info(f"  Removing series {j['SeriesNumber']}: NIFTI:{p_nii}, JSON:{p_json}")
+            os.remove(p_json) 
+            os.remove(p_nii) 
+
+
+@debug_logging
+def run_dcm2bids(subject:str, 
+                 session:str,
+                 source_dir:Path, 
+                 bids_output_dir:Path, 
+                 config_file:Path, 
+                 nordic_config:Path=None,
+                 nifti:bool=False):
+    """
+    Run dcm2bids with a given set of parameters.
+
+    :param subject: Subject name (ex. 'sub-5000', subject would be '5000')
+    :type subject: str
+    :param session: Session name (ex. 'ses-01', session would be '01')
+    :type session: str
+    :param source_dir: Path to 'sourcedata' directory (or wherever DICOM data is kept).
+    :type source_dir: pathlib.Path
+    :param bids_output_dir: Path to the bids directory to store the newly made NIFTI files
+    :type bids_output_dir: pathlib.Path
+    :param config_file: Path to dcm2bids config file, which maps raw sourcedata to BIDS-compliant counterpart
+    :type config_file: pathlib.Path
+    :param nordic_config: Path to second dcm2bids config file, needed for additional post processing that one BIDS config file can't handle.
+    :type nordic_config: pathlib.Path
+    :param nifti: Specify that the soure directory contains NIFTI files instead of DICOM
+    :type nifti: bool
+    :raise RuntimeError: If dcm2bids exits with a non-zero exit code.
+    """
+
+    for p in [source_dir, bids_output_dir, config_file]:
+        if not p.exists():
+            exit_program_early(f"Path {str(p)} does not exist.")
+
+    if shutil.which('dcm2bids') == None:
+            exit_program_early("Cannot locate program 'dcm2bids', make sure it is in your PATH.")
+    
+    tmp_path = bids_output_dir / f"tmp_dcm2bids/sub-{subject}_ses-{session}"
+    
+    def clean_up(quiet=False):
+        try:
+            logger.debug(f"removing the temporary directory used by dcm2bids: {tmp_path}")
+            shutil.rmtree(tmp_path)
+        except Exception:
+            if not quiet:
+                logger.warning(f"There was a problem deleting the temporary directory at {tmp_path}")
+    
+    if (path_that_exists := bids_output_dir/f"sub-{subject}/ses-{session}").exists():
+        ans = prompt_user_continue(dedent(f"""
+                                    A raw data bids path for this subject and session already exists. 
+                                    Would you like to delete its contents and rerun dcm2bids? If not,
+                                    dcm2bids will be skipped.
+                                          """))
+        if ans:
+            logger.debug("removing the old BIDS raw data directory and its contents")
+            shutil.rmtree(path_that_exists)
+        else:
+            return
+        
+    nifti_path = None    
+    if not nifti:
+        clean_up(quiet=True)
+        run_dcm2niix(source_dir=source_dir, 
+                     tmp_nifti_dir=tmp_path)
+        nifti_path = tmp_path
+    else:
+        nifti_path = source_dir
+    helper_command = shlex.split(f"""{shutil.which('dcm2bids')} 
+                                 --bids_validate 
+                                 --skip_dcm2niix
+                                 -d {str(nifti_path)} 
+                                 -p {subject} 
+                                 -s {session} 
+                                 -c {str(config_file)} 
+                                 -o {str(bids_output_dir)}
+                                 """)
+    try:
+        log_linebreak()
+        logger.info("####### Running first round of Dcm2Bids ########\n")
+        prepare_subprocess_logging(logger)
+        with subprocess.Popen(helper_command, stdout=subprocess.PIPE) as p:    
+            while p.poll() == None:
+                for line in p.stdout:
+                    logger.info(line.decode("utf-8", "ignore"))
+            prepare_subprocess_logging(logger, stop=True)
+            p.kill()
+            if p.poll() != 0:
+                raise RuntimeError("'dcm2bids' has ended with a non-zero exit code.")
+            
+        if nordic_config:
+            if not nordic_config.exists():
+                exit_program_early(f"Path {nordic_config} does not exist.")
+
+            nordic_run_command = shlex.split(f"""{shutil.which('dcm2bids')} 
+                                            --bids_validate
+                                            --skip_dcm2niix
+                                            -d {str(nifti_path)} 
+                                            -p {subject}
+                                            -s {session}
+                                            -c {str(nordic_config)}
+                                            -o {str(bids_output_dir)}
+                                            """)
+            log_linebreak()
+            logger.info("####### Running second round of Dcm2Bids ########\n")
+            prepare_subprocess_logging(logger)
+            with subprocess.Popen(nordic_run_command, stdout=subprocess.PIPE) as p:
+                while p.poll() == None:
+                    for line in p.stdout:
+                        logger.info(line.decode("utf-8", "ignore"))
+                prepare_subprocess_logging(logger, stop=True)
+                p.kill()
+                if p.poll() != 0:
+                    raise RuntimeError("'dcm2bids' has ended with a non-zero exit code.")
+                
+            # Clean up NORDIC files
+            if not flags.debug:
+                separate_nordic_files = glob(f"{str(bids_output_dir)}/sub-{subject}/ses-{session}/func/*_part-*")
+                logger.debug(f"removing the old nordic files that are not needed after mag-phase combination :\n  {separate_nordic_files}")
+                for f in separate_nordic_files:
+                    os.remove(f)
+
+    except RuntimeError or subprocess.CalledProcessError as e:
+        prepare_subprocess_logging(logger, stop=True)
+        logger.exception(e, stack_info=True)
+        exit_program_early("Problem running 'dcm2bids'.", None if flags.debug else clean_up)
+    if not flags.debug:
+        clean_up()
+
+
+@debug_logging
+def run_dcm2niix(source_dir:Path, 
+                 tmp_nifti_dir:Path,
+                 clean_up_func=None):
+    """
+    Run dcm2niix with the given input and output directories.
+
+    :param source_dir: Path to 'sourcedata' directory (or wherever DICOM data is kept).
+    :type source_dir: pathlib.Path
+    :param tmp_nifti_dir: Path to the directory to store the newly made NIFTI files
+    :type tmp_nifti_dir: pathlib.Path
+    """
+    
+    if not source_dir.exists():
+        exit_program_early(f"Path {source_dir} does not exist.")
+    elif shutil.which('dcm2niix') == None:
+        exit_program_early("Cannot locate program 'dcm2niix', make sure it is in your PATH.")
+
+    if not tmp_nifti_dir.exists():
+        tmp_nifti_dir.mkdir(parents=True)
+    
+    helper_command = shlex.split(f"""{shutil.which('dcm2niix')} 
+                                -b y
+                                -ba y
+                                -z y
+                                -f %3s_%f_%p_%t
+                                -o {str(tmp_nifti_dir)}
+                                {str(source_dir)}
+                                """)
+    try: 
+        log_linebreak()
+        logger.info("####### Converting DICOM files into NIFTI #######\n")
+        prepare_subprocess_logging(logger)
+        with subprocess.Popen(helper_command, stdout=subprocess.PIPE) as p:
+            while p.poll() == None:
+                for line in p.stdout:
+                    logger.info(line.decode("utf-8", "ignore"))
+            prepare_subprocess_logging(logger, stop=True)
+            p.kill()
+            if p.poll() != 0:
+                raise RuntimeError("'dcm2bniix' has ended with a non-zero exit code.")
+    except RuntimeError or subprocess.CalledProcessError as e:
+        prepare_subprocess_logging(logger, stop=True)
+        logger.exception(e, stack_info=True)
+        exit_program_early("Problem running 'dcm2niix'.", 
+                           exit_func=clean_up_func if clean_up_func else None)
+        
+    # Delete or move extra files from short runs
+    files_to_remove = list(tmp_nifti_dir.glob("*a.nii.gz")) + list(tmp_nifti_dir.glob("*a.json"))
+    if flags.debug:
+        unused_files_dir = tmp_nifti_dir.parent / f"{tmp_nifti_dir.name}_unused"
+        unused_files_dir.mkdir(exist_ok=True)
+        logger.debug(f"moving some unused files and files created from shortened runs to directory {unused_files_dir}")
+        for f in files_to_remove:
+            shutil.move(f.resolve(), (unused_files_dir/f.name).resolve())
+    else:
+        logger.info(f"removing some unused files and files created from shortened runs :\n  {[str(f) for f in files_to_remove]}")
+        for f in files_to_remove:
+            os.remove(f)
+    
+    
+@debug_logging
+def dicom_to_bids(subject:str, 
+                  session:str, 
+                  source_dir:Path, 
+                  bids_dir:Path, 
+                  xml_path:Path, 
+                  bids_config:Path,
+                  nordic_config:Path=None,
+                  nifti=False):
+    
+    """
+    Facilitates the conversion of DICOM data into NIFTI data in BIDS format, and the removal of data marked 'unusable'.
+
+    :param subject: Subject name (ex. 'sub-5000', subject would be '5000')
+    :type subject: str
+    :param session: Session name (ex. 'ses-01', session would be '01')
+    :type session: str
+    :param source_dir: Path to 'sourcedata' directory (or wherever DICOM data is kept).
+    :type source_dir: pathlib.Path
+    :param bids_dir: Path to the bids directory to store the newly made NIFTI files
+    :type bids_dir: pathlib.Path
+    :param bids_config: Path to dcm2bids config file, which maps raw sourcedata to BIDS-compliant counterpart
+    :type bids_config: pathlib.Path
+    :param nordic_config: Path to second dcm2bids config file, needed for additional post processing if NORDIC data that one BIDS config file can't handle.
+    :type nordic_config: pathlib.Path
+    :param nifti: Specify that the soure directory contains NIFTI files instead of DICOM
+    :type nifti: bool
+    """
+
+    run_dcm2bids(subject=subject, 
+                 session=session,
+                 source_dir=source_dir, 
+                 bids_output_dir=bids_dir, 
+                 config_file=bids_config, 
+                 nordic_config=nordic_config, 
+                 nifti=nifti)
+    
+    remove_unusable_runs(xml_file=xml_path, 
+                         bids_data_path=bids_dir, 
+                         subject=subject)
+
+
+if __name__ == "__main__":
+    parser = ArgumentParser(prog="bids_wrapper.py",
+                                    description="wrapper script for dcm2bids",
+                                    epilog="WIP")
+    parser.add_argument("-su", "--subject", required=True, 
+                        help="Subject ID")
+    parser.add_argument("-se","--session", required=True, 
+                        help="Session ID")
+    parser.add_argument("-sd", "--source_data", type=Path, required=True,
+                        help="Path to directory containing this session's DICOM files")
+    parser.add_argument("-b", "--bids_path", type=Path, required=True, 
+                        help="Path to the bids directory to store the newly made NIFTI files")
+    parser.add_argument("-x", "--xml_path", type=Path, required=True, 
+                        help="Path to this session's XML file")
+    parser.add_argument("-c", "--bids_config", type=Path, required=True, 
+                        help="dcm2bids config json file")
+    parser.add_argument("-n", "--nordic_config", type=Path,
+                        help="Second dcm2bids config json file used for NORDIC processing")
+    parser.add_argument("--nifti", action='store_true', 
+                        help="Flag to specify that the source directory contains files of type NIFTI (.nii/.jsons) instead of DICOM")
+    args = parser.parse_args()
+    
+    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)

oceanproc-0.1.0/oceanproc/events_long.py

@@ -0,0 +1,153 @@
+import pandas as pd
+import numpy as np
+import nibabel as nib
+import json
+import os
+from .utils import exit_program_early, debug_logging, log_linebreak
+from glob import glob
+from pathlib import Path
+import logging
+
+logger = logging.getLogger(__name__)
+
+def find_nearest(array, value):
+    """
+    Finds the smallest difference in 'value' and one of the 
+    elements of 'array', and returns the index of the element
+
+    :param array: a list of elements to compare value to
+    :type array: a list or list-like object
+    :param value: a value to compare to elements of array
+    :type value: integer or float
+    :return: integer index of array
+    :rtype: int
+    """
+    array = np.asarray(array)
+    idx = (np.abs(array - value)).argmin()
+    return(array[idx])
+
+
+@debug_logging
+def make_events_long(bold_run:Path, event_file:Path, output_file:Path, tr:float):
+    """
+    Takes and event file and a funtional run and creates a long formatted events file
+    that maps the onset of task events to a frame of the functional run
+
+    :param bold_run: path to the function run corresponding to the event file
+    :type bold_run: pathlib.Path
+    :param event_file: path to the event timing file
+    :type event_file: pathlib.Path
+    :param output_file: file path (including name) to save the long formatted event file to
+    :type output_file: pathlib.Path
+    :param tr: Repetition time of the function run in seconds
+    :type tr: float
+    """
+    nvols = nib.load(bold_run).dataobj.shape[-1]
+    duration = nvols * tr
+
+    events_df = pd.read_csv(event_file, index_col=None, delimiter="\t")
+    conditions = [s for s in np.unique(events_df.trial_type)]
+    events_long = pd.DataFrame(0, columns=conditions, index=np.arange(0,duration,tr))
+
+    for e in events_df.index:
+        i = find_nearest(events_long.index, events_df.loc[e, "onset"])
+        events_long.loc[i, events_df.loc[e, "trial_type"]] = 1
+        if events_df.loc[e, "duration"] > tr:
+            offset = events_df.loc[e, "onset"] + events_df.loc[e, "duration"]
+            j = find_nearest(events_long.index, offset)
+            if j>i:
+                events_long.loc[j, events_df.loc[e, "trial_type"]] = 1
+
+    events_long.to_csv(output_file)
+
+
+@debug_logging
+def append_to_confounds(confounds_file:Path, fd_thresh:float):
+    """
+    Makes motion outlier regressors based on the framewise
+    displacement threshold, and appends them to the confounds file
+    for this functional run
+
+    :param confounds_file: path to the confounds file for this functional run
+    :type confounds_file: pathlib.Path
+    :param fd_thresh: Framewise displacement threshold for this functional run
+    :type fd_thresh: float
+    """
+    conf_df = pd.read_csv(confounds_file, delimiter="\t")
+    b = 0
+    for a in range(len(conf_df)):
+        if conf_df.loc[a, "framewise_displacement"] > fd_thresh:
+            conf_df[f"spike{b}"] = 0
+            conf_df.loc[a, f"spike{b}"] = 1
+            b += 1
+    
+    conf_df.to_csv(confounds_file, sep="\t")
+    
+
+@debug_logging
+def create_events_and_confounds(bids_path:Path, derivs_path:Path, sub:str, ses:str, fd_thresh:float):
+    """
+    Facilitates the creation of a long formatted events file
+    and the appending of motion outlier regressors to the 
+    confounds file for each functional run for this subject and session
+
+    :param bids_path: Path to the bids directory containing the raw
+    :type bids_path: pathlib.Path
+    :param derivs_path: Path to BIDS-compliant derivatives folder.
+    :type derivs_path: pathlib.Path
+    :param subject: Subject id (
+    :type subject: str
+    :param session: Session id 
+    :type session: str
+    :param fd_thresh: Framewise displacement threshold for this functional run
+    :type fd_thresh: float
+    
+    """
+    log_linebreak()
+    logger.info("####### Creating long formatted event files ########\n")
+
+    bids_func = bids_path / f"sub-{sub}/ses-{ses}/func"
+    derivs_func = derivs_path / f"sub-{sub}/ses-{ses}/func"
+    if not bids_func.is_dir():
+        exit_program_early(f"Cannnot find 'func' - {bids_func} - bids directory for this subject and session")
+    if not derivs_func.is_dir():
+        exit_program_early(f"Cannnot find 'func' - {derivs_func} - derivatives directory for this subject and session")
+
+    event_time_files = list(bids_func.glob("*_events.tsv"))
+    logger.info(f"Found {len(event_time_files)} event timing files")
+    for etf in event_time_files:
+        search_path = f"/sub-{sub}_ses-{ses}*"
+        task = etf.name.split('task-')[-1].split('_')[0]
+        search_path = f"{search_path}task-{task}*"
+        run = None
+        if "run" in etf.name:
+            run = etf.name.split('run-')[-1].split('_')[0].zfill(2)
+            search_path = f"{search_path}run-{run}*"
+        bold_file = list(bids_func.glob(f"{search_path}bold.nii*"))
+        if len(bold_file) < 1:
+            logger.info(f"Could not find any bold files that matched this event timing file: {etf}")
+            continue
+        confounds_file = list(derivs_func.glob(f"{search_path}confounds_timeseries.tsv"))
+        if len(confounds_file) < 1:
+            logger.info(f"Could not find any confounds files that matched this event timing file: {etf}")
+            continue
+        confounds_file = confounds_file[0]
+        bold_file = bold_file[0]
+        side_car = bold_file.split(".")[0] + ".json"
+        tr = None
+        with open(side_car, "r") as f:
+            jd = json.load(f)
+            tr = jd["RepetitionTime"]
+
+        event_file_out = derivs_func / f"sub-{sub}_ses-{ses}_task-{task}_{f'run-{run}' if run else ''}_desc-events_long.csv"
+        make_events_long(bold_run=bold_file, 
+                         event_file=etf, 
+                         output_file=event_file_out, 
+                         tr=tr)
+        append_to_confounds(confounds_file=confounds_file, 
+                            fd_thresh=fd_thresh)
+        
+
+
+
+