xnatbidscli 2.0.0__py3-none-any.whl

xnatbidscli/mriconvert.py

@@ -0,0 +1,890 @@
+import argparse
+import csv
+import io
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from datetime import datetime
+from pathlib import Path
+
+from .archive import (
+    OK_STATUSES as ARCHIVE_OK_STATUSES,
+    archive_experiment,
+    delete_experiment_dir,
+)
+from .sysinfo import get_system_username
+
+STATUS_COMPLETE = "COMPLETE"
+STATUS_FAILURE = "FAILURE"
+STATUS_NONEXISTENT = "NONEXISTENT"
+STATUS_EMPTY = "EMPTY"
+
+_OK_STATUSES = {STATUS_COMPLETE, STATUS_EMPTY}
+_NON_ALNUM = re.compile(r"[^A-Za-z0-9]")
+_DICOM_EXTS = {".dcm", ".ima"}
+_DATE_TAGS = (
+    "StudyDate",
+    "SeriesDate",
+    "AcquisitionDate",
+    "ContentDate",
+    "InstanceCreationDate",
+)
+_NON_DIGIT = re.compile(r"\D")
+
+# Root-level mriconvert_qc.tsv generation (run at the end of mriconvert).
+_SCANS_COLUMNS = [
+    "filename",
+    "acq_time",
+    "series_number",
+    "dimensions",
+    "size_bytes",
+    "participant_id",
+    "session_id",
+    "datatype",
+    "suffix",
+    "bids_name",
+    "rename",
+    "physio",
+    "recommend_for_use",
+    "complete",
+    "usable",
+    "qc_rating",
+    "rating_reason",
+    "qc_notes",
+]
+# Columns the generator always writes empty; user-entered text in any of them
+# means the file has been reviewed and must not be regenerated over.
+_SCANS_USER_COLUMNS = (
+    "rename",
+    "physio",
+    "recommend_for_use",
+    "complete",
+    "usable",
+    "qc_rating",
+    "rating_reason",
+    "qc_notes",
+)
+_SUB_RE = re.compile(r"(sub-[A-Za-z0-9]+)")
+_SES_RE = re.compile(r"(ses-[A-Za-z0-9]+)")
+# A SUBJECT/EXPERIMENT directory name matching these exactly (not just
+# containing a substring like it) is one `xnatbidscli download` wrote via
+# --rename-subject/--rename-experiment (or the CSV's SUBJECT_BIDS_RENAME/
+# EXPERIMENT_BIDS_RENAME columns): already `sub-<alnum>`/`ses-<alnum>`, so it
+# must be used as the BIDS label verbatim rather than sanitized and
+# re-prefixed.
+_SUB_RENAMED_RE = re.compile(r"^sub-[A-Za-z0-9]+$")
+_SES_RENAMED_RE = re.compile(r"^ses-[A-Za-z0-9]+$")
+_BIDS_NAME_RE = re.compile(r"^sub-[A-Za-z0-9]+_ses-[A-Za-z0-9]+_(.+)\.nii\.gz$")
+
+_print_lock = threading.Lock()
+
+# In-place "elapsed time" progress block shown while conversions are running
+# (see _render_progress). Every concurrent session gets its own line, all
+# redrawn together every 5 seconds (or whenever a status line is printed).
+_active_lock = threading.Lock()
+_active: dict[str, float] = {}  # label -> start time (time.monotonic())
+_progress_lines = 0  # number of progress lines currently drawn on-screen
+
+
+def _register_active(label: str) -> None:
+    with _active_lock:
+        _active[label] = time.monotonic()
+    _render_progress()
+
+
+def _unregister_active(label: str) -> None:
+    with _active_lock:
+        _active.pop(label, None)
+
+
+def _progress_snapshot() -> list[str]:
+    """Current 'LABEL: converting... elapsed Ns' lines, one per active session."""
+    with _active_lock:
+        items = list(_active.items())
+    now = time.monotonic()
+    return [
+        f"{label}: converting... elapsed {int(now - start)}s"
+        for label, start in items
+    ]
+
+
+def _render_progress() -> None:
+    """Redraw the live progress block in place, replacing whatever was drawn
+    on the previous call (see _progress_lines)."""
+    global _progress_lines
+    lines = _progress_snapshot()
+    with _print_lock:
+        if _progress_lines:
+            sys.stdout.write(f"\x1b[{_progress_lines}A\x1b[0J")
+        if lines:
+            sys.stdout.write("\n".join(lines) + "\n")
+        sys.stdout.flush()
+        _progress_lines = len(lines)
+
+
+def _safe_print(msg: str) -> None:
+    """Print msg above the live progress block, then redraw the block."""
+    global _progress_lines
+    lines = _progress_snapshot()
+    with _print_lock:
+        if _progress_lines:
+            sys.stdout.write(f"\x1b[{_progress_lines}A\x1b[0J")
+        print(msg)
+        if lines:
+            sys.stdout.write("\n".join(lines) + "\n")
+        sys.stdout.flush()
+        _progress_lines = len(lines)
+
+
+def _logging_now() -> str:
+    now = datetime.now()
+    return f"{now.strftime('%Y-%m-%d %H:%M:%S')},{now.microsecond // 1000:03d}"
+
+
+class _LogWriter:
+    def __init__(self, path: Path | None):
+        self._path = path
+        self._lock = threading.Lock()
+        self._user = get_system_username()
+        if path is not None:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            with path.open("w", newline="") as f:
+                csv.writer(f).writerow(
+                    [
+                        "DATESTAMP",
+                        "USER",
+                        "PROJECT",
+                        "SUBJECT",
+                        "EXPERIMENT",
+                        "STATUS",
+                    ]
+                )
+
+    def write(
+        self,
+        datestamp: str,
+        project: str,
+        subject: str,
+        experiment: str,
+        status: str,
+    ) -> None:
+        if self._path is None:
+            return
+        with self._lock, self._path.open("a", newline="") as f:
+            csv.writer(f).writerow(
+                [datestamp, self._user, project, subject, experiment, status]
+            )
+
+
+def _extract_session_date(ds) -> str | None:
+    """YYYYMMDD from the first non-empty DICOM date tag in priority order."""
+    for tag in _DATE_TAGS:
+        value = getattr(ds, tag, None)
+        if value is None or value == "":
+            continue
+        digits = _NON_DIGIT.sub("", str(value))
+        if len(digits) >= 8:
+            return digits[:8]
+    return None
+
+
+def _scan_dicoms(scans_dir: Path) -> tuple[bool, str | None]:
+    """Walk DICOMs under scans_dir, returning (any_readable, session_date).
+
+    session_date is YYYYMMDD pulled from the first DICOM with a usable date
+    tag, or None if no readable DICOM has one. After a DICOM parses but
+    yields no date, sibling files in that directory are skipped so a series
+    with empty date tags does not block dates available in other series.
+    """
+    import pydicom
+
+    any_readable = False
+    skip_dirs: set[Path] = set()
+    for path in scans_dir.rglob("*"):
+        if not path.is_file():
+            continue
+        if path.suffix.lower() not in _DICOM_EXTS:
+            continue
+        if path.parent in skip_dirs:
+            continue
+        try:
+            ds = pydicom.dcmread(str(path), stop_before_pixels=True)
+        except Exception:
+            continue
+        any_readable = True
+        date = _extract_session_date(ds)
+        if date:
+            return True, date
+        skip_dirs.add(path.parent)
+    return any_readable, None
+
+
+def _convert_one(
+    input_root: Path,
+    project: str,
+    subject: str,
+    experiment: str,
+    output_dir: Path,
+    config_path: Path,
+    dcm2bids_path: str,
+) -> tuple[str, str | None]:
+    exp_dir = input_root / project / subject / experiment
+    if not exp_dir.is_dir():
+        return STATUS_NONEXISTENT, f"session directory not found: {exp_dir}"
+
+    scans_dir = exp_dir / "scans"
+    if not scans_dir.is_dir():
+        return STATUS_EMPTY, f"no 'scans/' subdirectory under {exp_dir}"
+
+    any_readable, session_date = _scan_dicoms(scans_dir)
+    if not any_readable:
+        return STATUS_EMPTY, "no readable .dcm/.IMA DICOM files under scans/"
+
+    # A directory already named sub-X/ses-Y came from a download-stage
+    # rename: use the label verbatim (no stripping, no re-prefixing, and no
+    # DICOM-date override for the session) since the point of an explicit
+    # rename is that the user controls the final label.
+    if _SUB_RENAMED_RE.match(subject):
+        participant = subject[len("sub-"):]
+    else:
+        participant = _NON_ALNUM.sub("", subject)
+
+    if _SES_RENAMED_RE.match(experiment):
+        session = experiment[len("ses-"):]
+    else:
+        session = session_date or _NON_ALNUM.sub("", experiment)
+
+    if not participant or not session:
+        return STATUS_FAILURE, (
+            f"empty PARTICIPANT or SESSION after sanitizing "
+            f"SUBJECT={subject!r} EXPERIMENT={experiment!r}"
+        )
+
+    bids_root = output_dir / project
+    sub_dir = bids_root / f"sub-{participant}" / f"ses-{session}"
+    if sub_dir.exists() and any(sub_dir.iterdir()):
+        _safe_print(f"WARNING: overwriting existing {sub_dir}")
+
+    bids_root.mkdir(parents=True, exist_ok=True)
+
+    cmd = [
+        dcm2bids_path,
+        "-d", str(scans_dir),
+        "-p", participant,
+        "-s", session,
+        "-c", str(config_path),
+        "-o", str(bids_root),
+        "--clobber",
+        "--force_dcm2bids",
+    ]
+    label = f"{project}/{subject}/{experiment}"
+    _register_active(label)
+    try:
+        proc = subprocess.Popen(
+            cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True
+        )
+        stdout, stderr = proc.communicate()
+    finally:
+        _unregister_active(label)
+
+    if proc.returncode != 0:
+        stderr_tail = (stderr or "").strip().splitlines()[-1:] or [""]
+        return STATUS_FAILURE, (
+            f"dcm2bids exited with code {proc.returncode}"
+            + (f" — {stderr_tail[0]}" if stderr_tail[0] else "")
+        )
+    return STATUS_COMPLETE, None
+
+
+def _discover_sessions(
+    input_root: Path, args: argparse.Namespace
+) -> list[tuple[str, str, str]]:
+    if args.triplet is not None:
+        p, s, e = args.triplet
+        return [(p, s, e)]
+
+    if args.subject is not None:
+        project, subject = args.subject
+        subject_dir = input_root / project / subject
+        if not subject_dir.is_dir():
+            sys.exit(f"Error: subject directory not found: {subject_dir}")
+        sessions = [
+            (project, subject, exp.name)
+            for exp in sorted(subject_dir.iterdir())
+            if exp.is_dir()
+        ]
+        if not sessions:
+            sys.exit(f"Error: no sessions found under {subject_dir}")
+        return sessions
+
+    project = args.project
+    project_dir = input_root / project
+    if not project_dir.is_dir():
+        sys.exit(f"Error: project directory not found: {project_dir}")
+    sessions: list[tuple[str, str, str]] = []
+    for subject_dir in sorted(project_dir.iterdir()):
+        if not subject_dir.is_dir():
+            continue
+        for exp_dir in sorted(subject_dir.iterdir()):
+            if exp_dir.is_dir():
+                sessions.append(
+                    (project, subject_dir.name, exp_dir.name)
+                )
+    if not sessions:
+        sys.exit(f"Error: no sessions found under {project_dir}")
+    return sessions
+
+
+def _read_sidecar(nii_path: Path) -> dict:
+    """Load the JSON sidecar that accompanies a .nii.gz, or {} if absent."""
+    json_path = nii_path.with_name(nii_path.name[:-7] + ".json")
+    if not json_path.is_file():
+        return {}
+    try:
+        with json_path.open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _nii_dimensions(nii_path: Path, nib) -> str:
+    """x-joined image shape from nibabel, padded to always include a 4th dim."""
+    if nib is None:
+        return ""
+    try:
+        shape = list(nib.load(str(nii_path)).shape)
+    except Exception:
+        return ""
+    while len(shape) < 4:
+        shape.append(1)
+    return "x".join(str(int(s)) for s in shape)
+
+
+def _scans_row(nii_path: Path, bids_root: Path, nib) -> list:
+    basename = nii_path.name
+    sidecar = _read_sidecar(nii_path)
+    try:
+        size_bytes: object = nii_path.stat().st_size
+    except OSError:
+        size_bytes = ""
+
+    name_match = _BIDS_NAME_RE.match(basename)
+    sub_match = _SUB_RE.search(basename)
+    ses_match = _SES_RE.search(basename)
+    stem = basename[:-7] if basename.endswith(".nii.gz") else basename
+
+    return [
+        nii_path.relative_to(bids_root).as_posix(),
+        sidecar.get("AcquisitionTime", ""),
+        sidecar.get("SeriesNumber", ""),
+        _nii_dimensions(nii_path, nib),
+        size_bytes,
+        sub_match.group(1) if sub_match else "",
+        ses_match.group(1) if ses_match else "",
+        nii_path.parent.name,
+        stem.rsplit("_", 1)[-1],
+        name_match.group(1) if name_match else "",
+        "",  # rename — for the end-user
+        "",  # physio — for the end-user
+        "",  # recommend_for_use — for the end-user
+        "",  # complete — for the end-user
+        "",  # usable — for the end-user
+        "",  # qc_rating — for the end-user
+        "",  # rating_reason — for the end-user
+        "",  # qc_notes — for the end-user
+    ]
+
+
+def _find_scans_json() -> Path | None:
+    """Locate the static mriconvert_qc.json data dictionary (dev tree or wheel)."""
+    here = Path(__file__).resolve().parent
+    for candidate in (
+        here.parent / "assets" / "mriconvert_qc.json",  # dev: src/assets/
+        here / "assets" / "mriconvert_qc.json",  # wheel: xnatbidscli/assets/
+    ):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _qc_tsv_path(bids_root: Path) -> Path:
+    """``OUTPUT_DIR/PROJECT-<PROJECT_ID>_mriconvert_qc.tsv`` for ``bids_root``
+    (``OUTPUT_DIR/PROJECT_ID``)."""
+    return bids_root.parent / f"PROJECT-{bids_root.name}_mriconvert_qc.tsv"
+
+
+def _backup_qc_tsv(tsv_path: Path, new_content: str) -> Path | None:
+    """Lazily back up ``tsv_path`` before it is overwritten with ``new_content``.
+
+    Copies the current file to
+    ``OUTPUT_DIR/mriconvert_qc_backups/<stem>_YYYYMMDD_HHMMSS.tsv`` only when it
+    exists and its content differs from ``new_content``, so unchanged reruns
+    don't accumulate duplicate backups. Backups are never pruned.
+
+    Returns
+    -------
+    Path or None
+        The backup path, or None when no backup was needed.
+    """
+    try:
+        with tsv_path.open(newline="", encoding="utf-8") as f:
+            if f.read() == new_content:
+                return None
+    except FileNotFoundError:
+        return None
+
+    backup_dir = tsv_path.parent / "mriconvert_qc_backups"
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+    backup_path = backup_dir / f"{tsv_path.stem}_{ts}{tsv_path.suffix}"
+    shutil.copy2(tsv_path, backup_path)
+    return backup_path
+
+
+def _qc_json_path(bids_root: Path) -> Path:
+    """``OUTPUT_DIR/PROJECT-<PROJECT_ID>_mriconvert_qc.json`` for ``bids_root``
+    (``OUTPUT_DIR/PROJECT_ID``)."""
+    return bids_root.parent / f"PROJECT-{bids_root.name}_mriconvert_qc.json"
+
+
+def _write_scans_json(
+    bids_root: Path,
+    physio_parent: Path | None,
+    dcm2bids_config: Path | None = None,
+) -> None:
+    """Write mriconvert_qc.json from the static asset, injecting
+    ``PhysioParent`` and ``Dcm2BidsConfigPath``.
+
+    Loads the static data dictionary (never mutated in place) and sets
+    ``PhysioParent.Value``/``Dcm2BidsConfigPath.Value`` to ``physio_parent``/
+    ``dcm2bids_config`` when given. When ``dcm2bids_config`` is given,
+    ``Dcm2BidsConfigPath.LastModified`` is also stamped with the current time
+    (in Python logging's default ``asctime`` format). When either is None,
+    preserves whatever value (and, for ``Dcm2BidsConfigPath``, ``LastModified``)
+    was already recorded for it in the destination mriconvert_qc.json from a
+    prior run, if any, so omitting ``-y``/``-c`` on a rerun (e.g. under
+    ``-m/--maps``) doesn't erase it.
+    """
+    src_json = _find_scans_json()
+    if src_json is None:
+        _safe_print(
+            "WARNING: mriconvert_qc.json data dictionary not found; skipping the sidecar write."
+        )
+        return
+
+    try:
+        with src_json.open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError) as exc:
+        _safe_print(f"WARNING: could not read {src_json}: {exc}; skipping the sidecar write.")
+        return
+
+    dest_json = _qc_json_path(bids_root)
+    prior: dict | None = None
+    if (physio_parent is None or dcm2bids_config is None) and dest_json.is_file():
+        try:
+            with dest_json.open(encoding="utf-8") as f:
+                prior = json.load(f)
+        except (OSError, ValueError):
+            prior = None
+
+    if physio_parent is not None:
+        data.setdefault("PhysioParent", {})["Value"] = str(physio_parent)
+    elif prior is not None:
+        prior_value = prior.get("PhysioParent", {}).get("Value", "")
+        if prior_value:
+            data.setdefault("PhysioParent", {})["Value"] = prior_value
+
+    if dcm2bids_config is not None:
+        entry = data.setdefault("Dcm2BidsConfigPath", {})
+        entry["Value"] = str(dcm2bids_config)
+        entry["LastModified"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S,%f")[:-3]
+    elif prior is not None:
+        prior_entry = prior.get("Dcm2BidsConfigPath", {})
+        prior_value = prior_entry.get("Value", "")
+        if prior_value:
+            entry = data.setdefault("Dcm2BidsConfigPath", {})
+            entry["Value"] = prior_value
+            prior_last_modified = prior_entry.get("LastModified", "")
+            if prior_last_modified:
+                entry["LastModified"] = prior_last_modified
+
+    with dest_json.open("w", encoding="utf-8") as f:
+        json.dump(data, f, indent=4)
+        f.write("\n")
+
+
+def _read_existing_scans(
+    tsv_path: Path,
+) -> tuple[list[str], list[dict]] | None:
+    """Parse an existing mriconvert_qc.tsv into (fieldnames, rows), or None if it
+    cannot be read."""
+    try:
+        with tsv_path.open(newline="", encoding="utf-8") as f:
+            reader = csv.DictReader(f, delimiter="\t")
+            return list(reader.fieldnames or []), list(reader)
+    except OSError:
+        return None
+
+
+def _scans_deviations(
+    existing_rows: list[dict],
+    new_rows: list[list],
+    compare_columns: list[str],
+) -> list[tuple[str, str]]:
+    """Deviations in non-user fields between the current mriconvert_qc.tsv and a
+    freshly generated set of rows, keyed by ``filename``.
+
+    Returns a list of ``(kind, message)`` pairs, where ``kind`` is one of
+    ``"new"`` (file newly present on disk), ``"missing"`` (a mriconvert_qc.tsv row
+    whose file is no longer found on disk — the row is preserved, not
+    dropped), or ``"changed"`` (a generator-owned field drifted).
+    """
+    name_idx = _SCANS_COLUMNS.index("filename")
+    col_idx = {c: _SCANS_COLUMNS.index(c) for c in compare_columns}
+    existing_by_name = {r.get("filename", ""): r for r in existing_rows}
+    new_by_name = {r[name_idx]: r for r in new_rows}
+
+    deviations: list[tuple[str, str]] = []
+    for name in sorted(set(existing_by_name) | set(new_by_name)):
+        if name not in existing_by_name:
+            deviations.append((
+                "new",
+                f"{name}: newly present on disk (absent from current mriconvert_qc.tsv)",
+            ))
+            continue
+        if name not in new_by_name:
+            deviations.append((
+                "missing",
+                f"{name}: present in current mriconvert_qc.tsv but no longer found "
+                "on disk (row preserved)",
+            ))
+            continue
+        old_row, new_row = existing_by_name[name], new_by_name[name]
+        for col in compare_columns:
+            new_val = new_row[col_idx[col]]
+            new_val = "" if new_val is None else str(new_val)
+            old_val = old_row.get(col) or ""
+            if new_val != old_val:
+                deviations.append((
+                    "changed",
+                    f"{name}: {col} changed from {old_val!r} to {new_val!r}",
+                ))
+    return deviations
+
+
+def _report_scans_deviations(
+    bids_root: Path, deviations: list[tuple[str, str]]
+) -> None:
+    """Print one WARNING per deviation to stdout and write them to a log
+    file under <output>/PROJECT_ID/log/."""
+    project = bids_root.name
+    lines = [
+        f"WARNING: mriconvert_qc.tsv deviation [{project}] {msg}"
+        for _, msg in deviations
+    ]
+    for line in lines:
+        _safe_print(line)
+
+    log_dir = bids_root / "log"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+    log_path = log_dir / f"scans_deviations_{ts}.log"
+    with log_path.open("w", encoding="utf-8") as f:
+        f.write("\n".join(lines) + "\n")
+    _safe_print(
+        f"{len(deviations)} mriconvert_qc.tsv deviation(s) for {project} "
+        f"logged to {log_path}"
+    )
+
+
+def _generate_scans_tsv(
+    bids_root: Path,
+    physio_parent: Path | None = None,
+    dcm2bids_config: Path | None = None,
+) -> int:
+    """Write <output_dir>/PROJECT-<bids_root.name>_mriconvert_qc.tsv from
+    every .nii.gz under the dataset.
+
+    Walks bids_root with os.walk (skipping the dcm2bids ``tmp_dcm2bids``
+    scratch directory) and emits one row per .nii.gz, then writes the
+    mriconvert_qc.json sidecar alongside it (see ``_write_scans_json``). When a
+    mriconvert_qc.tsv is already present, rows are merged by ``filename``: a row
+    already present in mriconvert_qc.tsv is always kept exactly as-is (preserving
+    any reviewer edits), even if its generator-owned fields have since
+    drifted — such drift is only reported as a WARNING, never applied. Only
+    rows for files that are newly present on disk (their filename absent from
+    the current mriconvert_qc.tsv) are appended. This lets separate sessions be
+    converted at different times, appending to mriconvert_qc.tsv without
+    disturbing already-reviewed rows. Before an existing mriconvert_qc.tsv is
+    overwritten with different content, it is backed up (see
+    ``_backup_qc_tsv``).
+
+    ``physio_parent`` and ``dcm2bids_config``, when given, are recorded as the
+    ``PhysioParent``/``Dcm2BidsConfigPath`` values in mriconvert_qc.json;
+    when omitted, a value already recorded there is preserved (see
+    ``_write_scans_json``).
+
+    Returns the number of preserved rows whose file is no longer found on
+    disk, for the caller to fold into an end-of-run summary.
+    """
+    if not bids_root.is_dir():
+        return 0
+
+    tsv_path = _qc_tsv_path(bids_root)
+
+    try:
+        import nibabel as nib
+    except ImportError:
+        nib = None
+        _safe_print(
+            "WARNING: nibabel not installed; the 'dimensions' column in "
+            "mriconvert_qc.tsv will be empty. Install nibabel to populate it."
+        )
+
+    rows: list[list] = []
+    for dirpath, dirnames, filenames in os.walk(bids_root):
+        dirnames[:] = [d for d in dirnames if d != "tmp_dcm2bids"]
+        for fname in filenames:
+            if fname.endswith(".nii.gz"):
+                rows.append(
+                    _scans_row(Path(dirpath) / fname, bids_root, nib)
+                )
+    rows.sort(key=lambda r: r[0])
+
+    existing = _read_existing_scans(tsv_path) if tsv_path.is_file() else None
+    missing_count = 0
+    if existing is None:
+        merged_rows = rows
+        added = len(rows)
+    else:
+        _, existing_rows = existing
+        # Non-user, non-key columns the generator owns. 'dimensions' is
+        # excluded when nibabel is missing so its empty values are not
+        # reported as spurious deviations.
+        compare_columns = [
+            c
+            for c in _SCANS_COLUMNS
+            if c not in _SCANS_USER_COLUMNS
+            and c != "filename"
+            and not (c == "dimensions" and nib is None)
+        ]
+        deviations = _scans_deviations(existing_rows, rows, compare_columns)
+        if deviations:
+            _report_scans_deviations(bids_root, deviations)
+        missing_count = sum(1 for kind, _ in deviations if kind == "missing")
+
+        name_idx = _SCANS_COLUMNS.index("filename")
+        existing_by_name = {r.get("filename", ""): r for r in existing_rows}
+        new_by_name = {r[name_idx]: r for r in rows}
+
+        merged_rows = []
+        added = 0
+        for name in sorted(set(existing_by_name) | set(new_by_name)):
+            if name in existing_by_name:
+                # Already present (whether or not it's a "partially matching"
+                # row, i.e. identical besides the reviewer columns): keep it
+                # untouched rather than overwriting it.
+                old_row = existing_by_name[name]
+                merged_rows.append([old_row.get(c, "") for c in _SCANS_COLUMNS])
+            else:
+                # Newly present on disk and absent from mriconvert_qc.tsv: add it.
+                merged_rows.append(new_by_name[name])
+                added += 1
+
+    buf = io.StringIO(newline="")
+    writer = csv.writer(buf, delimiter="\t")
+    writer.writerow(_SCANS_COLUMNS)
+    writer.writerows(merged_rows)
+    content = buf.getvalue()
+
+    backup_path = _backup_qc_tsv(tsv_path, content)
+    if backup_path is not None:
+        _safe_print(f"Backed up previous {tsv_path.name} to {backup_path}")
+
+    with tsv_path.open("w", newline="", encoding="utf-8") as f:
+        f.write(content)
+    if existing is None:
+        _safe_print(f"Wrote {tsv_path} ({len(merged_rows)} scan(s))")
+    else:
+        _safe_print(
+            f"Updated {tsv_path} ({len(merged_rows)} scan(s), {added} newly "
+            "added; existing rows preserved)"
+        )
+
+    _write_scans_json(bids_root, physio_parent, dcm2bids_config)
+
+    return missing_count
+
+
+def mriconvert_cmd(args: argparse.Namespace) -> int:
+    if args.nconvert < 1:
+        sys.exit("Error: -n/--nconvert must be >= 1.")
+
+    input_root = Path(args.input).resolve()
+    if not input_root.is_dir():
+        sys.exit(f"Error: input directory not found: {input_root}")
+
+    output_dir = Path(args.output).resolve()
+
+    physio_parent = Path(args.physio_parent).resolve() if args.physio_parent else None
+    if physio_parent is not None and not physio_parent.is_dir():
+        _safe_print(f"WARNING: -y/--physio directory not found: {physio_parent}")
+
+    dcm2bids_config = Path(args.config).resolve() if args.config else None
+
+    # --maps: skip the dcm2bids conversion entirely and only (re)generate the
+    # mriconvert_qc.tsv/mriconvert_qc.json tabular outputs for every project in scope from the
+    # already-converted BIDS data under OUTPUT_DIR. The config, pydicom, and the
+    # dcm2bids/dcm2niix tools are unused on this path, so none are required.
+    if args.maps:
+        if not output_dir.is_dir():
+            sys.exit(
+                f"Error: output directory not found: {output_dir}; run "
+                "mriconvert without -m/--maps first."
+            )
+        sessions = _discover_sessions(input_root, args)
+        missing_total = 0
+        for project in sorted({p for p, _, _ in sessions}):
+            missing_total += _generate_scans_tsv(
+                output_dir / project, physio_parent, dcm2bids_config
+            )
+        if missing_total:
+            print(
+                f"WARNING: {missing_total} mriconvert_qc.tsv row(s) across all "
+                "project(s) in scope reference file(s) no longer found on "
+                "disk (rows preserved; see WARNING(s) above)."
+            )
+        return 0
+
+    if dcm2bids_config is None:
+        sys.exit("Error: -c/--config is required unless -m/--maps is given.")
+    config_path = dcm2bids_config
+    if not config_path.is_file():
+        sys.exit(f"Error: config file not found: {config_path}")
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        import pydicom  # noqa: F401
+    except ImportError:
+        sys.exit(
+            "Error: pydicom is required for mriconvert. "
+            "Install it via 'uv sync' or 'pip install pydicom'."
+        )
+
+    dcm2bids = shutil.which("dcm2bids")
+    dcm2niix = shutil.which("dcm2niix")
+    missing = [
+        name for name, path in (("dcm2bids", dcm2bids), ("dcm2niix", dcm2niix))
+        if path is None
+    ]
+    if missing:
+        sys.exit(
+            f"Error: required tool(s) not found on PATH: {', '.join(missing)}."
+        )
+
+    sessions = _discover_sessions(input_root, args)
+    project = sessions[0][0]
+
+    log_path: Path | None = None
+    if args.log:
+        while True:
+            ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+            log_path = output_dir / "log" / f"mriconvert_{ts}_log.csv"
+            if not log_path.exists():
+                break
+            time.sleep(1)
+    log_writer = _LogWriter(log_path)
+
+    counts = {
+        STATUS_COMPLETE: 0,
+        STATUS_FAILURE: 0,
+        STATUS_NONEXISTENT: 0,
+        STATUS_EMPTY: 0,
+    }
+
+    def _one(triplet: tuple[str, str, str]) -> str:
+        p, s, e = triplet
+        start = _logging_now()
+        status, detail = _convert_one(
+            input_root, p, s, e, output_dir, config_path, dcm2bids,
+        )
+        line = f"{p}/{s}/{e}: {status}"
+        if detail:
+            line += f" — {detail}"
+        _safe_print(line)
+        log_writer.write(start, p, s, e, status)
+
+        archive_ok = False
+        if args.archive:
+            a_status, a_detail = archive_experiment(input_root, p, s, e)
+            a_line = f"  archive {p}/{s}/{e}: {a_status}"
+            if a_detail:
+                a_line += f" — {a_detail}"
+            _safe_print(a_line)
+            archive_ok = a_status in ARCHIVE_OK_STATUSES
+
+        if args.delete:
+            if args.archive:
+                if archive_ok:
+                    delete_experiment_dir(input_root, p, s, e)
+            elif status in _OK_STATUSES:
+                delete_experiment_dir(input_root, p, s, e)
+        return status
+
+    stop_progress = threading.Event()
+
+    def _progress_loop() -> None:
+        while not stop_progress.wait(5):
+            _render_progress()
+
+    progress_thread = threading.Thread(target=_progress_loop, daemon=True)
+    progress_thread.start()
+    try:
+        if args.nconvert <= 1:
+            for triplet in sessions:
+                counts[_one(triplet)] += 1
+        else:
+            with ThreadPoolExecutor(max_workers=args.nconvert) as ex:
+                futures = [ex.submit(_one, t) for t in sessions]
+                for fut in as_completed(futures):
+                    counts[fut.result()] += 1
+    finally:
+        stop_progress.set()
+        progress_thread.join()
+        _render_progress()  # clear any leftover progress lines (all sessions are done)
+
+    total = sum(counts.values())
+    print(f"\nProcessed {total} session(s):")
+    for status in (
+        STATUS_COMPLETE,
+        STATUS_FAILURE,
+        STATUS_NONEXISTENT,
+        STATUS_EMPTY,
+    ):
+        print(f"  {status}: {counts[status]}")
+    if log_path is not None:
+        print(f"Log written to {log_path}")
+
+    missing_total = 0
+    for project in sorted({p for p, _, _ in sessions}):
+        missing_total += _generate_scans_tsv(
+            output_dir / project, physio_parent, dcm2bids_config
+        )
+    if missing_total:
+        print(
+            f"WARNING: {missing_total} mriconvert_qc.tsv row(s) across all "
+            "project(s) in scope reference file(s) no longer found on disk "
+            "(rows preserved; see WARNING(s) above)."
+        )
+
+    bad = counts[STATUS_FAILURE] + counts[STATUS_NONEXISTENT]
+    return 0 if bad == 0 else 1