Metadata-Version: 2.4
Name: siemensfile
Version: 0.3.0
Summary: Python package to read Siemens MRI raw data files (.dat) and reconstruct MR images.
Home-page: https://github.com/cenarius1985/SIEMENSFile
Author: Fernando Jose Ramirez
Author-email: fernando.ramirez.sarmiento@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12.4
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: mri-nufft
Requires-Dist: pydicom
Requires-Dist: openpyxl
Requires-Dist: h5py
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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:

```bash
pip install siemensfile
```

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

```bash
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

```python
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.**

| File | Content |
|---|---|
| `<name>_kspace.png` | k-space magnitude preview (log scale), one panel per slice |
| `<name>_reconstruction.png` | mosaic with the reconstructed magnitude image of every slice |
| `<name>_slice_NNN.dcm` | reconstruction as DICOM MR (`MRImageStorage`), one file per slice |
| `<name>_metadata.json` | flattened twix headers (protocol, geometry, acquisition parameters) |

### Example: 3D MPRAGE

```python
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

```python
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

```bash
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](https://github.com/pehses/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.
