table of contents
LIPSIA     The Lipsia data format
The Lipsia data format

This Lipsia data format originates from the Vista data format which was developed by Art Pope and David Lowe at the University of British Columbia.

Lipsia employs a data file format that allows any collection of images to be stored in a single file. This allows, for example, to keep anatomical and functional images in one file. Each file is divided into two parts. The first part, which contains descriptions of the objects in the file, is represented entirely in ASCII so that it can be easily viewed and even edited using a text editor. For example, one can add a comment annotating an image by simply editing this part of the file. The second part of the file holds the image pixel values.

The Lipsia (Vista) file names should always have the extension '.v'. Anatomical and functional data can be viewed using the program 'vsview' which is only a simple viewer for Vista files, however. A more sophisticated and flexible way of visualizing Lipsia data is using the viewers 'vlv' and 'vlview'.

Display the ASCII header

Using our example data file 'structural.v', the ASCII header can be shown doing

more structural.v

Then, the following ASCII header appears on the screen:

V-data 2 {
        image: image {
                data: 0
                length: 7180800
                nbands: 170
                nframes: 170
                nrows: 240
                ncolumns: 176
		bandtype: spatial
                repn: ubyte
                voxel: "1.000000 1.000000 1.500000"
                convention: natural
                orientation: axial
        }

The ASCII header contains the attributes of all images which are stored in the file. In our example 'structural.v', the file contains only 1 image. The image attributes shown in this example (data, length, nbands, nframes, nrows, ncolumns, bandtype, repn, voxel, convention, and orientation) are required for all images in Lipsia.

The attributes nbands, nrows, and ncolumns show the number of slices, rows, and columns of the image, respectively. The attribute bandtype shows if the bands contain slices (e.g. in structural images) or timesteps (e.g. in functional images). The attribute repn denotes the image data representation. Possible image representations are 'bit' (1-bit), 'ubyte' (8-bit integer), 'short' (16-bit integer), 'float' (32 bit floating point), and 'double' (64 bit floating point). In our example above, we have the representation 'ubyte', i.e., the image has integer values between 0 and 255. The attribute voxel denotes the voxel size in mm (row, column, slice). In our example, we have a voxel size of 1x1x1.5mm. The attribute convention denotes the image convention. Possible values are 'natural' (L=L and R=R) and 'radiological' (L=R and R=L). Note that for Lipsia processing, all data must be stored in natural convention. The last attribute is the slice orientation which can be 'axial', 'sagittal', or 'coronal'. In our example, we have a set of 170 axial slices.

Changing the ASCII header

The ASCII header can easily be changed using a text editor. One can add, edit, and delete optional attributes or comments annotating an image by simply editing this part of the file, e.g. using the editor 'joe'. However, a safer way of changing the image attributes is to use the Lipsia program 'vattredit'. In our example, we could do the following:

vattredit -in structural.v -out outfile.v -name "patient" -value "Paul Miller"

With this command we edit (or add) the attribute 'patient' and give it the value 'Paul Miller'. Note that this is usually done for all objects in the input file, unless an individual object is specified by the option '-obj' when calling 'vattredit'. However, in our example data the input file contains only 1 image. The resulting header of 'outfile.v' thus looks as follows:

V-data 2 {
        history: {
                vattredit: "1.3; -obj -1 -name patient -value Paul Miller"
        }
        image: image {
                data: 0
                length: 7180800
                nbands: 170
                nframes: 170
                nrows: 240
                ncolumns: 176
		bandtype: spatial
                repn: ubyte
                voxel: "1.000000 1.000000 1.500000"
                convention: natural
                orientation: axial
                patient: "Paul Miller"
        }

The changes in the header are marked in blue. After using Lipsia programs, the first part of the ASCII header shows the history of the processing steps. In our example, the file 'outfile.v' is obtained after using the program 'vattredit'. The header shows the program version and all command-line options.

Anatomical MRI data
The Lipsia data format is able to store different images in a single file. These images are 'objects' of the Lipsia data file. In our example data set, the anatomical data file 'structural.v' contains only one image, i.e., the file contains only one 'object'. This can be seen as follows:

vsview -in structural.v

In anatomical data sets, bands correspond to image slices, whereas rows and columns correspond to within-slice position. The anatomical data set can also be viewed with

vlv -in structural.v

Important: Structural data must have the orientation as shown in the figures above: Bands must be ordered from dorsal to ventral, rows must be ordered from anterior to posterior, and columns must be ordered from left to right. The latter corresponds to the natural convention (L=L and R=R).

Functional MRI data
In Lipsia, (4D-) functional MRI data are organized slightly different from structural data. This enables a particularly fast data processing.

Functional MRI data are stored as a set of several 'objects'. Each object represents an image slice, where bands correspond to time steps and rows and columns again correspond to within-slice position. Our example data contains six functional slices, i.e., the file 'data.v' contains six 'objects' called "Image". Calling 'vsview -in data.v', the six functional slices appear as images in the object list (see Figure below).

Individual time steps of a functional data set can also be viewed like this:

vtimestep -in data.v -out tmp.v -step 0

vlview -in tmp.v

Note that in the coronal and sagittal views only the six slices are seen.

Important: Before preprocessing, functional data must have the orientation as shown in the figures above: Objects must be ordered from ventral to dorsal (i.e. upside down). When importing (unpreprocessed) raw functional volumes using anatov or niftov, specify '-zflip true' in order to flip the slices.

In general, rows must be ordered from anterior to posterior, and columns must be ordered from left to right. The latter corresponds to the natural convention (L=L and R=R).

As described above, the header of the image file can be shown using the command 'more'. In our example, the ASCII header of 'data.v' contains information of all images, i.e., of all six axial slices.

V-data 2 {
        image: image {
                data: 0
                length: 983040
                nbands: 120
                nframes: 120
                nrows: 64
                ncolumns: 64
		bandtype: temporal
                repn: short
                voxel: "3.000000 3.000000 4.500000"
                convention: natural
                orientation: axial
                MPIL_vista_0: " repetition_time=2000 packed_data=1 120 "
                ntimesteps: 120
                repetition_time: 2000
                slice_time: 600
        }
        image: image {
                data: 983040
                length: 983040
                nbands: 120
                nframes: 120
                nrows: 64
                ncolumns: 64
		bandtype: temporal
                repn: short
                voxel: "3.000000 3.000000 4.500000"
                convention: natural
                orientation: axial
                MPIL_vista_0: " repetition_time=2000 packed_data=1 120 "
                ntimesteps: 120
                repetition_time: 2000
                slice_time: 800
        }
        image: image {
                data: 1966080
                length: 983040
...

Because this dataset containes functional images, the attribute 'bandtype' has the value 'temporal' in all images.In addition to the required attributes described above, functional images must also contain the attributes 'MPIL_vista_0', 'ntimesteps', 'repetition_time', and 'slice_time'. The attribute 'MPIL_vista_0' contains the repetition time (in our example 2000 ms) and the number of functional scans (i.e. timesteps). In our example, we have 120 timesteps. The image attributes 'repetition_time' and 'ntimesteps' show also those numbers, i.e. the repetition time of 2000 ms and the number of 120 timesteps. The attribute 'slice_time' shows the exact slice acquisition time after the trigger. In our example, the first (most ventral) slice was acquired 600 ms after the trigger. The second slice was acquired 800 ms after the trigger, and so on.

List of image attributes

The following table gives a set of image attributes which are used in the Lipsia data format.

datanumberrequiredposition of the image in the binary data
lengthnumberrequiredlength of the binary image data
nbandsnumberrequirednumber of bands (anatomical image: slices, functional image: scans)
nframesnumberrequirednumber of frames (anatomical image: slices, functional image: scans)
nrowsnumberrequirednumber of rows
ncolumnsnumberrequirednumber of columns
bandtypespatial, temporalrequiredtype of bands, e.g. 'spatial' in structural images, 'temporal' in functional images
repnbit, ubyte, short, long, float, doublerequiredimage representation, i.e. ubyte (8bit) has gray values between 0 and 255
voxel3 numbersrequiredimage voxel size (row, column, and slice thickness)
conventionnatural, radiologicalrequiredimage convention ('natural' convention is required by many Lipsia programs)
orientationaxial, sagittal, coronalrequiredslice orientation
MPIL_vista_0textrequired in functional datatext containing repetition time and the number of scans
ntimestepsnumberrequired in functional datanumber of functional scans (timesteps)
repetition_timenumberrequired in functional datarepetition time in ms
slice_timenumberrequired in functional dataslice acquisition time in ms (after trigger)
ca3 numbersrequired in Talairach spaceposition of commissura anterior in voxels
cp3 numbersrequired in Talairach spaceposition of commissura posterior in voxels
extent3 numbersrequired in Talairach spaceextent (size) of the brain in mm
fixpoint3 numbersrequired in Talairach spacefixpoint of the image in voxels
talairachatlas, neurologicalrequired in Talairach space type of ca/cp image orientation ('atlas' is required by many Lipsia programs)
nametextrequired by some programs name of the image
modalitytextrequired by some programs image modality, e.g. zmap
patienttextoptional name or description of the subject/patient
birthDD.MM.YYYYoptional birth date of the subject/patient
sexmale, femaleoptional gender of the subject/patient
devicetextoptional name of acquisition device, e.g. Siemens Trio
protocoltextoptional type of acquisition protocol, e.g. t1_mpr_axial_standard
sequencetextoptional type of acquisition sequence
CoilIDtextoptional name or id of coil
dateDD.MM.YYYYoptional date of image acquisition
timeHH:MM:SSoptional time of image acquisition
boundingBoxspecial formatoptional image bounding box
ori_nrowsnumberoptional number of rows in the original data set
ori_ncolumnsnumberoptional number of columns in the original data set
acquisitionOrientationaxial, sagittal, coronaloptional original orientation after image acquisition


Max Planck Institute for Human Cognitive and Brain Sciences. Further Information: lipsia@cbs.mpg.de
Copyright © 2007 Max Planck Institute for Human Cognitive and Brain Sciences. All rights reserved.