nibabel.parrec

Read images in PAR/REC format.

This is yet another MRI image format generated by Philips scanners. It is an ASCII header (PAR) plus a binary blob (REC).

This implementation aims to read version 4.0 through 4.2 of this format. Other versions could probably be supported, but we need example images to test against. If you want us to support another version, and have an image we can add to the test suite, let us know. You would make us very happy by submitting a pull request.

PAR file format

The PAR format appears to have two sections:

General information

This is a set of lines each giving one key : value pair, examples:

.    EPI factor        <0,1=no EPI>     :   39
.    Dynamic scan      <0=no 1=yes> ?   :   1
.    Diffusion         <0=no 1=yes> ?   :   0

(from nibabel/tests/data/phantom_EPI_asc_CLEAR_2_1.PAR)

Image information

There is a # prefixed list of fields under the heading “IMAGE INFORMATION DEFINITION”. From the same file, here is the start of this list:

# === IMAGE INFORMATION DEFINITION =============================================
#  The rest of this file contains ONE line per image, this line contains the following information:
#
#  slice number                             (integer)
#  echo number                              (integer)
#  dynamic scan number                      (integer)

There follows a space separated table with values for these fields, each row containing all the named values. Here are the first few lines from the example file above:

# === IMAGE INFORMATION ==========================================================
#  sl ec  dyn ph ty    idx pix scan% rec size                (re)scale              window        angulation              offcentre        thick   gap   info      spacing     echo     dtime   ttime    diff  avg  flip    freq   RR-int  turbo delay b grad cont anis         diffusion       L.ty

1   1    1  1 0 2     0  16    62   64   64     0.00000   1.29035 4.28404e-003  1070  1860 -13.26  -0.00  -0.00    2.51   -0.81   -8.69  6.000  2.000 0 1 0 2  3.750  3.750  30.00    0.00     0.00    0.00   0   90.00     0    0    0    39   0.0  1   1    8    0   0.000    0.000    0.000  1
2   1    1  1 0 2     1  16    62   64   64     0.00000   1.29035 4.28404e-003  1122  1951 -13.26  -0.00  -0.00    2.51    6.98  -10.53  6.000  2.000 0 1 0 2  3.750  3.750  30.00    0.00     0.00    0.00   0   90.00     0    0    0    39   0.0  1   1    8    0   0.000    0.000    0.000  1
3   1    1  1 0 2     2  16    62   64   64     0.00000   1.29035 4.28404e-003  1137  1977 -13.26  -0.00  -0.00    2.51   14.77  -12.36  6.000  2.000 0 1 0 2  3.750  3.750  30.00    0.00     0.00    0.00   0   90.00     0    0    0    39   0.0  1   1    8    0   0.000    0.000    0.000  1

Orientation

PAR files refer to orientations “ap”, “fh” and “rl”.

Nibabel’s required affine output axes are RAS (left to Right, posterior to Anterior, inferior to Superior). The correspondence of the PAR file’s axes to RAS axes is:

  • ap = anterior -> posterior = negative A in RAS = P

  • fh = foot -> head = S in RAS = S

  • rl = right -> left = negative R in RAS = L

We therefore call the PAR file’s axis system “PSL” (Posterior, Superior, Left).

The orientation of the PAR file axes corresponds to DICOM’s LPS coordinate system (right to Left, anterior to Posterior, inferior to Superior), but in a different order.

Data type

It seems that everyone agrees that Philips stores REC data in little-endian format - see https://github.com/nipy/nibabel/issues/274

Philips XML header files, and some previous experience, suggest that the REC data is always stored as 8 or 16 bit unsigned integers - see https://github.com/nipy/nibabel/issues/275

Data Sorting

PAR/REC files have a large number of potential image dimensions. To handle sorting of volumes in PAR/REC files based on these fields and not the order slices first appear in the PAR file, the strict_sort flag of nibabel.load (or parrec.load) should be set to True. The fields that are taken into account during sorting are:

  • slice number

  • echo number

  • cardiac phase number

  • gradient orientation number

  • diffusion b value number

  • label type (ASL tag vs. control)

  • dynamic scan number

  • image_type_mr (Re, Im, Mag, Phase)

Slices are sorted into the third dimension and the order of preference for sorting along the 4th dimension corresponds to the order in the list above. If the image data has more than 4 dimensions these will all be concatenated along the 4th dimension. For example, for a scan with two echos and two dynamics, the 4th dimension will have both echos of dynamic 1 prior to the two echos for dynamic 2.

The``get_volume_labels`` method of the header returns a dictionary containing the PAR field labels for this 4th dimension.

The volume sorting described above can be enabled in the parrec2nii command utility via the option “–strict-sort”. The dimension info can be exported to a CSV file by adding the option “–volume-info”.

Module Attributes

supported_versions

PAR header versions we claim to understand

image_def_dtype

Deprecated; please don't use

slice_orientation_codes

slice orientation codes

Functions

exts2pars(exts_source)

Parse, return any PAR headers from NIfTI extensions in exts_source

load(filename, *[, mmap, permit_truncated, ...])

Create PARREC image from filename filename

one_line(long_str)

Make maybe mutli-line long_str into one long line

parse_PAR_header(fobj)

Parse a PAR header and aggregate all information into useful containers.

vol_is_full(slice_nos, slice_max[, slice_min])

Vector with True for slices in complete volume, False otherwise

vol_numbers(slice_nos)

Calculate volume numbers inferred from slice numbers slice_nos

Classes

PARRECArrayProxy(file_like, header, *[, ...])

Initialize PARREC array proxy

PARRECHeader(info, image_defs[, ...])

PAR/REC header

PARRECImage(dataobj, affine[, header, ...])

PAR/REC image

Exceptions

PARRECError

Exception for PAR/REC format related problems.