8.3. Space names, qform_code and sform_code

8.3.1. Overview

Throughout much of neuroimaging’s history, it has been useful to know whether the given dataset is still in its “original” or “native” space (or at least only rotated/shifted), or whether it has been aligned/warped to a template or reference (“standard”) space. There are different ways to encode this information in headers.

8.3.2. NIFTI: qform_code and sform_code

In NIFTI, the qform_code and sform_code values control this. These are each integer values that hierarchically encode whether the data are in “original” or in a “template” space—or, confusingly, whether it is an “arbitrary” space. The latter ambiguity seems a particularly unfortunate allowed choice; it was implemented to provide backwards compatability with the ANALYZE format that some software used. Unfortunately, such cases specifying an ambiguous space still get output in some software (NB: this should not happen in AFNI output).

The currently (as of Nov, 2023) recognized qform_code and sform_code scalar values, and their interpretations, are shown in the following table:

Value

Label

Description

0

NIFTI_XFORM_UNKNOWN

Arbitrary coordinates (Method 1).

1

NIFTI_XFORM_SCANNER_ANAT

Scanner-based anatomical coordinates.

2

NIFTI_XFORM_ALIGNED_ANAT

Coordinates aligned to another file’s, or to anatomical “truth”. This is ambiguous as to being in standard space or not.

3

NIFTI_XFORM_TALAIRACH

Coordinates aligned to Talairach-Tournoux Atlas; (0,0,0)=AC, etc.

4

NIFTI_XFORM_MNI_152

MNI 152 normalized coordinates.

5

NIFTI_XFORM_TEMPLATE_OTHER

Normalized coordinates (for any general standard template space). Added March 8, 2019.

Note

Why do we have qform_code and sform_code integers? In NIFTI, there are three methods that can be used for mapping the data values to grid coordinates, and these are conveniently called Method 1, Method 2 and Method 3. More details of this are provided in the NIFTI C-library code, but basically the [qs]form_code values encode which coordinate method should be used: Method 1 is the “old way” that applies only when qform_code = 0; Method 2 uses quatern_* and qoffset_* header info and applies when qform_code > 0; and Method 3 uses srow_* info and applies when sform_code > 0.

8.3.3. BRIK/HEAD: space names; map to/from NIFTI

Within the BRIK/HEAD format, the information about space is stored in the header in the TEMPLATE_SPACE attribute. It is also reflected in the filename itself, typically as either +orig or +tlrc (AFNI’s “view extension for the space”, seen with 3dinfo -av_space).

  • The view extension parts of the filename are fairly generic, reflecting simply being in native or some standard space specifically (NB: use of “+tlrc” isn’t just restricted to Talairach space—that is somewhat a legacy convention from The Old Days when there were a very small number of standard spaces).

  • In contrast, the TEMPLATE_SPACE is a more specific space name; it encodes a more specific version of Talairach (like TT_N27) or MNI or IBT or HaskinsPeds or NMT template; and for native space data, it is just ORIG.

There is a 1-to-1 mapping between AFNI view extension and the unambiguous [qs]form_code values, and then some extra information is necessary to deal with the arbitrary case. This will be done by setting the following AFNI environment variable:

AFNI_NIFTI_VIEW

The default view extension used for output when creating AFNI format datasets from NIFTI datasets.This variable is only applicable for sform and qform codes that do not have clearly defined views (sform/qform code = 2). Set to “tlrc” or “orig”. See also AFNI_DEFAULT_STD_SPACE and AFNI_NIFTI_PRIORITY. Note sform/qform code=5 can be used for spaces other than MNI or TLRC including MNI_ANAT or D99 spaces.

Essentially, the NIFTI-BRIK/HEAD space labeling rules are as follows:

  • NIFTI [qs]form_code values of 3, 4 or 5 denote that the dataset is in some standard space, and map to BRIK/HEAD view extensions of +tlrc. Furthermore, the latter’s TEMPLATE_SPACE attribute can carry more specific naming information about the template, even within the Talairach, MNI, IBT, etc. families.

  • NIFTI [qs]form_code values of 0 or 1 denote that the dataset is in some original or native coordinate space, and map to BRIK/HEAD view extensions of +orig. The latter’s TEMPLATE_SPACE should correspondingly be simply ORIG.

  • NIFTI [qs]form_code values of 2 will be interpreted as one of the following:

    • If AFNI_NIFTI_VIEW = tlrc, they will be treated as representing data in some standard space; these would map to BRIK/HEAD view extensions of +tlrc and TEMPLATE_SPACE attributes of TLRC.

    • If AFNI_NIFTI_VIEW = orig, they will be treated as representing data in some native or original coordinate space; these would map to BRIK/HEAD view extensions of +orig and TEMPLATE_SPACE attributes of ORIG.

Easy, right?

8.3.4. GUI visualization, with space considerations

Within the AFNI GUI, one cannot overlay a “+orig” dataset on a “+tlrc” one, and vice versa. This should generally not cause too much hassle. For example, when AFNI programs warp an original space dataset to a standard space template, the newly-warped output will pick up the template’s space attribute, so they can be overlayed without woe.

However, a potential difficulty arises when one has a NIFTI dataset with the ambiguous qform_code or sform_code value of 2, which can happen in some other software. AFNI will use the user-specified (or default) AFNI_NIFTI_VIEW value to interpret whether such a dataset should be treated as “+orig” or “+tlrc”. The user just needs to make sure that this environment variable is set appropriately for each of their use cases. It is a far, far better thing to not leave the interpretation to chance, and to change/fix the header qform_code and sform_code values directly (using nifti_tool or 3drefit).

8.3.5. Get header information

NIFTI dataset header information can be checked with nifti_tool. One can display the full header:

nifti_tool -disp_hdr -infiles DSET

... or specific field(s), like the qform_code and sform_code values:

nifti_tool -disp_hdr                           \
    -field qform_code -field sform_code        \
    -infiles DSET

For example, running the latter on the MNI152_2009_template_SSW.nii.gz template dataset produces:

N-1 header file 'MNI152_2009_template_SSW.nii.gz', num_fields = 2
  name                offset  nvals  values
  ------------------- ------  -----  ------
  qform_code           252      1    4
  sform_code           254      1    4

... which seems appropriate.

It is also useful to check and see if the NIFTI dataset has any extensions, which can be done with:

nifti_tool -disp_exts -infiles DSET

BRIK/HEAD dataset header information can be checked with 3dinfo. One can display the header information with:

3dinfo DSET

... or specific field(s), like space names, with:

3dinfo -space -av_space -gen_space -prefix DSET

For example, running the latter on the MNI152_T1_2009c+tlrc.HEAD template dataset produces:

MNI    +tlrc    MNI       MNI152_T1_2009c

... which also seems appropriate. One can also view header attributes with 3dAttribute, such as viewing all with:

3dAttribute -all DSET

... or specific field(s), like TEMPLATE_SPACE, with:

3dAttribute -name TEMPLATE_SPACE DSET

NB: one can also run 3dinfo and 3dAttribute on NIFTI datasets, and each will output their usual information still. This is in large part because AFNI readily inputs and outputs NIFTI.