vxconvert DICOM-to-BIDS conversion

vxconvert wraps HeuDiConv + dcm2niix to convert DICOM files into BIDS-organized NIfTI volumes with JSON sidecars. All paths below are relative to the virdx/vxconvert repo root.

Two-phase pipeline

Phase 1: Grouping + Classification (header-only)

1. validate_dicom() (from heudiconv) — reads each DICOM with stop_before_pixels=True to avoid pixel I/O during scanning.
2. filter_dicom() (src/vxconvert/grouping.py) — rejects non-MR, localizers, scouts, derived series. Typically filters ~30–50% of input files.
3. custom_grouping_study_then_seqname() (src/vxconvert/grouping.py) — groups by StudyInstanceUID → SeriesInstanceUID, with further splits on echo/TR when multiple are present.
4. custom_seqinfo() (src/vxconvert/grouping.py) — extracts ~40 metadata fields from DICOM headers into a custom SeqInfo tuple.
5. infotodict() (src/vxconvert/infotodict.py) — classifies each SeqInfo into BIDS modalities (anat/dwi/fmap/perf/func) using SequenceClassifier.

Phase 2: Pixel conversion

dcm2niix reads full DICOM files (including pixels) per series → outputs NIfTI + JSON sidecars.

Output structure: sub-{subject}/ses-{session}/{modality}/{filename}.nii.gz + .json.

vicom integration

Enable with HEUDICONV_ENABLE_VICOM=true. When enabled, postprocess_json() (src/vxconvert/postprocessing.py) calls vicom_adapter() to enrich JSON sidecars with Volume-compatible fields:

• Converts JSON keys to snake_case.
• Sets volume_type from BIDS suffix: DWI, T1, T2, ADC, PM (parametric maps), or MISC.
• Sets is_trace and is_synthetic flags for trace-weighted DWI and computed ADC maps.
• Extracts b_value / adc_b_values from filename patterns like bval-1000 or bval-0and1000.
• Computes image_plane, field_of_view, spacing from the NIfTI affine matrix via vicom’s get_all_header_data.
• Timing normalization:
  • echo_time: normalized to milliseconds internally, output in seconds.
  • repetition_time, inversion_time: converted from BIDS seconds to milliseconds (multiply by 1000).
• Renames: study_instance_uid → study_identifier, series_instance_uid → series_identifier, etc.

vicom must be installed separately (pip install vicom); raises ImportError if missing.

Key files

• src/vxconvert/grouping.py — filter_dicom, custom_seqinfo, custom_grouping_study_then_seqname
• src/vxconvert/infotodict.py — infotodict classification logic
• src/vxconvert/postprocessing.py — postprocess_json, vicom_adapter
• src/vxconvert/bids.py — SequenceClassifier, BidsEntities
• src/vxconvert/cli/convert.py — CLI entrypoint, batch mode via ProcessPoolExecutor

vxData integration (removed, 2026-04)

The old ingestion path that fed converted volumes into the data platform (worker f_20260409_vxconvert_volumes) did not survive the data-platform archive (2026-05-27) and has no successor in mono/apps/vxdata-jobs. The target payload types themselves are alive and unchanged in mono/packages/vxdata-schemas/src/vxdata/schemas/payloads.py (ImagingStudy, Volume, incl. Volume.sequence_name) — so the sidecar fields vicom_adapter emits still map onto current Volume fields. Only the job that did the uploading is missing; vxconvert itself is a standalone converter today.