bids-manager 0.1.0__py3-none-any.whl

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/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()
+

bids_manager/dicom_inventory.py

@@ -0,0 +1,463 @@
+#!/usr/bin/env python3
+"""
+dicom_inventory.py — fully-commented, no-emoji version
+------------------------------------------------------
+
+Creates a long-format TSV describing every DICOM series in *root_dir*.
+
+Why you want this
+-----------------
+* Lets you review **all** SeriesDescriptions, subjects, sessions and file counts
+  before converting anything.
+* Column `include` defaults to 1 except for scout/report/physlog sequences,
+  which start at 0 so they are skipped by default.
+* Generated table is the single source of truth you feed into a helper script
+  that writes the HeuDiConv heuristic.
+
+Output columns (ordered as they appear)
+---------------------------------------
+subject        – GivenName shown only on the first row of each subject block
+BIDS_name      – auto-assigned `sub-001`, `sub-002`, … (same GivenName → same ID)
+session        – `ses-<label>` if exactly one unique session tag is present in
+                 that folder, otherwise blank
+source_folder  – relative path from the DICOM root to the folder containing the
+                 series
+include        – defaults to 1 but scout/report/physlog rows start at 0
+sequence       – original SeriesDescription
+series_uid     – DICOM SeriesInstanceUID identifying a specific acquisition
+rep            – 1, 2, … if multiple SeriesInstanceUIDs share the same description
+acq_time       – AcquisitionTime of the first file in that series
+modality       – fine label inferred from patterns (T1w, bold, dwi, …)
+modality_bids  – top-level container (anat, func, dwi, fmap) derived from
+                 *modality*
+n_files        – number of DICOM files (.dcm or .ima) with that SeriesDescription
+GivenName … StudyDescription – demographics copied from the first header seen
+"""
+
+import os
+import re
+from collections import defaultdict
+from typing import Optional
+from pathlib import Path
+from joblib import Parallel, delayed
+
+import pandas as pd
+import pydicom
+from pydicom.multival import MultiValue
+
+# Directory used to store persistent user preferences
+PREF_DIR = Path(__file__).resolve().parent / "user_preferences"
+SEQ_DICT_FILE = PREF_DIR / "sequence_dictionary.tsv"
+
+# Acceptable DICOM file extensions (lower case)
+DICOM_EXTS = (".dcm", ".ima")
+
+
+# ----------------------------------------------------------------------
+# 1.  Patterns: SeriesDescription → fine-grained modality label
+#    (order matters: first match wins)
+# ----------------------------------------------------------------------
+BIDS_PATTERNS = {
+    # anatomy
+    "T1w"    : (
+        "t1w",
+        "t1-weight",
+        "t1_",
+        "t1 ",
+        "mprage",
+        "tfl3d",
+        "fspgr",
+    ),
+    "T2w"    : ("t2w", "space", "tse"),
+    "FLAIR"  : ("flair",),
+    "MTw"    : ("gre-mt", "gre_mt", "mt"),
+    "PDw"    : ("gre-nm", "gre_nm"),
+    "scout"  : ("localizer", "scout"),
+    "report" : ("phoenixzipreport", "phoenix document", ".pdf", "report"),
+    "refscan": ("type-ref", "reference", "refscan"),
+    # functional
+    "bold"   : ("fmri", "bold", "task-"),
+    "SBRef"  : ("sbref",),
+    # diffusion
+    "dwi"    : ("dti", "dwi", "diff"),
+    # field maps
+    "fmap"   : (
+        "gre_field",
+        "fieldmapping",
+        "_fmap",
+        "fmap",
+        "phase",
+        "magnitude",
+        "b0rf",
+        "b0_map",
+        "b0map",
+    ),
+    # misc (kept for completeness)
+    "physio" : ("physiolog", "physio", "pulse", "resp"),
+}
+
+# Keep a pristine copy of the default patterns so the GUI can restore them
+DEFAULT_BIDS_PATTERNS = {m: tuple(pats) for m, pats in BIDS_PATTERNS.items()}
+
+
+def load_sequence_dictionary() -> None:
+    """Load user-modified sequence patterns from :data:`SEQ_DICT_FILE`."""
+    global BIDS_PATTERNS
+    if not SEQ_DICT_FILE.exists():
+        return
+    try:
+        df = pd.read_csv(SEQ_DICT_FILE, sep="\t", keep_default_na=False)
+    except Exception:
+        return
+    patterns: defaultdict[str, list[str]] = defaultdict(list)
+    for _, row in df.iterrows():
+        mod = str(row.get("modality", "")).strip()
+        pat = str(row.get("pattern", "")).strip().lower()
+        if mod and pat:
+            patterns[mod].append(pat)
+    if patterns:
+        BIDS_PATTERNS = {m: tuple(pats) for m, pats in patterns.items()}
+
+
+def restore_sequence_dictionary() -> None:
+    """Revert :data:`BIDS_PATTERNS` to the bundled defaults."""
+    global BIDS_PATTERNS
+    BIDS_PATTERNS = {m: tuple(pats) for m, pats in DEFAULT_BIDS_PATTERNS.items()}
+    try:
+        SEQ_DICT_FILE.unlink()
+    except Exception:
+        pass
+
+
+load_sequence_dictionary()
+
+def guess_modality(series: str) -> str:
+    """Return first matching fine label; otherwise 'unknown'."""
+    s = series.lower()
+    for label, pats in BIDS_PATTERNS.items():
+        if any(p in s for p in pats):
+            return label
+    return "unknown"
+
+
+MAGNITUDE_IMGTYPE = ["ORIGINAL", "PRIMARY", "M", "ND", "NORM"]
+PHASE_IMGTYPE = ["ORIGINAL", "PRIMARY", "P", "ND"]
+
+def normalize_image_type(value) -> list:
+    """Return ImageType components as a list of strings."""
+    if value is None:
+        return []
+    if isinstance(value, (list, tuple, MultiValue)):
+        return [str(x).strip() for x in value]
+    text = str(value)
+    if "\\" in text:
+        return [p.strip() for p in text.split("\\")]
+    text = text.strip()
+    if text.startswith("[") and text.endswith("]"):
+        text = text[1:-1]
+        return [p.strip().strip("'") for p in text.split(",")]
+    return [text] if text else []
+
+
+def classify_fieldmap_type(img_list: list) -> str:
+    """Return 'M' for magnitude, 'P' for phase, '' otherwise."""
+    if img_list == MAGNITUDE_IMGTYPE:
+        return "M"
+    if img_list == PHASE_IMGTYPE:
+        return "P"
+    return ""
+
+
+# ----------------------------------------------------------------------
+# 2.  Map fine label → top-level BIDS container (anat, func, …)
+# ----------------------------------------------------------------------
+BIDS_CONTAINER = {
+    "T1w":"anat", "T2w":"anat", "FLAIR":"anat",
+    "MTw":"anat", "PDw":"anat",
+    "scout":"anat", "report":"anat", "refscan":"anat",
+    "bold":"func", "SBRef":"func",
+    "dwi":"dwi",
+    "fmap":"fmap",
+}
+def modality_to_container(mod: str) -> str:
+    """Translate T1w → anat, bold → func, etc.; unknown → ''."""
+    return BIDS_CONTAINER.get(mod, "")
+
+# session detector (e.g. ses-pre, ses-01) -- case-insensitive
+SESSION_RE = re.compile(r"ses-([a-zA-Z0-9]+)", re.IGNORECASE)
+
+
+# ----------------------------------------------------------------------
+# 3.  Main scanner
+# ----------------------------------------------------------------------
+def scan_dicoms_long(
+    root_dir: str,
+    output_tsv: Optional[str] = None,
+    n_jobs: int = 1,
+) -> pd.DataFrame:
+    """
+    Walk *root_dir*, read DICOM headers, return long-format DataFrame.
+
+    Parameters
+    ----------
+    root_dir   : str
+        Path with raw DICOMs organised in sub-folders.
+    output_tsv : str | None
+        If provided, write the TSV to that path.
+    n_jobs : int
+        Number of parallel workers to use when reading DICOM files.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Inventory as described in module docstring.
+    """
+
+    root_dir = Path(root_dir)
+    print(f"Scanning DICOM headers under: {root_dir}")
+
+    # in-memory stores
+    demo    = {}
+    counts     = defaultdict(lambda: defaultdict(lambda: defaultdict(int)))
+    mods       = defaultdict(lambda: defaultdict(dict))
+    acq_times  = defaultdict(lambda: defaultdict(dict))
+    imgtypes   = defaultdict(lambda: defaultdict(dict))
+    sessset = defaultdict(lambda: defaultdict(set))
+
+    # PASS 1: Walk filesystem and collect info in parallel
+    file_list = []
+    for root, _dirs, files in os.walk(root_dir):
+        for fname in files:
+            if fname.lower().endswith(DICOM_EXTS):
+                file_list.append(os.path.join(root, fname))
+
+    def _read_one(fpath: str):
+        try:
+            ds = pydicom.dcmread(fpath, stop_before_pixels=True, force=True)
+        except Exception as exc:  # pragma: no cover - I/O errors
+            print(f"Warning: could not read {fpath}: {exc}")
+            return None
+
+        root = os.path.dirname(fpath)
+        pn = getattr(ds, "PatientName", None)
+        given = pn.given_name.strip() if pn and pn.given_name else ""
+        pid = getattr(ds, "PatientID", "").strip()
+        subj = given or pid or "UNKNOWN"
+        study = (
+            getattr(ds, "StudyDescription", None)
+            or getattr(ds, "StudyName", None)
+            or "n/a"
+        )
+        study = str(study).strip()
+        subj_key = f"{subj}||{study}"
+        rel = os.path.relpath(root, root_dir)
+        folder = root_dir.name if rel == "." else rel
+        series = getattr(ds, "SeriesDescription", "n/a").strip()
+        uid = getattr(ds, "SeriesInstanceUID", "")
+        raw_img_type = getattr(ds, "ImageType", None)
+        img_list = normalize_image_type(raw_img_type)
+        img3 = classify_fieldmap_type(img_list)
+        if not img3:
+            img3 = img_list[2] if len(img_list) >= 3 else ""
+        acq_time = str(getattr(ds, "AcquisitionTime", "")).strip()
+        m = SESSION_RE.search(series)
+        sess_tag = f"ses-{m.group(1)}" if m else None
+        demo_dict = dict(
+            GivenName=given,
+            FamilyName=getattr(pn, "family_name", "").strip(),
+            PatientID=pid,
+            PatientSex=getattr(ds, "PatientSex", "n/a").strip(),
+            PatientAge=getattr(ds, "PatientAge", "n/a").strip(),
+            StudyDescription=study,
+        )
+        return dict(
+            subj_key=subj_key,
+            folder=folder,
+            series=series,
+            uid=uid,
+            modality=guess_modality(series),
+            img3=img3,
+            acq_time=acq_time,
+            sess_tag=sess_tag,
+            demo=demo_dict,
+        )
+
+    results = Parallel(n_jobs=n_jobs)(delayed(_read_one)(fp) for fp in file_list)
+    for res in results:
+        if not res:
+            continue
+        subj_key = res["subj_key"]
+        folder = res["folder"]
+        series = res["series"]
+        uid = res["uid"]
+        key = (series, uid)
+        counts[subj_key][folder][key] += 1
+        mods[subj_key][folder][key] = res["modality"]
+        if key not in imgtypes[subj_key][folder]:
+            imgtypes[subj_key][folder][key] = res["img3"]
+        if key not in acq_times[subj_key][folder] and res["acq_time"]:
+            acq_times[subj_key][folder][key] = res["acq_time"]
+        if res["sess_tag"]:
+            sessset[subj_key][folder].add(res["sess_tag"])
+        if subj_key not in demo:
+            demo[subj_key] = res["demo"]
+
+    print(f"Subjects found            : {len(demo)}")
+    total_series = sum(len(seq_dict)
+                       for subj in counts.values()
+                       for folder, seq_dict in subj.items())
+    print(f"Unique Series instances   : {total_series}")
+
+    # PASS 2: assign BIDS subject numbers PER STUDY
+    study_subjects = defaultdict(set)
+    for subj_key in demo:
+        subj, stud = subj_key.split("||", 1)
+        study_subjects[stud].add(subj)
+
+    bids_map = {}
+    for study, subj_set in study_subjects.items():
+        for i, sid in enumerate(sorted(subj_set)):
+            bids_map[f"{sid}||{study}"] = f"sub-{i+1:03d}"
+
+    print("Assigned BIDS IDs:", bids_map)
+
+    # PASS 3: build DataFrame rows
+    rows = []
+    for subj_key in sorted(counts):
+        first_row = True
+        for folder in sorted(counts[subj_key]):
+
+            # decide session label for this folder
+            ses_labels = sorted(sessset[subj_key][folder])
+            session = ses_labels[0] if len(ses_labels) == 1 else ""
+
+            rep_counter = defaultdict(int)
+            for (series, uid), n_files in sorted(counts[subj_key][folder].items()):
+                fine_mod = mods[subj_key][folder][(series, uid)]
+                img3 = imgtypes[subj_key][folder].get((series, uid), "")
+                include = 1
+                if fine_mod in {"scout", "report"} or "physlog" in series.lower():
+                    include = 0
+                # Do not consider image type when counting scout duplicates
+                rep_key = series if fine_mod == "scout" else (series, img3)
+                rep_counter[rep_key] += 1
+                rows.append({
+                    "subject"       : demo[subj_key]["GivenName"] if first_row else "",
+                    "BIDS_name"     : bids_map[subj_key],
+                    "session"       : session,
+                    "source_folder" : folder,
+                    "include"       : include,
+                    "sequence"      : series,
+                    "series_uid"    : uid,
+                    "rep"           : rep_counter[rep_key] if rep_counter[rep_key] > 1 else "",
+                    "image_type"    : img3,
+                    "acq_time"      : acq_times[subj_key][folder].get((series, uid), ""),
+                    "modality"      : fine_mod,
+                    "modality_bids" : modality_to_container(fine_mod),
+                    "n_files"       : n_files,
+                    **demo[subj_key],                                # demographics
+                })
+                first_row = False
+
+    # Final column order
+    columns = [
+        "subject", "BIDS_name", "session", "source_folder",
+        "include", "sequence", "series_uid", "rep", "acq_time",
+        "image_type", "modality", "modality_bids", "n_files",
+        "GivenName", "FamilyName", "PatientID",
+        "PatientSex", "PatientAge", "StudyDescription",
+    ]
+    df = pd.DataFrame(rows, columns=columns)
+
+    # Collapse magnitude/phase rows for fieldmaps
+    fmap_mask = df.modality == "fmap"
+    if fmap_mask.any():
+        base_cols = [
+            "BIDS_name",
+            "session",
+            "source_folder",
+            "sequence",
+        ]
+        # Use acquisition time rounded to the minute to merge magnitude and
+        # phase series from the same fieldmap even if their timestamps differ
+        # by a few seconds.
+        fmap_df = df[fmap_mask].copy()
+        fmap_df["acq_group"] = fmap_df["acq_time"].apply(lambda t: str(t)[:4])
+        group_cols = base_cols + ["acq_group"]
+        fmap_df["uid_list"] = fmap_df["series_uid"]
+        # keep all UIDs within each group so both magnitude and phase series
+        # are converted; they will be joined with '|' below
+        fmap_df["img_set"] = fmap_df["image_type"]
+        fmap_df = (
+            fmap_df.groupby(group_cols, as_index=False)
+            .agg(
+                {
+                    "subject": "first",
+                    "BIDS_name": "first",
+                    "session": "first",
+                    "source_folder": "first",
+                    "include": "max",
+                    "sequence": "first",
+                    "uid_list": lambda x: "|".join(sorted(set(str(v) for v in x))),
+                    "img_set": lambda x: "".join(sorted(set(str(v) for v in x))),
+                    "acq_time": "first",
+                    "modality": "first",
+                    "modality_bids": "first",
+                    "n_files": "sum",
+                    "GivenName": "first",
+                    "FamilyName": "first",
+                    "PatientID": "first",
+                    "PatientSex": "first",
+                    "PatientAge": "first",
+                    "StudyDescription": "first",
+                }
+            )
+        )
+        fmap_df.rename(columns={"uid_list": "series_uid", "img_set": "image_type"}, inplace=True)
+        fmap_df.drop(columns=["acq_group"], inplace=True)
+        sort_cols = base_cols + ["acq_time"]
+        fmap_df.sort_values(sort_cols, inplace=True)
+        fmap_df["rep"] = fmap_df.groupby(base_cols).cumcount() + 1
+        repeat_mask = fmap_df.groupby(base_cols)["rep"].transform("count") > 1
+        fmap_df.loc[~repeat_mask, "rep"] = ""
+
+        df = pd.concat([df[~fmap_mask], fmap_df], ignore_index=True, sort=False)
+
+    df.sort_values(["StudyDescription", "BIDS_name"], inplace=True)
+
+    # optional TSV export
+    if output_tsv:
+        df.to_csv(output_tsv, sep="\t", index=False)
+        print(f"Inventory written to: {output_tsv}")
+
+    return df
+
+
+# ----------------------------------------------------------------------
+# Command-line test
+# ----------------------------------------------------------------------
+def main() -> None:
+    """Command line interface for :func:`scan_dicoms_long`."""
+
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Generate TSV inventory for a DICOM folder")
+    parser.add_argument("dicom_dir", help="Path to the directory containing DICOM files")
+    parser.add_argument("output_tsv", help="Destination TSV file")
+    parser.add_argument(
+        "--jobs",
+        type=int,
+        # Use ~80% of available CPUs to provide a sensible default while
+        # leaving some resources free for the rest of the system.
+        default=max(1, round((os.cpu_count() or 1) * 0.8)),
+        help="Number of parallel workers to use",
+    )
+    args = parser.parse_args()
+
+    table = scan_dicoms_long(args.dicom_dir, args.output_tsv, n_jobs=args.jobs)
+    print("\nPreview (first 10 rows):\n")
+    print(table.head(10).to_string(index=False))
+
+
+if __name__ == "__main__":
+    main()