io.read_mrd

Contents

io.read_mrd#

bartorch.io.read_mrd()#

Read the readouts of one encoding space of an ISMRMRD HDF5 file.

Each imaging and calibration readout is placed where its kspace_encode_step_1, kspace_encode_step_2 and loop counters say it belongs; a readout shorter than the others is right-aligned, where a partial echo’s samples belong. Noise readouts are returned apart; navigator, phase-correction, dummy-scan, feedback and surface-coil readouts are not read.

Parameters:

  • path (str) – The .h5 file.

  • encoding (int, default=0) – Encoding space to read, as the readouts’ encoding_space_ref names it.

  • group (str, default="dataset") – HDF5 group holding the header and the readouts.

  • trajectory_units ({None, "grid", "1/m", "fraction"}, default=None) – Units the file stores the trajectory in, to convert it to grid units: "1/m" is scaled by the reconstructed field of view along each axis, "fraction" (of the sampling bandwidth, within [-0.5, 0.5)) by the reconstructed matrix. None returns the trajectory as stored: ISMRMRD does not fix its units.

Returns:

A named tuple of

kspace

complex64, (*loops, coils, [partitions,] phase_encodes, readout): the loop counters – repetition, phase, slice, contrast, set, average, in that order – the header gives more than one position, then the channels; the partition axis is present when there is more than one. Zero where nothing was acquired. For a non-Cartesian space the phase encodes are the shots and the readout the samples of each, which is how NoncartesianSense takes them; the shots and partitions number what the header’s encoding limits state, or where it states none, what the readouts’ counters reach, and never the encoded matrix, which is the image’s.

mask, reference

bool, the shape of kspace without its coil axis: every placed sample, and the samples of parallel-imaging calibration readouts.

trajectory

float32, the shape of mask with (kx, ky, kz) last, or None when no readout carries one. Components a readout does not carry are zero.

noise

complex64, (coils, samples), the noise readouts side by side, or None.

axes

The name of each axis of kspace: the counter names, "coil", "partition", "phase_encode", "readout".

affine

float64 (4, 4) from voxel indices (x, y, z) of the image the header’s reconstructed matrix describes to RAS coordinates in millimetres, as write_nifti() and write_dicom() take it; None when the readouts carry no orientation.

header

The parsed ismrmrd.xsd.ismrmrdHeader.

readouts

One row per placed readout, in file order: the counters and flags, scan_counter, acquisition_time_stamp, physiology_time_stamp, sample_time_us, center_sample, and position, read_dir, phase_dir, slice_dir and patient_table_position in the scanner’s patient coordinates, millimetres for positions.

Return type:

MrdRaw

Raises:

  • ValueError – If the file has no header, the header has no such encoding space, no readout belongs to it, or a counter runs past the extent the header states.

  • ImportError – If h5py or ismrmrd is not installed.

Contents