MINC/SoftwareDevelopment/MINC1 File Format Reference

MINC 1.0 Name and Usage Conventions

The MINC (Medical Imaging NetCDF) 1.0 file format was designed as a specification for medical imaging data building upon the NetCDF (Network Common Data Format) standard.

This document is intended to describe the specifics of this layering by defining the essential variables, attributes, and conventions used by MINC files. While this information applies specifically to the implementation of MINC 1.0, much of this information is expected to apply to MINC 2.0. The major change will be in the adaptation or elimination of structural objects as a result of the transition from NetCDF to HDF5 (Hierarchical Data Format). MINC 2.0 probably will require considerable expansion and clarification of this specification.

Much of the information in this document is excerpted from the {\it MINC Programmer's Reference Manual} by Peter Neelin.

NOTE: Throughout this document, literal MINC variable names, attribute names, and predefined values are set in a fixed-width font.

Dimensions

MINC associates the dimensions of a medical image with standard textual names, such as 'xspace' or 'time'. This association serves both to clarify the interpretation of each dimension and to specify the relationships among variables which share the same coordinate space. The length of a dimension is defined when the file is created.

NetCDF's model of a dimension is very simple, associated just a name, a numeric identifier, and a length with each dimension. To extend this model to represent the full set of attributes associated with a MINC dimension object, MINC relies on the concept of a 'dimension variable', which is a variable with the same name as the corresponding dimension object.

While specialized applications can and occasionally do define additional dimensions, MINC defines the following standard dimension names:

• xspace - Spatial axis, defined to increase from patient left to patient right.
• yspace - Spatial axis, defined to increase from patient posterior to patient anterior.
• zspace - Spatial axis, defined to increase from patient inferior to patient superior.
• time - Time axis.
• xfrequency - Spatial frequency axis.
• yfrequency - Spatial frequency axis.
• zfrequency - Spatial frequency axis.
• tfrequency - Temporal frequency axis.
• vector_dimension - Axis used for components of a vector field. If present, this dimension should be the fastest-varying dimension of the image variable. Unlike the rest of the dimensions, this dimension is not associated with a dimension variable.

Variables

MINC variables fall into one of four classes. The first is the {\it group} class, which define data objects and names which are used to hold actual image data and supporting information. The second is the var-attribute class, which contain data qualifying another variable, for example, by specifying the range of the other variable's data. The third and fourth are the dimension class and the {\it dimension-width} class, which are used to specify the properties of the dimensions in a MINC file.

Standard MINC Variable Names

• rootvariable - This variable, which is of class {\it group}, exists for structural purposes only. It forms the base of the MINC variable hierarchy.
• image - The image variable is of class group. It is the variable which actually contains image data in a MINC file, so it is defined using whatever type and dimensions are required to represent the image. By convention, MINC considers the first spatial dimension of the image variable to be the 'slice' dimension, and any other spatial dimensions are considered to be 'image' dimensions. The {\tt image variable is the only variable whose presence in a MINC file is mandatory}.

• image-min - The image-min variable is of class {\it var-attribute}. If per-slice scaling of the image data is enabled, this variable will contain 64-bit floating-point data which provides the lowest value of the real range for each slice. The dimensionality of this and the image-max variable will correspond to the dimensionality of the image variable, omitting the 'image' dimensions and vector dimension, if used. For example, for typical fMRI data, the image-min variable will be a 2D array with {\tt time} and the first spatial declared as its dimensions. Note that is is legal for the image-min to have lower dimensionality. For example, the variable may be a scalar to specify a single, global maximum real value.
• image-max - The image-max is the counterpart to the image-min variable. Its use and structure is directly analogous, however it contains the maximum value of the real data range for each data slice.
• study - This variable is of class group. It contains no useful data, but serves only to group those attributes which contain information about the study of which this image is a part. Since the variable contains no data, the type is irrelevant.
• patient - Like the study variable, this variable is of class group and contains no data. It serves to group the attributes which specify the identification and characteristics of the patient.
• acquisition - The acquisition variable is of class group. Like the study and patient variables, the acquisition variable never contains useful data, but serves only to group those attributes which contain information about the image acquisition parameters, modality, etc.
• xspace - Variable of class dimension which groups the attributes specifying the X axis.
• yspace - Variable of class dimension which groups the attributes specifying the Y axis.
• zspace - Variable of class dimension which groups the attributes specifying the Z axis.
• time - Variable of class dimension which groups the attributes specifying the time axis.
• xfrequency - Variable of class dimension which groups the attributes specifying the spatial frequency axis.
• yfrequency - Variable of class dimension which groups the attributes specifying the spatial frequency axis.
• zfrequency - Variable of class dimension which groups the attributes specifying the spatial frequency axis.
• tfrequency - Variable of class dimension which groups the attributes specifying the temporal frequency axis.
• xspace-width - Variable of class dimension-width which groups the attributes specifying the width of samples along the X axis.
• yspace-width - Variable of class dimension-width which groups the attributes specifying the width of samples along the Y axis.
• zspace-width - Variable of class dimension-width which groups the attributes specifying the width of samples along the Z axis.
• time-width - Variable of class dimension-width which groups the attributes specifying the width of samples along the time axis.
• xfrequency-width - Variable of class dimension-width which groups the attributes specifying the width of samples along the spatial frequency axis.
• yfrequency-width - Variable of class dimension-width which groups the attributes specifying the width of samples along the spatial frequency axis.
• zfrequency-width - Variable of class dimension-width which groups the attributes specifying the width of samples along the spatial frequency axis.
• tfrequency-width - Variable of class dimension which groups the attributes specifying the width of samples along the temporal frequency axis.

Hierarchy

In MINC 1.0, group and var-attribute variables may be considered to exist in a tree-structured hierarchy. The base of the hierarchy is located at the rootvariable. This variable exists solely to form the base node of the hierarchy tree. The image, acquisition, patient, and study variables form the next layer of the hierarchy. Below the image variable are the image-min and image-max variables.

Other, non-standard variables may be added to this hierarchy as desired.

Because NetCDF is a non-hierarchical format, MINC uses a the {\tt parent} and children attributes to implement this hierarchy. In actual practice, the MINC 1.0 format relies this hierarchy very loosely, if at all. However, MINC 2.0, being based on a fundamentally hierarchical format (HDF5), will use and extend this hierarchy.

Attributes

In MINC, attributes are used to specify additional information about an object. These attributes can be considered to fall into three broad categories: Those which are defined by the NetCDF standard itself, those which play a structural role in defining the MINC file organization, and those which contain actual data or parameters associated with the file.

NetCDF attributes may be either global to the file or local to a specific variable. Only two global attributes are used as part of the MINC specification, history and title. These string attributes are both part of the NetCDF specification. All other MINC attributes are local to a specific variable.

Standard NetCDF Attribute Usage

These attributes are defined by the NetCDF standard itself.

• units - String which specifies the units of a variable's data, if applicable. The units should be compatible with the UCAR udunits library. In MINC 1.0, this attribute is generally included for informational purposes only and is not interpreted by the MINC library code.
• long_name - String giving a human-readable textual description of the variable. Included for informational purposes.
• valid_range - A vector of two numbers which specifies both the minimum and maximum valid values for this variable. Values outside this range must be treated as missing or uninitialized. In MINC, the order of the two values in the vector is not significant.

This attribute must not be defined if either the valid_min or the valid_max attributes are defined.

These attributes should be considered mandatory for the MINC image variable, unless the variable uses the default range, which is defined to be the full range of an (possibly signed or unsigned) integer type or the interval [0.0, 1.0] for floating point types. They are not required for any other MINC variable.

• valid_max - Scalar number which gives the maximum value allowed for the variable. Note that the presence of valid_max and valid_range are mutually exclusive.

• valid_min - Scalar number which gives the minimum value allowed for the variable. Note that the presence of valid_max and valid_range are mutually exclusive.

• _FillValue This is a scalar numeric value which gives the value to be used to fill in any value which is not explicitly written, or which falls outside the defined valid range of the data.

• history - A global string attribute for an audit trail. This is a character array with a line for each invocation of a program that has modified the dataset. All MINC and NetCDF applications should append a line containing: date, time of day, user name, program name and command arguments for each processing step. This attribute should be considered mandatory.

• title - A global string attribute which provides a description of the MINC file's contents. In practice this is optional and somewhat rarely used.

MINC Structural Attributes

Many MINC attributes are used to describe the types of variables and the relationships among variables.

These variables are considered 'structural' in the sense that they convey no useful information about the medical image stored in the MINC file, but instead serve to support the MINC format itself.

Each of these attributes should be considered mandatory for any MINC standard variable, with the following exceptions: The {\tt signtype} attribute is required only for variables of integral type, and the parent and children attributes are required only for variables of class group or var-attribute. They are not used for variables of class dimension or dimension-width.

• vartype - String identifying the type (or class) of the variable. It must be one of 'group________', '{\tt dimension____}', 'dim-width____, or 'var_attribute'.
• varid - String which identifies the variable's relationship to the MINC specification. All MINC standard variables should set this attribute to 'MINC standard variable'. Non-standard variables may either ignore this attribute or set it to some other string value.
• signtype - Because MINC, unlike NetCDF, differentiates between signed and unsigned integral types, this attribute is required to define the format of variables which store data of an integral type. The only legal values are either the string '{\tt signed__}' or the string 'unsigned'. For 8-bit integers, the default is unsigned, for all other integer types the default is signed__.
• parent - String identifying by name the parent variable of this variable. If the string is empty (of length zero), the variable is at the root of the hierarchy.
• children - List of the names of the variables which are considered children of this variable. The list is separated by newline characters.
• version - String identifying the version of this variable. In MINC 1.0, this string is always set to 'MINC Version\ \ \ \ 1.0' for MINC standard variables.

MINC Informational Attributes

Informational attributes in MINC may be of either a text string or a number.

Some string attributes are 'freeform' and may contain any value without restrictions on format and length. Other string attributes are assumed to have a specific format. Still other string attributes must contain one of several well-known values. When this is the case, the well-known strings are padded with underscore characters to the length of the longest legal value.

Another type of string attribute is the 'pointer' or 'variable' attribute. These attributes take the form '{\tt --->{\it var-name}}'. A typical example is the image variable's '{\tt image-max}' attribute, which in most MINC files contains the value '--->image-max', indicating that the image-max attribute value is stored in the variable of the same name.

Numeric attributes may be either integer or floating-point format. MINC includes attribute access routines which will automatically convert a value to the desired type on retrieval.

image variable attributes

• image-max - An string 'pointer' attribute containing the variable name that stores the real value maximum for the image. In most cases the variable has the same name as the attribute.

• image-min - Like image-max, but points to the {\tt image-min} variable for the image.

• complete - A boolean attribute (with values 'true_' or 'false') that indicates whether the variable has been written in its entirety. This can be used to detect program failure when writing out images as they are processed : complete is set to {\tt false} at the beginning and set to true_ when all data has been processed and written to the file.

study variable attributes

These attributes are grouped with the study variable for purposes of namespace organization. They are modeled after ACR-NEMA conventions. All of these attributes are optional, and have no default value defined.

• start_time - String giving the time and date of the start of the study, in the format 'YYYYMMDD HHMMSS.FFFFFF', where 'FFFFFF' is an string representation of fractional seconds. Either the entire time representation, or the fractional seconds, may be omitted if not required.
• start_year - Number giving the year of the start of date the study.
• start_month - Number giving the month (1-12) of the start date of the study.
• start_day - Number giving the day (1-31) of the start date of the study.
• start_hour - Number giving the hour (0-23) of the start time of the study.
• start_minute - Number giving the minute (0-59) of the start time of the study.
• start_seconds - Number giving the seconds (including fractions of a second, if required) of the start time of the study.
• modality - String which represents the imaging modality used, one of: PET__, SPECT, GAMMA, MRI__, MRS__, MRA__, CT___, DSA__, DR___, or label.
• manufacturer - String specifying the name of the imaging device manufacturer.
• device_model - String specifying the model of the imaging device.
• institution - String identifying the institution conducting the study.
• department - String identifying the department conducting the study.
• station_id - String identifying the specific imaging system which generated the image.
• referring_physician - String giving the name of the patient's primary physician.
• attending_physician - String giving the name of the physician administering the examination.
• radiologist - String giving the name of the radiologist interpreting the examination.
• operator - String giving the name of the operator of the imaging device.
• admitting_diagnosis - String description of the admitting diagnosis.
• procedure - String description of the procedure employed.
• study_id - String identifying the study.

patient variable attributes

These attributes are grouped with the patient variable for purposes of namespace organization. They are modeled after ACR-NEMA conventions for patient identification. All of these attributes are optional, and have no default value defined.

• full_name - String specifying the full name of the patient.
• other_names - String giving other names for the patient.
• identification - String specifying identification information for the patient.
• other_ids - String giving other identification information for the patient.
• birthdate - String specifying the patient's birthdate in the form 'YYYYMMDD'.
• sex - String specifying the patient's sex: 'male__', 'female' or 'other_'.
• age - Number giving the patient's age in years.
• weight - Number patient's weight in kilograms.
• size - Number giving patient's height or length in metres.
• address - String giving the patient's address.
• insurance_id - String giving the patient's insurance plan id.

acquisition variable attributes

These attributes store parameters about the acquisition. All of these attributes are optional, and have no default value defined.

• protocol - String description of the protocol for image acquisition.
• scanning_sequence - String description of type of data taken (eg. for MR - IR, SE, PS, etc.).
• repetition_time - Number giving the time in seconds between pulse sequences.
• echo_time - Number giving the time in seconds between the middle of a 90 degree pulse and the middle of spin echo production.
• inversion_time - Time in seconds after the middle of the inverting RF pulse to the middle of the 90 degree pulse to detect the amount of longitudinal magnetization.
• num_averages - Number of times a given pulse sequence is repeated before any parameter is changed.
• imaging_frequency - Precession frequency in Hz of the imaged nucleus.
• imaged_nucleus - String specifying the nucleus that is resonant at the imaging frequency.
• radionuclide - String specifying the isotope administered.
• contrast_agent - String identifying the contrast or bolus agent.
• radionuclide_halflife Half-life of radionuclide in seconds.
• tracer - String identifying tracer labeled with radionuclide that was injected.
• injection_time - String giving time (and date) of injection.
• injection_year - Integer giving year of injection.
• injection_month - Integer giving month (1-12) of injection.
• injection_day - Integer giving day (1-31) of injection.
• injection_hour - Integer giving hour (0-23) of injection.
• injection_minute Integer giving minute (0-59) of injection.
• injection_seconds - Floating-point number giving seconds of injection.
• injection_length - Number giving the time duration of the injection (in seconds).
• injection_dose - Total dose of radionuclide or contrast agent injected (in units specified by dose_units).
• dose_units - String giving units of dose.
• injection_volume - Number giving the volume of injection in milliliters.
• injection_route - String identifying administration route of injection.

Dimension variable attributes

The attributes associated with either dimension or dimension width variables are given in this section.

• spacing - String with value 'regular__' for a regularly spaced grid or 'irregular' for irregular spacing of samples. If the value of this attribute is 'irregular, then the dimension variable must be a vector varying with the dimension of the same name. If this attribute is absent, a value of regular__ should be assumed. Can be used for both dimension and dimension width variables.

• step - Number indicating the step size between samples for regular spacing. This value may be negative to reverse orientation (to specify that xspace runs from patient right to left, for example). If the spacing is irregular, then the value can be an average step size. If this attribute is absent, a value of 1.0 should be assumed. Applies only to dimension variables.

• start - Number specifying the coordinate of the index 0 of the dimension. If this attribute is absent, a value of 0.0 should be assumed. Applies only to dimension variables.

• spacetype - String identifying the type of coordinate space. Currently one of 'native___' (the coordinate system of the scanner), 'talairach_' (a standardized coordinate system for brain images), or 'callosal__' (another standardized coordinate system). If this attribute is absent, the {\tt spacetype} should be assumed to be native. Applies only to dimension variables.

• alignment - String indicating the position of the coordinates relative to each sample, one of 'start_', '{\tt centre}', or 'end___'. If this attribute is absent, it is assumed to be start_ for the time dimension or centre for spatial dimensions. Applies only to dimension variables.

• direction_cosines - Numeric vector with 3 elements giving the direction cosines of the axes. Although axes are labeled x, y and z, they may in fact have a significantly different orientation - this attribute allows the direction relative to the true axes to be specified exactly. The vectors should be normalized unit vectors.

If these attributes are not present, they are assumed to have the following default values:

For xspace: [1, 0, 0], for yspace: [0, 1, 0], and for zspace: [0, 0, 1]

The direction_cosines attributes apply only to dimension variables.

• width - Numeric attribute which gives the full-width half-maximum width of all samples for regularly sampled dimensions. It can be used for irregular widths to specify the average width. If this attribute is absent, a value of 1.0 should be assumed. Applies only to dimension width variables.

• filtertype - String specifying the shape of the convolving filter. Currently, can be one of 'square____', '{\tt gaussian__}' or 'triangular'. If this attribute is absent, a value of square____ should be assumed. Applies only to dimension width variables.

Minimal MINC file

Of all of the variables, dimensions, and attributes described here, only the 'image' variable and its associated dimensions are required to define a valid MINC file.

Any missing attributes are assumed to have default values, or to be undefined.

Non-Standard Objects

While MINC specifies the structure and interpretation of a number of objects, typical MINC programs will operate gracefully with MINC files which contain non-standard constructs. This imposes two requirements on MINC programs. First, MINC programs must operate correctly on files which contain non-standard variables and attributes. Second, MINC programs must copy non-standard attributes and variables from the input file to the resulting output file without alteration.

This behaviour allows the addition of arbitrary variables and/or attributes for informational purposes that extend the standard MINC namespace.

References

 Russell K.~Rew et al, 'NetCDF User's Guide for C'
 [online], Unidata Program Center, Boulder, CO, 1997
 (http://www.unidata.ucar.edu/packages/netcdf/guidec/).
 
 'HDF5: A New Generation of HDF' [online], National Center for 
 Supercomputing Applications, University of Illinois, Urbana-Champaign,
 IL 2003 (http://hdf.ncsa.uiuc.edu/HDF5/).
 
 Peter Neelin, 'MINC Programmer's Reference Manual' [online], Montreal
 Neurological Institute, Montreal, QC, 1993
 
 American College of Radiology, National Electrical Manufacturers
 Association (ACR-NEMA) Standards Publication Number 300-1985, {\bf
 Digital Imaging and Communications}, National Electrical
 Manufacturers Association (NEMA), Washington, DC, 1986.

Author

Robert D. Vincent