bids-manager 0.1.0__tar.gz

bids_manager-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 BIDS Manager
+
+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.

bids_manager-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include bids_manager/miscellaneous/images *

bids_manager-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: bids-manager
+Version: 0.1.0
+Summary: GUI application to manage BIDS datasets
+Author-email: Karel López Vilaret <karel.mauricio.lopez.vilaret@uni-oldenburg.de>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ANCPLabOldenburg/BIDS-Manager
+Project-URL: Documentation, https://github.com/ANCPLabOldenburg/BIDS-Manager
+Project-URL: Source, https://github.com/ANCPLabOldenburg/BIDS-Manager
+Project-URL: Tracker, https://github.com/ANCPLabOldenburg/BIDS-Manager/issues
+Keywords: BIDS,DICOM,GUI,Neuroimaging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydicom==3.0.1
+Requires-Dist: pandas==2.3.1
+Requires-Dist: PyQt5==5.15.11
+Requires-Dist: PyQtWebEngine==5.15.7
+Requires-Dist: heudiconv-ancp
+Requires-Dist: nipype-ancp
+Requires-Dist: dcm2niix==1.0.20250506
+Requires-Dist: nibabel==5.3.2
+Requires-Dist: numpy==2.2.6
+Requires-Dist: psutil==7.0.0
+Requires-Dist: matplotlib==3.10.3
+Requires-Dist: joblib==1.4.2
+Dynamic: license-file
+
+
+# BIDS Manager
+
+**BIDS Manager** is a **PyQt-based** GUI that converts **DICOM** folders into **BIDS**-compliant datasets and allows easy metadata editing.
+
+---
+
+## Requirements
+
+| Software  | Minimum Version | Notes                                                   |
+|----------|-----------------|---------------------------------------------------------|
+| **Python** | 3.10            | Installed automatically if you use the one-click installers |
+| **Git**    | —               | Must be installed manually (see below)                 |
+
+### Installing Git
+
+| Platform          | Command / Action                                   |
+|-------------------|----------------------------------------------------|
+| **Windows**       | Download and run the installer: <https://git-scm.com/download/win> |
+| **Ubuntu/Debian** | `sudo apt-get update && sudo apt-get install git`  |
+
+---
+
+## Installation
+
+You can install BIDS Manager in two ways:
+
+### 1. One-click installers <sup>(recommended)</sup>
+
+1. **Download** the ZIP package:  
+   **[📦 One-click Installers](https://github.com/ANCPLabOldenburg/BIDS-Manager/raw/main/Installers/Installers.zip
+)**
+2. **Extract** the ZIP file and run the script for your operating system:
+
+| OS               | Script                        | How to Run                         | Duration |
+|------------------|-------------------------------|------------------------------------|---------|
+| **Windows 10/11**| `install_bids_manager.bat`     | Double-click                        | ≈ 5 min |
+| **Linux**        | `install_bids_manager.sh`      | `./install_bids_manager.sh`         | ≈ 5 min |
+
+3. After the installation finishes, you will find two shortcuts on your desktop:
+
+| OS          | Launch                    | Uninstall                      |
+|-------------|---------------------------|--------------------------------|
+| **Windows** | `run_bidsmanager.bat`      | `uninstall_bidsmanager.bat`    |
+| **Linux**   | **BIDS Manager** (launcher)| `uninstall_bidsmanager.sh`     |
+
+---
+
+### 2. Install in a virtual environment (advanced)
+
+```bash
+# 1. Create a virtual environment
+python3 -m venv <env_name>
+
+# 2. Activate it
+source <env_name>/bin/activate          # On Windows: <env_name>\Scripts\activate
+
+# 3. Install BIDS Manager from GitHub
+pip install git+https://github.com/ANCPLabOldenburg/BIDS-Manager.git
+```
+
+The package declares all dependencies including `heudiconv`, so installation
+pulls everything required to run the GUI and helper scripts.
+All core requirements are version pinned in `pyproject.toml` to ensure
+consistent installations.
+
+After installation the following commands become available:
+
+- `bids-manager` – main GUI combining conversion and editing tools
+- `dicom-inventory` – generate `subject_summary.tsv` from a DICOM directory
+- `build-heuristic` – create a HeuDiConv heuristic from the TSV
+- `run-heudiconv` – run HeuDiConv using the generated heuristic
+- `post-conv-renamer` – rename fieldmap files after conversion
+- `bids-editor` – standalone metadata editor
+- `fill-bids-ignore` – interactively update `.bidsignore`
+
+All utilities provide `-h/--help` for details.
+
+### Recent updates
+
+- The TSV produced by `dicom-inventory` can now be loaded directly in the GUI and
+  its file name customised before generation.
+- The Batch Rename tool previews changes and allows restricting the scope to
+  specific subjects.
+- A "Set Intended For" dialog lets you manually edit fieldmap IntendedFor lists
+  if the automatic matching needs adjustment.
+- `run-heudiconv` now keeps a copy of `subject_summary.tsv` under `.bids_manager`
+  and generates a clean `participants.tsv` using demographics from that file.
+- Re-running `run-heudiconv` on the same dataset now appends new subjects to
+  the existing `.bids_manager` records and updates `participants.tsv` instead of
+  overwriting them.
+- `dicom-inventory` distinguishes repeated sequences by adding `series_uid` and `rep`
+  columns and records `acq_time` for each series in `subject_summary.tsv`.
+- Fieldmap rows for magnitude and phase images are now merged so each acquisition
+  appears once with the combined file count, and their `series_uid` values are
+  stored as a pipe-separated list so both sequences are converted.
+- `post-conv-renamer` now adds an `IntendedFor` list to each fieldmap JSON so
+  fMRI preprocessing tools can automatically match fieldmaps with the relevant
+  functional runs.
+- The GUI's Tools menu gained actions to refresh `_scans.tsv` files and edit
+  `.bidsignore` entries.
+- The DPI scale dialog now adjusts values in 25% increments and the DPI button
+  appears between the CPU and Authorship buttons.
+- On startup the GUI detects the system DPI and applies the matching scale.
+- The scanned data table now provides a "Generate unique IDs" button that
+  assigns random 3‑letter/3‑digit identifiers to subjects. If an entry already
+  exists for the same study in an existing `.bids_manager/subject_summary.tsv`,
+  you are prompted to reuse its identifier.
+- A "Detect repeats" button can recompute repetition numbers based on
+  acquisition time when all BIDS and given names are filled.
+

