oceanfla 0.1.0__tar.gz

oceanfla-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.1
+Name: oceanfla
+Version: 0.1.0
+Summary: First level analysis for WUSTL Ocean labs
+Author-Email: Ramone Agard <rhagard@wustl.edu>, Joey Scanga <joeyscanga92@gmail.com>
+Requires-Python: <3.13,>=3.10
+Requires-Dist: sphinx-rtd-theme<3.0.0,>=2.0.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pandas<3.0.0,>=2.2.2
+Requires-Dist: nilearn<1.0.0,>=0.11.0
+Requires-Dist: scipy>=1.13.0
+Requires-Dist: matplotlib<4.0.0,>=3.9.1
+Requires-Dist: pybids==0.16.4
+Requires-Dist: nipype>=1.10.0
+Requires-Dist: niworkflows>=1.14.3
+Description-Content-Type: text/markdown
+
+# oceanfla
+First level analysis package for Ocean Labs

oceanfla-0.1.0/README.md

@@ -0,0 +1,2 @@
+# oceanfla
+First level analysis package for Ocean Labs

oceanfla-0.1.0/oceanfla/config.py

@@ -0,0 +1,212 @@
+from pathlib import Path
+import bids
+import json
+import multiprocessing
+import logging
+from logging.handlers import QueueHandler
+
+
+class Options():
+    '''
+    A singleton class designed to be the holder of all user parsed arguments.
+    This class can only be initialized once, afterward, the same instance is returned.
+    '''
+    _instance = None
+    _initialized = False
+    layouts = []
+    logger_names = ["nipype.workflow", "nipype.utils", "nipype.interface"]
+    generic_nuisance_columns = ["mean", "trend", "spike"]
+    _pattern_file = Path(__file__).resolve().parent / "resources" / "bids_paths.json"
+    log_format = '%(asctime)s,%(msecs)d %(name)-2s %(levelname)-2s:\n\t %(message)s'
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self, opts=None):
+        if not self._initialized and opts:
+            # set up the global options
+            option_msg_list = ["User Inputs:", "-"*30]
+
+            for k, v in opts.items():
+                # find the layouts
+                if isinstance(v, bids.BIDSLayout):
+                    self.layouts.append(v)
+                # check for variable regroupings
+                elif k == "group" and v:
+                    option_msg_list.append(f" {k} : {v}")
+                    gmap = dict()
+                    for regroup in v:
+                        group_rename = regroup[-1]
+                        for i in range(len(regroup)-1):
+                            gmap[regroup[i]] = group_rename
+                    setattr(self, k, gmap)
+                    continue
+                else:
+                    option_msg_list.append(f" {k} : {v}")
+                # add the option to the class attributes
+                setattr(self, k, v)
+
+            option_msg_list.append("-"*30)
+
+            # start the logging subprocess
+            log_process, log_queue = config_logging_process(self.log_file, self.log_level, self.log_format)
+            setattr(self, 'log_queue', log_queue)
+            setattr(self, 'log_process', log_process)
+            for log_name in self.logger_names:
+                logger = get_logger(log_name, log_queue)
+                logger.setLevel(self.log_level)
+            
+            # log the arguments used for this run
+            logger = get_logger("nipype.utils")
+            logger.info("\n\t".join(option_msg_list))
+
+            self._initialized = True
+            self.bids_patterns = json.loads(self._pattern_file.read_text())["oceanfla_patterns"]
+    
+
+all_opts = Options()
+
+def set_configs(args):
+    all_opts.__init__(args)
+
+
+def get_layout_for_file(file) -> bids.BIDSLayout:
+    '''
+    Function to return the corresponding bids.BIDSLayout
+    for a given filepath 
+
+    Parameters
+    ----------
+    file: str
+        The path of the file belonging to some BIDSLayout / BIDS directory
+    
+
+    Returns
+    -------
+    bids.BIDSLayout
+        The BIDSLayout object if the file belongs to a parsed BIDS directory
+    
+    '''
+    if isinstance(file, Path):
+        file = str(file.resolve())
+    if isinstance(file, str):
+        file = str(Path(file).resolve())
+    else:
+        raise ValueError(
+            f"argument must be of type Path or str, not {type(file)}")
+
+    for lay in all_opts.layouts:
+        if file.startswith(str(lay._root.resolve())):
+            return lay
+    raise RuntimeError(f"No layout correspond to the input file {file}")
+
+
+
+def get_bids_file(file):
+    '''
+    Function to return the corresponding bids.layout.BIDSFile 
+    for a given filepath 
+
+    Parameters
+    ----------
+    file: str
+        The path of the file to convert
+    
+
+    Returns
+    -------
+    bids.layout.BIDSFile
+        The BIDSFile object or None if it is not found
+    
+    '''
+    if isinstance(file, bids.layout.BIDSFile):
+        return file
+    file_layout = get_layout_for_file(file)
+    return file_layout.get_file(file)
+
+
+def file_log_process(q, log_file, log_level=logging.INFO, log_fmt=None):
+
+    # remove current handlers
+    for logger_name in logging.Logger.manager.loggerDict:
+        logger = logging.getLogger(logger_name)
+        if isinstance(logger, logging.Logger):
+            for handler in logger.handlers[:]:
+                logger.removeHandler(handler)
+                handler.close()
+    # Special handling for the root logger, which is not in loggerDict but is accessible
+    root = logging.getLogger()
+    for handler in root.handlers[:]:
+        root.removeHandler(handler)
+        handler.close()
+
+    file_handler = logging.FileHandler(log_file)
+    fmtr = logging.Formatter(log_fmt)
+    file_handler.setFormatter(fmtr)
+    root.addHandler(file_handler)
+    root.setLevel(log_level)
+
+    while True:
+        try:
+            record = q.get()
+            if record is None:
+                break
+            logger = logging.getLogger(record.name)
+            logger.handle(record)
+        except Exception:
+            msg = "Error in the file logging process"
+            root.error(msg)
+            print(msg)
+            break
+    root.info("closing log file")
+    file_handler.close()
+    
+
+def config_logging_process(log_file, log_level=logging.INFO, log_fmt=None):
+    log_q = multiprocessing.Queue(-1)
+
+    log_process = multiprocessing.Process(target=file_log_process, args=(log_q, log_file, log_level, log_fmt))
+    log_process.start()
+
+    logger = get_logger("nipype.utils", log_q)
+    logger.info("File logging started")
+
+    return log_process, log_q
+
+
+def finish_logging():
+    try: 
+        logger = get_logger('nipype.utils')
+        logger.info("Ending log")
+    except:
+        print("Ending log")
+    finally:
+        if all_opts.log_process:
+            all_opts.log_queue.put_nowait(None)
+            all_opts.log_process.join()
+    logging.shutdown()
+    return
+
+
+def get_logger(name, q=None):
+    if q is None:
+        q = all_opts.log_queue
+    
+    logger = logging.getLogger(name)
+    has_queue_hdlr = any([isinstance(hdlr, QueueHandler) 
+                          for hdlr in logger.handlers])
+    if not has_queue_hdlr:
+        queue_handler = QueueHandler(q)
+        logger.addHandler(queue_handler)
+
+    return logger
+
+
+def close_layouts():
+    for lay in all_opts.layouts:
+        lay.connection_manager.session.close()
+    del all_opts.layouts[:]
+
+

