nifti2bids 0.1.2__py3-none-any.whl

nifti2bids/__init__.py

@@ -0,0 +1,20 @@
+"""
+Post-hoc BIDS conversion toolkit for NIfTI datasets without original DICOMs.
+----------------------------------------------------------------------------
+Documentation can be found at https://nifti2bids.readthedocs.io.
+
+Submodules
+----------
+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 metadata information from NIfTI images
+
+simulate -- Simulate a basic NIfTI image for testing purposes
+"""
+
+__version__ = "0.1.2"

nifti2bids/_decorators.py

@@ -0,0 +1,53 @@
+"""Decorator functions."""
+
+import functools, inspect
+
+from typing import Any, Callable
+
+from ._helpers import list_to_str
+
+
+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"{list_to_str(invalid_params)}."
+            )
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Callable:
+            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: {list_to_str(parameter_names)}."
+                )
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

nifti2bids/_exceptions.py

@@ -0,0 +1,51 @@
+"""Custom exceptions."""
+
+from typing import Literal, Optional
+
+
+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: Optional[str] = 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

nifti2bids/_helpers.py

@@ -0,0 +1,6 @@
+"""Helper functions."""
+
+
+def list_to_str(str_list: list[str]) -> None:
+    """Converts a list containing strings to a string."""
+    return ", ".join(["'{a}'".format(a=x) for x in str_list])

nifti2bids/bids.py