bids_manager-0.1.0/README.md

@@ -0,0 +1,111 @@
+
+# BIDS Manager
+
+**BIDS Manager** is a **PyQt-based** GUI that converts **DICOM** folders into **BIDS**-compliant datasets and allows easy metadata editing.
+
+---
+
+## Requirements
+
+| Software  | Minimum Version | Notes                                                   |
+|----------|-----------------|---------------------------------------------------------|
+| **Python** | 3.10            | Installed automatically if you use the one-click installers |
+| **Git**    | —               | Must be installed manually (see below)                 |
+
+### Installing Git
+
+| Platform          | Command / Action                                   |
+|-------------------|----------------------------------------------------|
+| **Windows**       | Download and run the installer: <https://git-scm.com/download/win> |
+| **Ubuntu/Debian** | `sudo apt-get update && sudo apt-get install git`  |
+
+---
+
+## Installation
+
+You can install BIDS Manager in two ways:
+
+### 1. One-click installers <sup>(recommended)</sup>
+
+1. **Download** the ZIP package:  
+   **[📦 One-click Installers](https://github.com/ANCPLabOldenburg/BIDS-Manager/raw/main/Installers/Installers.zip
+)**
+2. **Extract** the ZIP file and run the script for your operating system:
+
+| OS               | Script                        | How to Run                         | Duration |
+|------------------|-------------------------------|------------------------------------|---------|
+| **Windows 10/11**| `install_bids_manager.bat`     | Double-click                        | ≈ 5 min |
+| **Linux**        | `install_bids_manager.sh`      | `./install_bids_manager.sh`         | ≈ 5 min |
+
+3. After the installation finishes, you will find two shortcuts on your desktop:
+
+| OS          | Launch                    | Uninstall                      |
+|-------------|---------------------------|--------------------------------|
+| **Windows** | `run_bidsmanager.bat`      | `uninstall_bidsmanager.bat`    |
+| **Linux**   | **BIDS Manager** (launcher)| `uninstall_bidsmanager.sh`     |
+
+---
+
+### 2. Install in a virtual environment (advanced)
+
+```bash
+# 1. Create a virtual environment
+python3 -m venv <env_name>
+
+# 2. Activate it
+source <env_name>/bin/activate          # On Windows: <env_name>\Scripts\activate
+
+# 3. Install BIDS Manager from GitHub
+pip install git+https://github.com/ANCPLabOldenburg/BIDS-Manager.git
+```
+
+The package declares all dependencies including `heudiconv`, so installation
+pulls everything required to run the GUI and helper scripts.
+All core requirements are version pinned in `pyproject.toml` to ensure
+consistent installations.
+
+After installation the following commands become available:
+
+- `bids-manager` – main GUI combining conversion and editing tools
+- `dicom-inventory` – generate `subject_summary.tsv` from a DICOM directory
+- `build-heuristic` – create a HeuDiConv heuristic from the TSV
+- `run-heudiconv` – run HeuDiConv using the generated heuristic
+- `post-conv-renamer` – rename fieldmap files after conversion
+- `bids-editor` – standalone metadata editor
+- `fill-bids-ignore` – interactively update `.bidsignore`
+
+All utilities provide `-h/--help` for details.
+
+### Recent updates
+
+- The TSV produced by `dicom-inventory` can now be loaded directly in the GUI and
+  its file name customised before generation.
+- The Batch Rename tool previews changes and allows restricting the scope to
+  specific subjects.
+- A "Set Intended For" dialog lets you manually edit fieldmap IntendedFor lists
+  if the automatic matching needs adjustment.
+- `run-heudiconv` now keeps a copy of `subject_summary.tsv` under `.bids_manager`
+  and generates a clean `participants.tsv` using demographics from that file.
+- Re-running `run-heudiconv` on the same dataset now appends new subjects to
+  the existing `.bids_manager` records and updates `participants.tsv` instead of
+  overwriting them.
+- `dicom-inventory` distinguishes repeated sequences by adding `series_uid` and `rep`
+  columns and records `acq_time` for each series in `subject_summary.tsv`.
+- Fieldmap rows for magnitude and phase images are now merged so each acquisition
+  appears once with the combined file count, and their `series_uid` values are
+  stored as a pipe-separated list so both sequences are converted.
+- `post-conv-renamer` now adds an `IntendedFor` list to each fieldmap JSON so
+  fMRI preprocessing tools can automatically match fieldmaps with the relevant
+  functional runs.
+- The GUI's Tools menu gained actions to refresh `_scans.tsv` files and edit
+  `.bidsignore` entries.
+- The DPI scale dialog now adjusts values in 25% increments and the DPI button
+  appears between the CPU and Authorship buttons.
+- On startup the GUI detects the system DPI and applies the matching scale.
+- The scanned data table now provides a "Generate unique IDs" button that
+  assigns random 3‑letter/3‑digit identifiers to subjects. If an entry already
+  exists for the same study in an existing `.bids_manager/subject_summary.tsv`,
+  you are prompted to reuse its identifier.
+- A "Detect repeats" button can recompute repetition numbers based on
+  acquisition time when all BIDS and given names are filled.
+

