Basic Objects in BrainSTAT

There is one principal class called VImage (Volumetric Image) that handles much of the generic work in BrainSTAT which is essentially an array with one added feature: a voxel-to-physical coordinate system. The two most important attributes of VImage are image and warp.

* image: this is the "pipeline" through which data is read in and out of the VImage instance. It must have the following two methods: read, write to read/write hyperslabs of data. See the code for ArrayPipe here. If you want to extend the VImage class using another pipe, this can be done in by passing an argument pipe=mypipe to the instantiation of VImage. The function mypipe should return a pipe with the methods read, write.

* Currently, the existing pipes are ArrayPipe? which returns a VImage instance from a numarray, and URLPipe which returns a VImage instance from a URL, downloading to a local repository if necessary.

* warp: this is a map from voxel to physical coordinates (referred to as a "referential" in AIMS, for instance). The map need not be linear (though not much testing has been done on this front). The voxel coordinates are python voxel coordinates and not matlab/SPM coordinates. The code for the Warp class is fairly simple and can be here. Essentially, a Warp instance has attributes input_coords, output_coords and a method map (as well as a possibly non-functional method inverse).

* The coordinate systems input_coords, output_coords are of class Coordinates and consist of a list of Dimensions, and an identifier name, though it really need not be a string. The code for the Dimension and Coordinate class can be found here. The step, start attributes of the Dimension class are largely ignored if a 4x4 transformation matrix is provided.

* The pipe returned from mypipe should have an attribute warp, which is used by the VImage class to extract the "spatial" coordinates of the warp, i.e. the ['zspace', 'yspace', 'xspace'] components of the warp.

Examples

Dimension

from BrainSTAT.Base.Dimension import Dimension
xspace = Dimension(name='xspace', length=40, step=3.0, start=-15.0)
print xspace

Coordinates

from BrainSTAT.Base.Dimension import Dimension, Coordinates
xspace = Dimension(name='xspace', length=40, step=3.0, start=-15.0)
yspace = Dimension(name='yspace', length=20, step=13.0, start=-15.0)
zspace = Dimension(name='zspace', length=60, step=43.0, start=-15.0)
coords = Coordinates('world_reversed', [xspace, yspace, zspace])
print coords

Warp

from BrainSTAT.Base.Dimension import Dimension, Coordinates
from BrainSTAT.Base.Warp import Affine
from numarray.mlab import diag

xspace_w = Dimension(name='xspace', length=40, step=3.0, start=-15.0)
yspace_w = Dimension(name='yspace', length=20, step=13.0, start=-15.0)
zspace_w = Dimension(name='zspace', length=60, step=43.0, start=-15.0)
coords_w = Coordinates('world_reversed', [xspace_w, yspace_w, zspace_w])

xspace_v = Dimension(name='xspace', length=40, step=1.0, start=0.0)
yspace_v = Dimension(name='yspace', length=20, step=1.0, start=0.0)
zspace_v = Dimension(name='zspace', length=60, step=1.0, start=0.0)
coords_v = Coordinates('voxel', [zspace_v, yspace_v, xspace_v])

trans = diag([3.0, 13.0, 43.0, 1.0])
trans[0:3,3] = -15.

warp = Affine(coords_v, coords_w, trans)
print warp.transform

VImage

import BrainSTAT, os, pylab

url = 'http://www.fil.ion.ucl.ac.uk/~john/misc/images/avg152T1.mnc'
test = BrainSTAT.VImage(url, urlstrip='/~john/misc/images/')
test.view(cmap=pylab.cm.gray)

print BrainSTAT.Options.repository, os.listdir(BrainSTAT.Options.repository)

fMRIImage (subclass of VImage)

import BrainSTAT

test = BrainSTAT.fMRIImage(BrainSTAT.testfile('test_fmri.img'))
print test.shape

frame = test.frame(0)
frame.view()
print frame.shape

for slice in iter(test):
    print slice.shape

ConstantPipe class

A somewhat silly example of how one would provide a useless pipe for data that returns simply a constant. To add a pipe for AIMS, the methods read, write obviously need to be rewritten.

from BrainSTAT.Base.Dimension import Dimension, Coordinates
from BrainSTAT.Base.Warp import Affine
import BrainSTAT
from numarray import *

class ConstantPipe:
    def __init__(self, shape, constant=0.0):
        self.shape = shape
        self.constant = constant
        self.ndim = len(self.shape)
        self.outdim = []
        self.indim = []

        for i in range(self.ndim):
            self.outdim.append(Dimension(name=Dimension.valid[i], length=shape[i], 
                                         step=1.0, start=0.0))
            self.indim.append(Dimension(name=Dimension.valid[i], length=shape[i], 
                                        step=1.0, start=0.0))
        self.outcoords = Coordinates('output', self.outdim)
        self.incoords = Coordinates('input', self.indim)
        self.warp = Affine(self.incoords, self.outcoords, identity(self.ndim+1))

    def read(self, start, count, **keywords):
        return ones(count) * self.constant

    def write(self, start, data, **keywords):
        return

cpipe = ConstantPipe((10, 20, 20), constant=2.)

x = cpipe.read((0,)*3, (1,20,20))
print x.shape, x[0,0,0]

y = BrainSTAT.VImage((10, 20, 20), pipe=ConstantPipe)
print y.readall().shape