oceanfla-0.1.0/oceanfla/interfaces/clean.py

@@ -0,0 +1,237 @@
+from nipype.interfaces.base import (
+    File,
+    traits,
+)
+from oceanfla.interfaces.utility import ( 
+    OptionalInterface, 
+    OptionalInterfaceSpec,
+)
+
+class _FilterDataInputSpec(OptionalInterfaceSpec):
+    bold_in = File(
+        exists=True, mandatory=True,
+        desc="Path to unfiltered timeseries (as a .nii, .nii.gz, or .dtseries.nii)."
+    )
+    tmask_in = File(
+        exists=True, mandatory=True,
+        desc="Run mask (as a .txt)."
+    )
+    high_pass = traits.Float(
+        default_value=0.008,
+        desc="The lowest frequency allowed (Hz)"
+    )
+    low_pass = traits.Float(
+        default_value=0.1,
+        desc="The highest frequency allowed (Hz)"
+    )
+    tr = traits.Float(
+        desc="The Repetition Time for this BOLD run"
+    )
+    padtype = traits.Str(
+        "mean",
+        desc="Type of padding to use -- choices: 'odd', 'even', 'constant', 'zero', or 'none'"
+    )
+    padlen = traits.Int(
+        50,
+        desc="Length of pad."
+    )
+    brain_mask = traits.Union(
+        traits.File(exists=True),
+        None,
+        default_value=None,
+        desc="The brain mask that accompanies volumetric data"
+    )
+
+
+class _FilterDataOutputSpec(OptionalInterfaceSpec):
+    bold_file = File(
+        exists=True,
+        desc="Filtered timeseries."
+    )
+
+
+class FilterData(OptionalInterface):
+    """
+    Generates a nuisance matrix for regression before final GLM.
+    """
+
+    input_spec = _FilterDataInputSpec
+    output_spec = _FilterDataOutputSpec
+
+    def _run_interface(self, runtime):
+
+        self._results["bold_file"] = filter_data(
+            func_file=self.inputs.bold_in,
+            tmask_file=self.inputs.tmask_in,
+            tr=self.inputs.tr,
+            low_pass=self.inputs.low_pass,
+            high_pass=self.inputs.high_pass,
+            padtype=self.inputs.padtype,
+            padlen=self.inputs.padlen,
+            brain_mask=self.inputs.brain_mask
+        )
+
+        return runtime
+
+
+
+class PercentChangeInputSpec(OptionalInterfaceSpec):
+    bold_in = File(exists=True, mandatory=True,
+                   desc="A BIDS style bold file")
+
+    tmask_in = File(
+        exists=True, mandatory=True,
+        desc="Run mask (as a .txt)."
+    )
+
+    brain_mask = traits.Union(
+        traits.File(exists=True),
+        None,
+        default_value=None,
+        desc="The brain mask that accompanies volumetric data"
+    )
+
+
+class PercentChangeOutputSpec(OptionalInterfaceSpec):
+    bold_file = File(exists=True,
+                     desc="The functional data after a percent signal change transformation")
+
+
+class PercentChange(OptionalInterface):
+    input_spec = PercentChangeInputSpec
+    output_spec = PercentChangeOutputSpec
+
+    def _run_interface(self, runtime):
+
+        self._results["bold_file"] = percent_signal_change(
+            func_file=self.inputs.bold_in,
+            tmask_file=self.inputs.tmask_in,
+            brain_mask=self.inputs.brain_mask
+        )
+
+        return runtime
+    
+
+
+def filter_data(func_file: str,
+                tmask_file: str,
+                tr: float,
+                low_pass: float = 0.1,
+                high_pass: float = 0.008,
+                padtype: str = "mean",
+                padlen: int = 50,
+                brain_mask: str = None):
+    '''
+    Runs a butterworth filter on the data in the input file, using the filter
+    parameters specified. The temporal mask file is used to first censor the input data
+    before interpolating the missing frames, then running the filter.
+
+    Parameters
+    ----------
+    #TODO
+
+    Returns
+    -------
+    #TODO
+    '''
+    from nilearn.signal import butterworth, _handle_scrubbed_volumes
+    from oceanfla.utilities import load_data, create_image_like, replace_entities
+    import numpy as np
+
+    mask = np.loadtxt(tmask_file).astype(bool)
+    func_data = load_data(func_file, brain_mask)
+
+    if not any((
+        padtype == "none",
+        padlen is None,
+        (padtype != "zero" and padlen is not None and padlen > 0),
+        (padtype == "zero" and padlen is not None and padlen >= 2),
+    )):
+        raise ValueError(
+            f"Pad length of {padlen} incompatible with pad type {'odd' if padtype is None else padtype}")
+
+    padded_func_data = func_data
+    if padtype == "even":
+        padded_func_data = np.pad(
+            func_data, ((padlen, padlen), (0, 0)), mode='reflect')
+    elif padtype == "odd":
+        padded_func_data = np.pad(
+            func_data, ((padlen, padlen), (0, 0)), mode='reflect', reflect_type="odd")
+    elif padtype == "mean":
+        masked_mean = np.nanmean(func_data[mask], axis=0)
+        pad_arr = np.full(
+            shape=(padlen, func_data.shape[1]), fill_value=masked_mean)
+        padded_func_data = np.concatenate(
+            [pad_arr.copy(), func_data, pad_arr], axis=0)
+    elif padtype == "zero":
+        padded_func_data = np.pad(
+            func_data, ((padlen, padlen), (0, 0)), mode='constant', constant_values=0)
+    elif padtype == "edge":
+        padded_func_data = np.pad(
+            func_data, ((padlen, padlen), (0, 0)), mode='edge')
+
+    # padded_func_data = np.pad(func_data, ((padlen, padlen), (0, 0)), mode='mean')
+    padded_mask = np.pad(mask, (padlen, padlen), mode='constant',
+                         constant_values=True) if padtype != "none" else mask
+
+    # if the mask is excluding frames, interpolate the censored frames
+    if np.sum(mask) < mask.shape[0]:
+        padded_func_data, _, padded_mask = _handle_scrubbed_volumes(
+            signals=padded_func_data,
+            confounds=None,
+            sample_mask=padded_mask,
+            filter_type="butterworth",
+            t_r=tr,
+            extrapolate=True
+        )
+
+    filtered_data = butterworth(
+        signals=padded_func_data,
+        sampling_rate=1.0 / tr,
+        low_pass=low_pass,
+        high_pass=high_pass,
+        padtype=None  # if padtype == "none" else padtype,
+    )[padlen:-padlen, :]  # remove 0-pad frames on both sides
+
+    assert filtered_data.shape[0] == func_data.shape[0], "Filtered data must have the same number of timepoints as the original functional data"
+
+    # save data out
+    out_path = replace_entities(
+        file=func_file,
+        entities={"suffix": "filtered-bold", "path": None}
+    )
+    create_image_like(data=filtered_data,
+                      source_header=func_file,
+                      out_file=out_path,
+                      brain_mask=brain_mask)
+    return out_path
+
+
+def percent_signal_change(func_file: str,
+                          tmask_file: str,
+                          brain_mask: str = None):
+    from oceanfla.utilities import load_data, create_image_like, replace_entities
+    import numpy as np
+
+    mask = np.loadtxt(tmask_file).astype(bool)
+    data = load_data(func_file, brain_mask)
+
+    masked_data = data[mask, :]
+    mean = np.nanmean(masked_data, axis=0)
+    mean = np.repeat(mean[np.newaxis, :], data.shape[0], axis=0)
+    psc_data = ((data - mean) / np.abs(mean)) * 100
+    non_valid_indices = np.where(~np.isfinite(psc_data))
+    if len(non_valid_indices[0]) > 0:
+        # logger.warning("Found vertices with zero signal, setting these to zero")
+        psc_data[np.where(~np.isfinite(psc_data))] = 0
+
+    out_path = replace_entities(
+        file=func_file,
+        entities={"suffix": "percent-change-bold", "path": None}
+    )
+    create_image_like(data=psc_data,
+                      source_header=func_file,
+                      out_file=out_path,
+                      brain_mask=brain_mask)
+
+    return out_path