bids_manager-0.1.0/bids_manager/__init__.py

@@ -0,0 +1,11 @@
+"""BIDS Manager package."""
+
+from importlib import metadata
+
+__all__ = ["__version__"]
+
+try:  # pragma: no cover - version resolution
+    __version__ = metadata.version("bids-manager")
+except metadata.PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+

bids_manager-0.1.0/bids_manager/build_heuristic_from_tsv.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""
+build_heuristic_from_tsv.py — **v10**
+====================================
+Simple heuristic that:
+1. **Keeps every sequence**, including SBRef.
+2. **Uses the raw SeriesDescription** (cleaned) as the filename stem – no
+   added `rep-*`, task, or echo logic.
+3. Skips only modalities listed in `SKIP_BY_DEFAULT` (`report`,
+   `physio`, `refscan`).
+"""
+
+from __future__ import annotations
+from pathlib import Path
+from textwrap import dedent
+import pandas as pd
+import re
+
+# -----------------------------------------------------------------------------
+# Configuration
+# -----------------------------------------------------------------------------
+SKIP_BY_DEFAULT = {"report", "physio", "refscan"}
+
+# -----------------------------------------------------------------------------
+# Helper functions
+# -----------------------------------------------------------------------------
+
+def clean(text: str) -> str:
+    """Return alphanumerics only (for variable names)."""
+    return re.sub(r"[^0-9A-Za-z]+", "", str(text))
+
+
+def safe_stem(seq: str) -> str:
+    """Clean SeriesDescription for use in a filename."""
+    return re.sub(r"[^0-9A-Za-z_-]+", "_", seq.strip()).strip("_")
+
+
+def dedup_parts(*parts: str) -> str:
+    """Return underscore-joined *parts* with consecutive repeats removed."""
+    tokens: list[str] = []
+    for part in parts:
+        for t in str(part).split("_"):
+            if t and (not tokens or t != tokens[-1]):
+                tokens.append(t)
+    return "_".join(tokens)
+
+
+# -----------------------------------------------------------------------------
+# Core writer
+# -----------------------------------------------------------------------------
+
+def write_heuristic(df: pd.DataFrame, dst: Path) -> None:
+    """Write a HeuDiConv heuristic from ``df`` to ``dst``.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Table generated by :mod:`dicom_inventory` describing the DICOM series.
+    dst : Path
+        Destination ``heuristic_<name>.py`` file.
+    """
+
+    print("Building heuristic (v10)…")
+    buf: list[str] = []
+
+    # 1 ─ header -----------------------------------------------------------
+    buf.append(
+        dedent(
+            '''\
+            """AUTO-GENERATED HeuDiConv heuristic (v10)."""
+            from typing import Tuple
+
+            def create_key(template: str,
+                           outtype: Tuple[str, ...] = ("nii.gz",),
+                           annotation_classes=None):
+                if not template:
+                    raise ValueError("Template must be non-empty")
+                return template, outtype, annotation_classes
+            '''
+        )
+    )
+
+    # 2 ─ SID_MAP ----------------------------------------------------------
+    sid_pairs = {(clean(str(r.source_folder)) or clean(Path(r.source_folder or '.').name), r.BIDS_name) for r in df.itertuples()}
+    buf.append("\nSID_MAP = {\n")
+    for folder, bids in sorted(sid_pairs):
+        buf.append(f"    '{folder}': '{bids}',\n")
+    buf.append("}\n\n")
+
+    # 3 ─ template keys ----------------------------------------------------
+    # Include series UID (or rep) in the key to handle repeated sequences
+    seq2key: dict[tuple[str, str, str, str, str], str] = {}
+    key_defs: list[tuple[str, str]] = []
+
+    rep_counts = (
+        df.groupby(["BIDS_name", "session", "sequence"], dropna=False)["sequence"].transform("count")
+    )
+    rep_index = (
+        df.groupby(["BIDS_name", "session", "sequence"], dropna=False).cumcount() + 1
+    )
+
+    key_def_set = set()
+    for idx, row in df.iterrows():
+        ses_raw = row.get("session", "")
+        ses = "" if pd.isna(ses_raw) else str(ses_raw).strip()
+        folder = Path(str(row.get("source_folder", "."))).name
+        rep_num = rep_index.loc[idx]
+        uid_field = str(row.get("series_uid", ""))
+        bids = row["BIDS_name"]
+        container = row.get("modality_bids", "misc") or "misc"
+        stem = safe_stem(row["sequence"])
+
+        base_parts = [bids, ses, stem]
+        if rep_counts.loc[idx] > 1:
+            base_parts.append(f"rep-{rep_num}")
+        base = dedup_parts(*base_parts)
+        path = "/".join(p for p in [bids, ses, container] if p)
+        template = f"{path}/{base}"
+
+        key_parts = [bids, ses, stem]
+        if rep_counts.loc[idx] > 1:
+            key_parts.append(f"rep-{rep_num}")
+        key_var = "key_" + clean("_".join(p for p in key_parts if p))
+        if key_var not in key_def_set:
+            key_defs.append((key_var, template))
+            key_def_set.add(key_var)
+
+        uid_list = [u for u in uid_field.split("|") if u] or [""]
+        for uid in uid_list:
+            key_id = (row["sequence"], row["BIDS_name"], ses, folder, uid)
+            if key_id in seq2key:
+                continue
+            seq2key[key_id] = key_var
+
+    for var, tpl in key_defs:
+        buf.append(f"{var} = create_key('{tpl}')\n")
+    buf.append("\n")
+
+    # 4 ─ infotodict() ----------------------------------------------------
+    buf.append("def infotodict(seqinfo):\n    \"\"\"Return mapping SeriesDescription → key list.\"\"\"\n")
+    for var in seq2key.values():
+        buf.append(f"    {var}_list = []\n")
+    buf.append("    info = {\n")
+    for var in seq2key.values():
+        buf.append(f"        {var}: {var}_list,\n")
+    buf.append("    }\n\n")
+
+    buf.append("    for s in seqinfo:\n")
+    for (seq, _b, _s, folder, uid), var in seq2key.items():
+        seq_esc = seq.replace("'", "\\'")
+        fol_esc = folder.replace("'", "\\'")
+        uid_esc = str(uid).replace("'", "\\'")
+        buf.append(
+            f"        if s.series_description == '{seq_esc}' and s.dcm_dir_name == '{fol_esc}' and getattr(s, 'series_uid', '') == '{uid_esc}':\n"
+        )
+        buf.append(f"            {var}_list.append(s.series_id)\n")
+    buf.append("    return info\n")
+
+    dst.write_text("".join(buf), encoding="utf-8")
+    print("Heuristic written →", dst.resolve())
+
+
+# -----------------------------------------------------------------------------
+# Driver
+# -----------------------------------------------------------------------------
+
+def generate(tsv: Path, out_dir: Path) -> None:
+    """Generate heuristic files for each study described in ``tsv``.
+
+    Parameters
+    ----------
+    tsv : Path
+        Path to ``subject_summary.tsv`` produced by :mod:`dicom_inventory`.
+    out_dir : Path
+        Directory where the heuristic files will be written.
+    """
+
+    df = pd.read_csv(tsv, sep="\t", keep_default_na=False)
+
+    # Drop rows with unwanted modalities
+    mask = df.modality.isin(SKIP_BY_DEFAULT)
+    if mask.any():
+        df.loc[mask, "include"] = 0
+        print(f"Auto‑skipped {mask.sum()} rows ({', '.join(SKIP_BY_DEFAULT)})")
+
+    df = df[df.include == 1]
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    for study, sub_df in df.groupby("StudyDescription"):
+        fname = safe_stem(study or "unknown")
+        heur = out_dir / f"heuristic_{fname}.py"
+        write_heuristic(sub_df, heur)
+        folders = " ".join(sorted({clean(f) or clean(Path(f or '.').name) for f in sub_df.source_folder.unique()}))
+        print(dedent(f"""
+        heudiconv -d "<RAW_ROOT>/{{subject}}/**/*.*" -s {folders} -f {heur.name} -c dcm2niix -o <BIDS_OUT>/{fname} -b --minmeta --overwrite"""))
+
+
+def main() -> None:
+    """Entry point for the ``build-heuristic`` command line utility."""
+
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Generate HeuDiConv heuristic(s) from TSV")
+    parser.add_argument("tsv", help="Path to subject_summary.tsv file")
+    parser.add_argument("out_dir", help="Directory to write heuristic files")
+    args = parser.parse_args()
+
+    generate(Path(args.tsv), Path(args.out_dir))
+
+
+if __name__ == "__main__":
+    main()
+