nifti2bids 0.2.7__tar.gz

nifti2bids-0.2.7/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.2.7/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: nifti2bids
+Version: 0.2.7
+Summary: Post-hoc BIDS conversion toolkit for unstructured NIfTI datasets.
+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/badge/?version=stable)](http://nifti2bids.readthedocs.io/en/stable/?badge=stable)
+
+
+A toolkit for post hoc BIDS-ification unstructured 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.2.7/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/badge/?version=stable)](http://nifti2bids.readthedocs.io/en/stable/?badge=stable)
+
+
+A toolkit for post hoc BIDS-ification unstructured 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.2.7/nifti2bids/__init__.py

@@ -0,0 +1,23 @@
+"""
+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 or creating metadata information from NIfTI images
+
+parsers -- Operations related to standardizing and parsing information logs created by stimulus
+presentation software such as Presentation
+
+simulate -- Simulate a basic NIfTI image for testing purposes
+"""
+
+__version__ = "0.2.7"

nifti2bids-0.2.7/nifti2bids/_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=\t
+VarSeparator=\t
+BegDataLine=0
+EndDataLine=0
+MissingData=nan
+Unicode=0
+"""

nifti2bids-0.2.7/nifti2bids/_decorators.py

@@ -0,0 +1,82 @@
+"""Decorator functions."""
+
+import functools, inspect
+
+from typing import Any, Callable, Optional
+
+from ._helpers import list_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"{list_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: {list_to_str(parameter_names)}."
+                )
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def check_nifti(nifti_param_name: Optional[str] = None) -> Callable:
+    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

nifti2bids-0.2.7/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.2.7/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.2.7/nifti2bids/bids.py

@@ -0,0 +1,313 @@
+"""Module for creating BIDS compliant files."""
+
+import json
+from pathlib import Path
+from typing import Literal, Optional
+
+import pandas as pd
+import numpy as np
+
+from nifti2bids.io import _copy_file, glob_contents
+from nifti2bids.parsers import load_presentation_log, _convert_time
+
+
+def create_bids_file(
+    nifti_file: str | Path,
+    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 | Path = None,
+    remove_src_file: bool = False,
+    return_bids_filename: bool = False,
+) -> Path | None:
+    """
+    Create a BIDS compliant filename with required and optional entities.
+
+    Parameters
+    ----------
+    nifti_file: :obj:`str` or :obj:`Path`
+        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`, :obj:`Path`, or :obj:`None`, 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
+    -------
+    Path or None
+        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"{str(nifti_file).partition('.')[-1]}"
+    bids_filename += f"{ext}"
+    bids_filename = (
+        Path(nifti_file).parent / bids_filename
+        if dst_dir is None
+        else Path(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 | Path) -> str:
+    """
+    Removes entities with None in a BIDS compliant filename.
+
+    Parameters
+    ----------
+    bids_filename: :obj:`str` or :obj:`Path`
+        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 = str(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[str, str]:
+    """
+    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[str, str]
+        The dataset description dictionary
+    """
+    return {"Name": dataset_name, "BIDSVersion": bids_version}
+
+
+def save_dataset_description(
+    dataset_description: dict[str, str], dst_dir: str | Path
+) -> 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` or :obj:`Path`
+        Path to save the JSON file to.
+    """
+    with open(Path(dst_dir) / "dataset_description.json", "w", encoding="utf-8") as f:
+        json.dump(dataset_description, f)
+
+
+def create_participant_tsv(
+    bids_dir: str | Path, 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` or :obj:`Path`
+        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`
+        Returns dataframe if True else return None.
+
+    Returns
+    -------
+    pd.DataFrame or None
+        The dataframe if ``return_df`` is True.
+    """
+    participants = [folder.name for folder in glob_contents(bids_dir, "*sub-*")]
+    df = pd.DataFrame({"participant_id": participants})
+
+    if save_df:
+        df.to_csv(Path(bids_dir) / "participants.tsv", sep="\t", index=None)
+
+    return df if return_df else None
+
+
+def presentation_log_to_bids(
+    presentation_log_or_df: str | Path | pd.DataFrame,
+    convert_to_seconds: Optional[list[str]],
+    trial_types: Optional[list[str]],
+    experimental_design: Literal["block", "event"],
+    rest_block_code: Optional[list[str]] = None,
+    include_response: bool = False,
+    initial_column_headers: tuple[str] = ("Trial", "Event Type"),
+) -> pd.DataFrame:
+    """
+    Creates BIDs compliant events dataframe from Presentation log or dataframe.
+
+    Parameters
+    ----------
+    presentation_log_or_df: :obj:`str`, :obj:`Path`, :obj:`pd.DataFrame`
+        The presentation log as a file path or the presentation DataFrame
+        returned by :code:`nifti2bids.parsers.load_presentation_log`.
+
+    convert_to_seconds: :obj:`list[str]` or :obj:`None`, default=None
+        Convert the time resolution of the specified columns from 0.1ms to seconds.
+
+        .. note:: Recommend time resolution of the "Time" column to be converted.
+
+    trial_types: :obj:`list[str]` or :obj:`None`
+        The names of the trial types (i.e "congruentleft", "seen").
+        If None, the code will identify the trial types.
+
+        .. important::
+        ``trial_types=["congruent", "incongruent"]`` will identify
+        all trial types beginning with "congruent" and "incongruent"
+
+    experiment_design: :obj:`Literal["block", "event"]
+        The experimental design. Options are "block" or "event".
+
+        .. important::
+           Duration for "block" is computed as the difference between the
+           start of the block and the start of the interstimulus time.
+           The duration of "event" is computed as the difference between
+           the event stimulus and the response.
+
+    rest_block_code: :obj:`str`, default=None
+        The name of the code for the rest block. Only used
+        when ``experiment_design`` is "block".
+
+    include_response: :obj:`bool`, default=False
+        Includes a response column. Only used when
+        ``experiment_design`` is "event".
+
+    initial_column_headers: :obj:`tuple[str]`, default=("Trial", "Event Type")
+        The initial column headers for data. Only used when
+        ``presentation_log_or_df`` is a file path.
+
+    Returns
+    -------
+    pandas.DataFrame
+        The event dataframe which includes columns specifying the onset, duration,
+        and trial type. If ``include_response`` is True and ``experimental_design``
+        is True then a "response" column is added.
+    """
+    assert experimental_design in [
+        "event",
+        "block",
+    ], "Valid inputs for ``experimental_design`` are 'event' and 'block'."
+    assert not (
+        experimental_design == "block" and rest_block_code is None
+    ), "``rest_block_code` cannot be None when ``experimental_design`` is 'block'."
+
+    if not isinstance(presentation_log_or_df, pd.DataFrame):
+        presentation_df = load_presentation_log(
+            presentation_log_or_df,
+            convert_to_seconds=convert_to_seconds,
+            initial_column_headers=tuple(initial_column_headers),
+        )
+    elif convert_to_seconds:
+        presentation_df = _convert_time(
+            presentation_df, convert_to_seconds=convert_to_seconds, divisor=10000
+        )
+    else:
+        presentation_df = presentation_log_or_df
+
+    if experimental_design == "block":
+        rest_block_indxs = presentation_df[
+            presentation_df["Code"].str.startswith(rest_block_code)
+        ].index.tolist()
+        rest_block_indxs = np.array(rest_block_indxs)
+
+    # Get the first pulse which corresponds to scanner start time
+    scanner_start = presentation_df.loc[
+        presentation_df["Event Type"] == "Pulse", "Time"
+    ].values[0]
+    events = []
+    for row_indx, row in presentation_df.iterrows():
+        onset = row["Time"] - scanner_start
+        if row["Event Type"] == "Picture" and row["Code"].startswith(
+            tuple(trial_types)
+        ):
+            if experimental_design == "event":
+                trial_num = row["Trial"]
+                response_row = presentation_df[
+                    (presentation_df["Trial"] == trial_num)
+                    & (presentation_df["Event Type"] == "Response")
+                ]
+                duration = response_row.iloc[0]["Time"] - row["Time"]
+                response = row["Stim Type"]
+            else:
+                rest_indx = rest_block_indxs[rest_block_indxs > row_indx][0]
+                rest_row = presentation_df.loc[rest_indx, :]
+                duration = rest_row["Time"] - row["Time"]
+
+            data = {"onset": onset, "duration": duration, "trial_type": row["Code"]}
+            if experimental_design == "event" and include_response:
+                data.update({"response": response})
+
+            events.append(data)
+
+    return pd.DataFrame(events)