@@ -0,0 +1,192 @@
+"""Module for creating BIDS compliant files."""
+
+import os, json
+from typing import Optional
+
+import pandas as pd
+
+from nifti2bids.io import _copy_file, glob_contents
+
+
+def create_bids_file(
+    nifti_file: str,
+    subj_id: str | int,
+    desc: str,
+    ses_id: Optional[str | int] = None,
+    task_id: Optional[str] = None,
+    run_id: Optional[str | int] = None,
+    dst_dir: str = None,
+    remove_src_file: bool = False,
+    return_bids_filename: bool = False,
+) -> str | None:
+    """
+    Create a BIDS compliant filename with required and optional entities.
+
+    Parameters
+    ----------
+    nifti_file: :obj:`str`
+        Path to NIfTI image.
+
+    sub_id: :obj:`str` or :obj:`int`
+        Subject ID (i.e. 01, 101, etc).
+
+    desc: :obj:`str`
+        Description of the file (i.e., T1w, bold, etc).
+
+    ses_id: :obj:`str` or :obj:`int` or :obj:`None`, default=None
+        Session ID (i.e. 001, 1, etc). Optional entity.
+
+    ses_id: :obj:`str` or :obj:`int` or :obj:`None`, default=None
+        Session ID (i.e. 001, 1, etc). Optional entity.
+
+    task_id: :obj:`str` or :obj:`None`, default=None
+        Task ID (i.e. flanker, n_back, etc). Optional entity.
+
+    run_id: :obj:`str` or :obj:`int` or :obj:`None`, default=None
+        Run ID (i.e. 001, 1, etc). Optional entity.
+
+    dst_dir: :obj:`str`, default=None
+        Directory name to copy the BIDS file to. If None, then the
+        BIDS file is copied to the same directory as
+
+    remove_src_file: :obj:`str`, default=False
+        Delete the source file if True.
+
+    return_bids_filename: :obj:`str`, default=False
+        Returns the full BIDS filename if True.
+
+    Returns
+    -------
+    None or str
+        If ``return_bids_filename`` is True, then the BIDS filename is
+        returned.
+
+    Note
+    ----
+    There are additional entities that can be used that are
+    not included in this function.
+    """
+    bids_filename = f"sub-{subj_id}_ses-{ses_id}_task-{task_id}_" f"run-{run_id}_{desc}"
+    bids_filename = _strip_none_entities(bids_filename)
+
+    ext = f"{nifti_file.partition('.')[-1]}"
+    bids_filename += f"{ext}"
+    bids_filename = (
+        os.path.join(os.path.dirname(nifti_file), bids_filename)
+        if dst_dir is None
+        else os.path.join(dst_dir, bids_filename)
+    )
+
+    _copy_file(nifti_file, bids_filename, remove_src_file)
+
+    return bids_filename if return_bids_filename else None
+
+
+def _strip_none_entities(bids_filename: str) -> str:
+    """
+    Removes entities with None in a BIDS compliant filename.
+
+    Parameters
+    ----------
+    bids_filename: :obj:`str`
+        The BIDS filename.
+
+    Returns
+    -------
+    str
+        BIDS filename with entities ending in None removed.
+
+    Example
+    -------
+    >>> from bidsrep.io import _strip_none_entities
+    >>> bids_filename = "sub-101_ses-None_task-flanker_bold.nii.gz"
+    >>> _strip_none_entities(bids_filename)
+        "sub-101_task-flanker_bold.nii.gz"
+    """
+    basename, _, ext = bids_filename.partition(".")
+    retained_entities = [
+        entity for entity in basename.split("_") if not entity.endswith("-None")
+    ]
+
+    return f"{'_'.join(retained_entities)}.{ext}"
+
+
+def create_dataset_description(dataset_name: str, bids_version: str = "1.0.0") -> dict:
+    """
+    Generate a dataset description dictionary.
+
+    Creates a dictionary containing the name and BIDs version of a dataset.
+
+    .. versionadded:: 0.34.1
+
+    Parameters
+    ----------
+    dataset_name: :obj:`str`
+        Name of the dataset.
+
+    bids_version: :obj:`str`,
+        Version of the BIDS dataset.
+
+    derivative: :obj:`bool`, default=False
+        Determines if "GeneratedBy" key is added to dictionary.
+
+    Returns
+    -------
+    dict
+        The dataset description dictionary
+    """
+    return {"Name": dataset_name, "BIDSVersion": bids_version}
+
+
+def save_dataset_description(dataset_description: dict[str, str], dst_dir: str) -> None:
+    """
+    Save a dataset description dictionary.
+
+    Saves the dataset description dictionary as a file named "dataset_description.json" to the
+    directory specified by ``output_dir``.
+
+    Parameters
+    ----------
+    dataset_description: :obj:`dict`
+        The dataset description dictionary.
+
+    dst_dir: :obj:`str`
+        Path to save the JSON file to.
+    """
+    with open(
+        os.path.join(dst_dir, "dataset_description.json"), "w", encoding="utf-8"
+    ) as f:
+        json.dump(dataset_description, f)
+
+
+def create_participant_tsv(
+    bids_dir: str, save_df: bool = False, return_df: bool = True
+) -> pd.DataFrame | None:
+    """
+    Creates a basic participant dataframe for the "participants.tsv" file.
+
+    Parameters
+    ----------
+    bids_dir: :obj:`str`
+        The root of BIDS compliant directory.
+
+    save_df: :obj:`bool`, bool=False
+        Save the dataframe to the root of the BIDS compliant directory.
+
+    return_df: :obj:`str`
+        Whether or not to return the dataframe.
+
+    Returns
+    -------
+    pd.DataFrame or None
+        The dataframe if ``return_df`` is True.
+    """
+    participants = [
+        os.path.basename(folder) for folder in glob_contents(bids_dir, "*sub-*")
+    ]
+    df = pd.DataFrame({"participant_id": participants})
+
+    if save_df:
+        df.to_csv(os.path.join(bids_dir, "participants.tsv"), sep="\t", index=None)
+
+    return df if return_df else None

nifti2bids/io.py

