bidsaid 0.20.0__py3-none-any.whl

bidsaid/__init__.py

@@ -0,0 +1,27 @@
+"""
+Post-hoc BIDS toolkit for NIfTI datasets without original DICOMs.
+-----------------------------------------------------------------
+Documentation can be found at https://bidsaid.readthedocs.io.
+
+Submodules
+----------
+audit -- Contains the ``BIDSAuditor`` class to check for certain file availability
+
+bids -- Operations related to initializing and creating BIDS compliant files
+
+io -- Generic operations related to loading NIfTI data
+
+logging -- Set up a logger using ``RichHandler`` as the default handler if a root or
+module specific handler is not available
+
+metadata -- Operations related to extracting or creating metadata information from NIfTI images
+
+parsers -- Operations related to standardizing and parsing information logs created by stimulus
+neurobehavioral software such as Presentation and EPrime
+
+qc -- Quality control utilities for fMRI data (motion censoring, framewise displacement, etc.)
+
+simulate -- Simulate a basic NIfTI image or BIDS dataset for testing purposes
+"""
+
+__version__ = "0.20.0"

bidsaid/_constants.py

@@ -0,0 +1,24 @@
+"""
+Module for constants.
+
+Note: The CLI command for converting edat3 files to text files can be found at the
+following link: https://support.pstnet.com/hc/en-us/articles/360020316014-DATA-Using-E-DataAid-exe-with-Command-Line-Interpreters-25323
+"""
+
+EDATAAID_PATH = r"C:\Program Files (x86)\PST\E-Prime 3.0\Program\E-DataAid.exe"
+
+EDATAAID_CONTROL_FILE = """Inheritance=NULL
+InFile={edat_path}
+OutFile={dst_path}
+ColFlags=0
+ColNames=1
+Comments=0
+BegCommentLine=0
+EndCommentLine=0
+DataSeparator={delimiter}
+VarSeparator={delimiter}
+BegDataLine=0
+EndDataLine=0
+MissingData=nan
+Unicode=0
+"""

bidsaid/_decorators.py

@@ -0,0 +1,97 @@
+"""Decorator functions."""
+
+import functools, inspect
+
+from typing import Any, Callable
+
+from ._helpers import iterable_to_str
+from .io import get_nifti_header
+
+
+def check_all_none(parameter_names: list[str]) -> Callable:
+    """
+    Checks if specific parameters are assigned ``None``.
+
+    Parameters
+    ----------
+    parameter_names : :obj:`list[str]`
+        List of parameter names to check.
+
+    Returns
+    -------
+    Callable
+        Decorator function wrapping target function.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        signature = inspect.signature(func)
+        if invalid_params := [
+            param
+            for param in parameter_names
+            if param not in signature.parameters.keys()
+        ]:
+            raise NameError(
+                "Error in ``parameter_names`` of decorator. The following "
+                f"parameters are not in the signature of '{func.__name__}': "
+                f"{iterable_to_str(invalid_params)}."
+            )
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            bound_args = signature.bind(*args, **kwargs)
+            bound_args.apply_defaults()
+            all_param_values = [bound_args.arguments[name] for name in parameter_names]
+            if all(value is None for value in all_param_values):
+                raise ValueError(
+                    "All of the following arguments cannot be None, "
+                    f"one must be specified: {iterable_to_str(parameter_names)}."
+                )
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def check_nifti(nifti_param_name: str | None = None) -> Callable:
+    """
+    Checks if input NIfTI has qform or sform codes set to scanner.
+
+    Parameters
+    ----------
+    nifti_param_name : :obj:`list[str]`
+        Name of the NIfTI parameter. If None, assumes the
+        NIfTI parameter is "nifti_file_or_img".
+
+    Returns
+    -------
+    Callable
+        Decorator function wrapping target function.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            bound_args = inspect.signature(func).bind(*args, **kwargs)
+            bound_args.apply_defaults()
+
+            param_name = (
+                "nifti_file_or_img" if not nifti_param_name else nifti_param_name
+            )
+            img_val = bound_args.arguments.get(param_name)
+            if img_val:
+                hdr = get_nifti_header(img_val)
+
+                # sform takes precedence over qform
+                code = "sform_code" if hdr["sform_code"] else "qform_code"
+                if hdr[code] != 1:
+                    raise ValueError(
+                        f"The {code} is not set to 'scanner' and is not a raw NIfTI image."
+                    )
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

bidsaid/_exceptions.py

@@ -0,0 +1,60 @@
+"""Custom exceptions."""
+
+from typing import Literal
+
+
+class SliceAxisError(Exception):
+    """
+    Incorrect slice axis.
+
+    Raised when the number of slices does not match "slice_end" plus one.
+
+    Parameters
+    ----------
+    slice_axis : :obj:`Literal["x", "y", "z"]`
+        The specified slice dimension.
+
+    n_slices : :obj:`int`
+        The number of slices from the specified ``slice_axis``.
+
+    slice_end : :obj:`int`
+        The number of slices specified by "slice_end" in the NIfTI header.
+
+    message : :obj:`str` or :obj:`None`:
+        The error message. If None, a default error message is used.
+    """
+
+    def __init__(
+        self,
+        slice_axis: Literal["x", "y", "z"],
+        n_slices: int,
+        slice_end: int,
+        message: str | None = None,
+    ):
+        if not message:
+            self.message = (
+                "Incorrect slice axis. Number of slices for "
+                f"{slice_axis} dimension is {n_slices} but "
+                f"'slice_end' in NIfTI header is {slice_end}."
+            )
+        else:
+            self.message = message
+
+        super().__init__(self.message)
+
+
+class DataDimensionError(Exception):
+    """
+    Incorrect data dimensionality.
+    """
+
+    pass
+
+
+class PathDoesNotExist(Exception):
+    """Exception when path does not exist."""
+
+    def __init__(self, path):
+        self.message = f"The following path does not exist: {path}"
+
+        super().__init__(self.message)

bidsaid/_helpers.py

@@ -0,0 +1,14 @@
+"""Helper functions."""
+
+from pathlib import Path
+from typing import Any
+
+
+def iterable_to_str(str_list: list[str]) -> None:
+    """Converts an iterable containing strings to strings."""
+    return ", ".join(["'{a}'".format(a=x) for x in str_list])
+
+
+def is_path(object: Any) -> bool:
+    "Determine if input is a Path or string."
+    return isinstance(object, (str, Path))