nifti2bids 0.0.9__tar.gz

nifti2bids-0.0.9/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Donisha Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nifti2bids-0.0.9/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: nifti2bids
+Version: 0.0.9
+Summary: Post-hoc BIDS conversion toolkit for NIfTI datasets without original DICOMs.
+Author-email: Donisha Smith <dsmit420@jhu.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://nifti2bids.readthedocs.io
+Project-URL: Github, https://github.com/donishadsmith/nifti2bids
+Project-URL: Issues, https://github.com/donishadsmith/nifti2bids/issues
+Project-URL: Changelog, https://nifti2bids.readthedocs.io/en/stable/changelog.html
+Keywords: python,neuroimaging,fMRI,MRI,BIDS,NIfTI
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.10.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.3
+Requires-Dist: nibabel>=5.0.0
+Requires-Dist: rich>=14.2.0
+Requires-Dist: nilearn>=0.10.4
+Requires-Dist: pandas>=2.1.0
+Provides-Extra: all
+Requires-Dist: nifti2bids[test]; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+# Nifti2Bids
+
+[![Latest Version](https://img.shields.io/pypi/v/nifti2bids.svg)](https://pypi.python.org/pypi/nifti2bids/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/nifti2bids.svg)](https://pypi.python.org/pypi/nifti2bids/)
+[![Source Code](https://img.shields.io/badge/Source%20Code-nifti2bids-purple)](https://github.com/donishadsmith/nifti2bids)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Test Status](https://github.com/donishadsmith/nifti2bids/actions/workflows/testing.yaml/badge.svg)](https://github.com/donishadsmith/nifti2bids/actions/workflows/testing.yaml)
+[![codecov](https://codecov.io/gh/donishadsmith/nifti2bids/graph/badge.svg?token=PCJ17NA627)](https://codecov.io/gh/donishadsmith/nifti2bids)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Documentation Status](https://readthedocs.org/projects/nifti2bids-py/badge/?version=latest)](http://nifti2bids.readthedocs.io/en/latest/?badge=latest)
+
+
+A toolkit for post hoc BIDS-ification NIfTI datasets. Includes utilities for metadata extraction, file renaming, and JSON sidecar generation, designed primarily for datasets where the original DICOMs are unavailable.
+
+## Installation
+To install ``nifti2bids`` use one of the following methods:
+
+### Standard Installation
+```bash
+pip install nifti2bids
+```
+
+### Development Version
+
+```bash
+git clone --depth 1 https://github.com/donishadsmith/nifti2bids/
+cd nifti2bids
+pip install -e .
+```

nifti2bids-0.0.9/README.md

@@ -0,0 +1,29 @@
+# Nifti2Bids
+
+[![Latest Version](https://img.shields.io/pypi/v/nifti2bids.svg)](https://pypi.python.org/pypi/nifti2bids/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/nifti2bids.svg)](https://pypi.python.org/pypi/nifti2bids/)
+[![Source Code](https://img.shields.io/badge/Source%20Code-nifti2bids-purple)](https://github.com/donishadsmith/nifti2bids)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Test Status](https://github.com/donishadsmith/nifti2bids/actions/workflows/testing.yaml/badge.svg)](https://github.com/donishadsmith/nifti2bids/actions/workflows/testing.yaml)
+[![codecov](https://codecov.io/gh/donishadsmith/nifti2bids/graph/badge.svg?token=PCJ17NA627)](https://codecov.io/gh/donishadsmith/nifti2bids)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Documentation Status](https://readthedocs.org/projects/nifti2bids-py/badge/?version=latest)](http://nifti2bids.readthedocs.io/en/latest/?badge=latest)
+
+
+A toolkit for post hoc BIDS-ification NIfTI datasets. Includes utilities for metadata extraction, file renaming, and JSON sidecar generation, designed primarily for datasets where the original DICOMs are unavailable.
+
+## Installation
+To install ``nifti2bids`` use one of the following methods:
+
+### Standard Installation
+```bash
+pip install nifti2bids
+```
+
+### Development Version
+
+```bash
+git clone --depth 1 https://github.com/donishadsmith/nifti2bids/
+cd nifti2bids
+pip install -e .
+```

nifti2bids-0.0.9/nifti2bids/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.9"

nifti2bids-0.0.9/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-0.0.9/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-0.0.9/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-0.0.9/nifti2bids/io.py

@@ -0,0 +1,287 @@
+"""Module for input/output operations."""
+
+import glob, json, os, shutil
+from typing import Optional
+
+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)
+
+
+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)

nifti2bids-0.0.9/nifti2bids/logger.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

nifti2bids-0.0.9/nifti2bids/simulate.py

@@ -0,0 +1,59 @@
+"""Module for creating simulated data."""
+
+import nibabel as nib, numpy as np
+
+from numpy.typing import NDArray
+
+
+def simulate_nifti_image(
+    img_shape: tuple[int, int, int] | tuple[int, int, int, int], affine: NDArray = None
+) -> nib.Nifti1Image:
+    """
+    Simulates a NIfTI image.
+
+    Parameters
+    ----------
+    img_shape: :obj:`tuple[int, int, int]` or :obj:`tuple[int, int, int, int]`
+        Shape of the NIfTI image.
+
+    affine: :obj:`NDArray`, default=None
+        The affine matrix.
+
+        .. important::
+           If None, creates an identity matrix.
+
+    Returns
+    -------
+    Nifti1Image
+        The NIfTI image with no header.
+    """
+    if affine is None:
+        affine = create_affine(
+            xyz_diagonal_value=1, translation_vector=np.array([0, 0, 0, 1])
+        )
+
+    return nib.Nifti1Image(np.random.rand(*img_shape), affine)
+
+
+def create_affine(xyz_diagonal_value: int, translation_vector: NDArray) -> NDArray:
+    """
+    Generate an 4x4 affine matrix.
+
+    Parameters
+    ----------
+    xyz_diagonal_value: :obj:`int`
+        The value assigned to the diagonal of the affine for x, y, and z.
+
+    translation_vector: :obj:`NDArray`
+        The translation vector/shift from the origin.
+
+    Returns
+    -------
+    NDArray
+        The affine matrix.
+    """
+    affine = np.zeros((4, 4))
+    np.fill_diagonal(affine[:3, :3], xyz_diagonal_value)
+    affine[:, 3:] = translation_vector[:, np.newaxis]
+
+    return affine