dcm-to-bids

name	dcm-to-bids
description	Convert a DICOM directory tree into a BIDS-organised dataset with NIfTI images. Covers single-step NIfTI conversion and full BIDS layout creation.
compatibility	Requires the medmcp-dicom MCP server (console script medmcp-dicom).
license	Apache-2.0

Workflow — dcm-to-bids

Step 1 — Gather inputs and confirm

Ask the user for two things only. Provide suggested paths for both:

• dicom_root: root directory of the DICOM data (tool scans recursively)
• output_dir: where to write the BIDS dataset

Once you have both paths, compute the proposed dataset name as the last path component of dicom_root with _bids appended. For example, if dicom_root is /data/study_2024, the dataset name is study_2024_bids.

Then present the concrete values back to the user — fill in the actual strings, not placeholders:

Proposed settings

• DICOM source: /data/study_2024
• BIDS output: /data/study_2024_bids
• Dataset name: study_2024

Reply yes to proceed, or provide a different dataset name.

Do not call any tool until the user replies "yes" (or equivalent explicit confirmation). A different dataset name counts as a reply — confirm again with the updated name before proceeding.

Step 2 — Full BIDS conversion

Call build_bids_dataset(dicom_root, output_dir, dataset_name, anonymize=True).

• anonymize=True (default): subject labels are sub-001, sub-002 … only.
• anonymize=False: source patient IDs are also written to participants.tsv. Only set this if the user explicitly asks for non-anonymous output.

Follow the _render instructions in the result.

If unclassified is non-empty: display the unclassified series in a separate section and ask the user how to handle them (rename manually, skip, or note for later). Do not re-run the whole conversion just to fix suffix labels.

---

Gotchas

• Call on the dataset root, not a subdirectory — the tool scans recursively.
• dcm2niix required: dcm2niix must be on the PATH. If not installed, the tool returns a clear error with installation instructions. Do not retry; report the error and the install hint to the user.
• PHI: anonymize=True is the default. Never set anonymize=False unless the user explicitly requests non-anonymous output.
• Research software: flag any context that suggests clinical decision-making and stop. This package is not licensed for clinical use.
• Unclassified series: series that do not match any suffix rule are still converted and placed in anat/ with a fallback suffix. They appear in the unclassified list so the user can review them.
• Multi-echo sequences: each echo is written as a separate NIfTI with an _echo-N label appended to the filename. This is BIDS-valid but the user should verify the echo ordering.
• DWI series: dcm2niix automatically produces .bval and .bvec files alongside the NIfTI. These are moved to the BIDS dwi/ directory.
• Duplicate series per session: if two series map to the same sub/ses/suffix combination, _run-01 / _run-02 labels are added automatically.