Ctrl+K

deepmr.io.read_rawdata

Contents

deepmr.io.read_rawdata#

deepmr.io.read_rawdata(filepath, acqheader=None, device='cpu', verbose=0)[source]#

Read kspace data from file.

Currently, handles data written in ISMRMD format [1] (vendor agnostic) and GEHC proprietary raw data (requires access to a private repository).

Parameters:

  • filepath (str) – Path to kspace file. Supports wildcard (e.g., /path-to-data-folder/*.h5).

  • acqheader (Header, optional) – Acquisition header loaded from trajectory. If not provided, assume Cartesian acquisition and infer from data. The default is None.

  • device (str, optional) – Computational device for internal attributes. The default is cpu.

  • verbose (int, optional) – Verbosity level (0=Silent, 1=Less, 2=More). The default is 0.

Returns:

  • data (torch.tensor) – Complex k-space data.

  • head (Header) – Metadata for image reconstruction.

Example

>>> import deepmr

Get the filename for an example .mrd file.

>>> filepath = deepmr.testdata("mrd")

Load the file contents.

>>> data, head = deepmr.io.read_rawdata(filepath)

The result is a data/header pair. Data contains k-space data. Here, it represents a 2D spiral acquisition with 1 slice, 36 coils, 32 arms and 1284 samples per arm:

>>> data.shape
torch.Size([1, 36, 1, 32, 1284])

Head contains the acquisition information. We can inspect the k-space trajectory and dcf size, the expected image shape and resolution:

>>> head.traj.shape
torch.Size([1, 32, 1284, 2])
>>> head.dcf.shape
torch.Size([1, 32, 1284])
>>> head.shape
tensor([  1, 192, 192])
>>> head.ref_dicom.SliceThickness
'5.0'
>>> head.ref_dicom.PixelSpacing
[1.56, 1.56]

Head also contains contrast information (for forward simulation and parameter inference):

>>> head.FA
10.0
>>> head.TE
0.86
>>> head.TR
4.96

Notes

The returned data tensor contains raw k-space data. Dimensions are defined as following:

  • 2Dcart: (nslices, ncoils, ncontrasts, ny, nx).

  • 2Dnoncart: (nslices, ncoils, ncontrasts, nviews, nsamples).

  • 3Dcart: (nx, ncoils, ncontrasts, nz, ny).

  • 3Dnoncart: (ncoils, ncontrasts, nviews, nsamples).

When possible, data are already pre-processed:

  • For Cartesian data (2D and 3D) readout oversampling is removed if the number of samples along readout is larger than the number of rows in the image space (shape[-1]).

  • For Non-Cartesian (2D and 3D), fov is centered according to trajectory and isocenter info from the header.

  • For separable acquisitions (3D stack-of-Non-Cartesians and 3D Cartesians), k-space is decoupled via FFT (along slice and readout axes, respectively).

The returned head (deepmr.Header()) is a structure with the following fields:

  • shape (torch.Tensor):

    This is the expected image size of shape (nz, ny, nx).

  • resolution (torch.Tensor):

    This is the expected image resolution in mm of shape (dz, dy, dx).

  • t (torch.Tensor):

    This is the readout sampling time (0, t_read) in ms. with shape (nsamples,).

  • traj (torch.Tensor):

    This is the k-space trajectory normalized as (-0.5, 0.5) with shape (ncontrasts, nviews, nsamples, ndims).

  • dcf (torch.Tensor):

    This is the k-space sampling density compensation factor with shape (ncontrasts, nviews, nsamples).

  • FA (torch.Tensor, float):

    This is either the acquisition flip angle in degrees or the list of flip angles of shape (ncontrasts,) for each image in the series.

  • TR (torch.Tensor, float):

    This is either the repetition time in ms or the list of repetition times of shape (ncontrasts,) for each image in the series.

  • TE (torch.Tensor, float):

    This is either the echo time in ms or the list of echo times of shape (ncontrasts,) for each image in the series.

  • TI (torch.Tensor, float):

    This is either the inversion time in ms or the list of inversion times of shape (ncontrasts,) for each image in the series.

  • user (dict):

    User parameters. Some examples are:

    • ordering (torch.Tensor):

      Indices for reordering (acquisition to reconstruction) of acquired k-space data, shaped (3, nslices * ncontrasts * nview), whose rows are contrast_index, slice_index and view_index, respectively.

    • mode (str):

      Acquisition mode (2Dcart, 3Dcart, 2Dnoncart, 3Dnoncart).

    • separable (bool):

      Whether the acquisition can be decoupled by fft along slice/ readout directions (3D stack-of-noncartesian / 3D cartesian, respectively) or not (3D noncartesian and 2D acquisitions).

    • slice_profile (torch.Tensor):

      Flip angle scaling along slice profile of shape (nlocs,).

    • basis (torch.Tensor):

      Low rank subspace basis for subspace reconstruction of shape (ncoeff, ncontrasts).

  • affine (np.ndarray):

    Affine matrix describing image spacing, orientation and origin of shape (4, 4).

  • ref_dicom (pydicom.Dataset):

    Template dicom for image export.

  • flip (list):

    List of spatial axis to be flipped after image reconstruction. The default is an empty list (no flipping).

  • transpose (list):

    Permutation of image dimensions after reconstruction, depending on acquisition mode:

    • 2Dcart: reconstructed image has (nslices, ncontrasts, ny, nx) -> transpose = [1, 0, 2, 3]

    • 2Dnoncart: reconstructed image has (nslices, ncontrasts, ny, nx) -> transpose = [1, 0, 2, 3]

    • 3Dcart: reconstructed image has (ncontrasts, nz, ny, nx) -> transpose = [0, 1, 2, 3]

    • 3Dnoncart: reconstructed image has (nx, ncontrasts, nz, ny) -> transpose = [1, 2, 3, 0]

    The default is an empty list (no transposition).

References

[1]: Inati, S.J., Naegele, J.D., Zwart, N.R., Roopchansingh, V., Lizak, M.J., Hansen, D.C., Liu, C.-Y., Atkinson, D., Kellman, P., Kozerke, S., Xue, H., Campbell-Washburn, A.E., Sørensen, T.S. and Hansen, M.S. (2017), ISMRM Raw data format: A proposed standard for MRI raw datasets. Magn. Reson. Med., 77: 411-421. https://doi.org/10.1002/mrm.26089

Contents