SIEMENSFile

SIEMENSFile is a Python package for previewing, reading and processing Siemens .dat raw MRI files, and for reconstructing MR images. It extracts the raw k-space data and the scan metadata, and performs image reconstruction with centered inverse Fourier transforms. The Cartesian reconstruction pipeline supports 2D multi-slice, 2D multi-stack (e.g. sag+cor+tra localizers) and 3D acquisitions (e.g. MPRAGE), including Partial Fourier handling. Non-Cartesian reconstruction (radial/spiral via NUFFT) is planned.

Features

• Reads Siemens VD/VE raw data files (.dat, twix format) through the bundled twixtools.
• Cartesian reconstruction of:
  • 3D acquisitions: each partition (cPar) is treated as an individual slice — a 3D MPRAGE volume yields one image per partition.
  • 2D multi-stack acquisitions: stacks sharing the same slice counter are separated by spatial position from the acquisition header.
  • Partial Fourier 6/8: phase lines are mapped onto the full acquisition matrix using CenterLin; missing lines are zero-filled.
  • Partial Fourier 1/2 (interleaved): odd phase lines are interpolated from their even neighbours to remove the Nyquist ghost produced by zero-filling.
  • Readout centering: the echo peak (k-space center) is re-centered using CenterCol with an exact circular roll.
• Root-sum-of-squares (RMS) coil combination over all channels.
• Outputs per acquisition: k-space preview (PNG), reconstruction mosaic (PNG), one standard-compliant DICOM MR file per slice (MRImageStorage), and full metadata (JSON).
• Robust metadata extraction from the Siemens Phoenix protocol: TR/TE (ms), FOV, pixel spacing, slice thickness/spacing, 3D flag.

Installation

Install from PyPI:

pip install siemensfile

For a development setup with conda (see requirements.txt for pinned versions):

conda create -n siemensfile python=3.12 -y --override-channels -c conda-forge
conda activate siemensfile
pip install -r requirements.txt
pip install -e .

Requires Python 3.12+.

Usage

from siemensfile import siemensfile

metadata, kspace = siemensfile(r"path/to/meas_MID00068_FID09111_t1_mprage_tra.dat",
                               reconstruction="Cartesian")

kspace.shape   # [line, channel, column, slice] (complex k-space)

reconstruction accepts "Cartesian" (implemented) or "NonCartesian" (not yet implemented — raises NotImplementedError).

API change in 0.2.0: the keyword argument and its values were renamed from reconstruccion="Cartesiana"/"NoCartesiana" to reconstruction="Cartesian"/"NonCartesian", and all module-level functions were renamed to English (e.g. lectura_twix → read_twix_pipeline, extraer_metadata_recursivamente → extract_metadata_recursively).

Outputs

Results are written to an output folder next to the input .dat file. The folder is deleted and recreated on every run.

Example: 3D MPRAGE

metadata, kspace = siemensfile(r"meas_MID00068_FID09111_t1_mprage_tra.dat")
kspace.shape    # (224, 15, 352, 102) -> 102 axial partitions reconstructed

Example: multi-stack localizer

metadata, kspace = siemensfile(r"meas_MID00062_FID09105_localizer_sag+cor+tra.dat")
kspace.shape    # (288, 15, 512, 26) -> 26 slices (8 cor + 8 sag + 10 tra), ghost-free

Tests

python -m pytest tests/ -q

Known limitations

• No coil intensity inhomogeneity correction: sum-of-squares images keep the coil sensitivity profile (brighter periphery than the vendor reconstruction).
• Partial Fourier 6/8 is zero-filled (slight blur); homodyne reconstruction is not implemented.
• No parallel imaging (GRAPPA/R) support.
• No non-Cartesian (radial/spiral) reconstruction yet.
• ismrmrd_formato.py (ISMRMRD HDF5 export) is experimental and untested.

Credits and acknowledgements

This project builds on twixtools by Philipp Ehses, bundled under src/twixtools, which provides the core Siemens .dat reading functionality. This package extends it with image reconstruction. If you need a more complete tool for reading/writing Siemens raw data, check twixtools directly.