@@ -0,0 +1,135 @@
+"""Module for input/output operations."""
+
+import glob, os, shutil
+
+import nibabel as nib
+
+
+def load_nifti(
+    nifti_file_or_img: str | nib.nifti1.Nifti1Image,
+) -> nib.nifti1.Nifti1Image:
+    """
+    Loads a NIfTI image.
+
+    Loads NIfTI image when not a ``Nifti1Image`` object or
+    returns the image if already loaded in.
+
+    Parameters
+    ----------
+    nifti_file_or_img: :obj:`str` or :obj:`Nifti1Image`
+        Path to the NIfTI file or a NIfTI image.
+
+    Returns
+    -------
+    nib.nifti1.Nifti1Image
+        The loaded in NIfTI image.
+    """
+    nifti_img = (
+        nifti_file_or_img
+        if isinstance(nifti_file_or_img, nib.nifti1.Nifti1Image)
+        else nib.load(nifti_file_or_img)
+    )
+
+    return nifti_img
+
+
+def compress_image(nifti_file: str, remove_src_file: bool = False) -> None:
+    """
+    Compresses a ".nii" image to a ".nii.gz" image.
+
+    Parameters
+    ----------
+    nifti_file: :obj:`str`
+        Path to the NIfTI image.
+
+    remove_src_file: :obj:`bool`
+        Deletes the original source image file.
+
+    Returns
+    -------
+    None
+    """
+    img = nib.load(nifti_file)
+    nib.save(img, nifti_file.replace(".nii", ".nii.gz"))
+
+    if remove_src_file:
+        os.remove(nifti_file)
+
+
+def glob_contents(src_dir: str, pattern: str) -> list[str]:
+    """
+    Use glob to get contents with specific patterns.
+
+    Parameters
+    ----------
+    src_dir: :obj:`str`
+        The source directory.
+
+    ext: :obj:`str`
+        The extension.
+
+    Returns
+    -------
+    list[str]
+        List of contents with the pattern specified by ``pattern``.
+    """
+    return glob.glob(os.path.join(src_dir, f"*{pattern}"))
+
+
+def get_nifti_header(nifti_file_or_img):
+    """
+    Get header from a NIfTI image.
+
+    Parameters
+    ----------
+    nifti_file_or_img: :obj:`str` or :obj:`Nifti1Image`
+        Path to the NIfTI file or a NIfTI image.
+
+    Returns
+    -------
+    nib.nifti1.Nifti1Image
+        The header from a NIfTI image.
+    """
+    return load_nifti(nifti_file_or_img).header
+
+
+def get_nifti_affine(nifti_file_or_img):
+    """
+    Get the affine matrix from a NIfTI image.
+
+    Parameters
+    ----------
+    nifti_file_or_img: :obj:`str` or :obj:`Nifti1Image`
+        Path to the NIfTI file or a NIfTI image.
+
+    Returns
+    -------
+    nib.nifti1.Nifti1Image
+        The header from a NIfTI image.
+    """
+    return load_nifti(nifti_file_or_img).affine
+
+
+def _copy_file(src_file: str, dst_file: str, remove_src_file: bool) -> None:
+    """
+    Copy a file and optionally remove the source file.
+
+    Parameters
+    ----------
+    src_file: :obj:`str`
+        The source file to be copied
+
+    dst_file: :obj:`str`
+        The new destination file.
+
+    remove_src_file: :obj:`bool`
+        Delete the source file if True.
+
+    Returns
+    -------
+    None
+    """
+    shutil.copy(src_file, dst_file)
+
+    if remove_src_file:
+        os.remove(src_file)

nifti2bids/logging.py

@@ -0,0 +1,86 @@
+"""Module for logging."""
+
+import logging
+from typing import Optional
+
+from rich.logging import RichHandler
+
+
+def setup_logger(
+    logger_name: str = None, level: Optional[int] = None
+) -> logging.Logger:
+    """
+    Sets up the logger.
+
+    .. note::
+       Defaults to ``RichHandler`` if a module or root handler is
+       not detected.
+
+    Parameters
+    ----------
+    logger_name: :obj:`str`
+        Name of the logger to return, if None, the root logger is returned.
+
+    level: :obj:`int` or :obj:`None`
+        The logging level. If None, the logging level is not set
+
+    Returns
+    -------
+    Logger
+        A ``Logger`` object.
+    """
+    logger = logging.getLogger(logger_name)
+    if not _has_handler(logger):
+        logger = _add_default_handler(logger)
+
+    if level:
+        logger.setLevel(level)
+
+    return logger
+
+
+def _has_handler(logger):
+    """
+    Check if a handler is present.
+
+    Checks the root logger and module logger.
+
+    logger: :obj:`Logger`
+        A logging object.
+
+    Returns
+    -------
+    bool
+        True if a handler is present and False if no handler is present
+    """
+    has_root_handler = logging.getLogger().hasHandlers()
+    has_module_handler = bool(logger.handlers)
+
+    return True if (has_root_handler or has_module_handler) else False
+
+
+def _add_default_handler(logger: logging.Logger, format: str | None = None):
+    """
+    Add a default and format handler. Uses ``RichHandler`` as the default logger.
+
+    Parameters
+    ----------
+    logger: :obj:`Logger`
+        A logging object.
+
+    format: :obj:`str`
+        String specifying the format of the logged message.
+
+    Returns
+    -------
+    Logger
+        A logger object.
+    """
+
+    format = format if format else "%(asctime)s %(name)s [%(levelname)s] %(message)s"
+
+    handler = RichHandler()
+    handler.setFormatter(logging.Formatter(format))
+    logger.addHandler(handler)
+
+    return logger