Reading geometric data

In braviz scripts and applications should not have to deal with individual files or directory structures. All access to this data should be done through to the functions and classes in the braviz.readAndFilter module. The objective behind this is to isolate the applications code from the underlying file system. In this way it is easy to adapt to different projects with different data structures.

Project readers should be derived from BaseReader , which describes the behaviour that they should provide.

BaseReader

class BaseReader(max_cache=100, **kwargs)[source]

Provide access to projects’ non-tabular data

Project readers provide a common interface to each projects underlying data. All project readers should be inherited from this class. Most data access is carried out through the get() method. Underneath this method locates the appropriate data files and transformations, and returns the requested data in the requested coordinates system.

An instance of this class will always return empty lists when indexes are requested and raise exceptions when data is requested. To get a more useful class you should create your own subclass.

Constructors

BaseReader.__init__(self, max_cache=100, **kwargs)[source]

The base reader handles a memory cache for speeding repeated access for the same data.

Parameters:
  • max_cache (int) – The maximum amount of memory in MB that can be used for cache
  • **kwargs – Ignored, maybe used by derived classes

Note that subclasses may have more arguments in their constructors.

static BaseReader.get_auto_reader(**kw_args)[source]

Initialized a based on known nodes file

The get method

BaseReader.get(self, data, subj_id=None, *args, **kwargs)[source]

Provides access to geometric data in an specified coordinate system.

Parameters:
  • data (str) –

    Case insensitive, the type of data requested. Currently the possible values are

    Ids ids of all subjects in the study as a list

    Returns a list of ids
    IMAGE structural image of the given subject requires name=<modality>. The available modalities depend of the project, but some common values are MRI, FA, and MD.

    Use index=True to get a list of available modalities.

    All of these are single channel images. Other modalities may be available under DTI and Label.

    Returns a nibabel image object, use format="VTK" to receive a vtkImageData instead.
    DTI RGB DTI image

    returns a nibabel image object, use format="VTK" to receive a vtkImageData instead.
    Label Read Label Map images

    requires name=<map>. Some common maps are

    APARC: FreeSurfer Aparc (Auto Parcelation) image WMPARC: FreeSurfer WMParc (White Matter Parcelation) image

    use index=True to get a list of available maps

    returns a nibabel image object, use format="VTK" to receive a vtkImageData instead.

    use lut=True to get a vtkLookupTable
    fMRI SPM t-score map

    returns a nibabel image object, use format="VTK" to receive a vtkImageData instead.

    Requires name=<paradigm>

    Optionally you may specify contrast=<int>

    contrasts_dict = True will return a dictionary with the available for contrasts for the specified paradigm.

    SPM = True will return a SpmFileReader
    with the data contained in the spm.mat file.
    BOLD SPM, pre-processed bold series

    Only available as a 4d nibabel object
    Model Reconstruction of FreeSurfer segmented structure

    index=True returns a list of available models

    name=<model> returns a vtkPolyData, unless one of the following options is also specified

    color=True returns the standard FreeSurfer color associated with the given model

    volume=True returns the volume of the given structure read from the FreeSurfer stats files

    label=True returns the integer which identifies the structure in the Aparc or WMparc image
    Surf FreeSurfer brain cortex surface reconstruction

    Requires name=<surface> and hemi=<r|l> where surface is orig, pial, white, smoothwm, inflated or sphere

    normals=False returns a polydata without normals

    scalars=<name> add the given scalars to the polydata (look Surf_Scalar)
    Surf_Scalar Scalars for a FreeSurfer surfaces

    index = True returns a list of available scalars

    scalars=<name> and hemi=<'r'|'l'> will return a numpy array with the scalar data.

    lut=True will return a vtkLookupTable appropriate for the given scalars.
    Fibers Tractography

    Returns a polydata containing polylines. The following options are available

    color=<'orient'|'rand'|None> By default fibers are colored according to the direction. ‘rand’ will give a different color for each polyline so that they can be distinguished. Use None when you intend to display the fibers using scalar data and a lookup table

    scalars=<'fa_p','fa_l','md_p','md_l','length','aparc','wmparc'> will attach the given scalar data to the polydata. fa stands for Fractional Anisotropy and md for mean diffusivity. _p stands for a value for each point, while _l will create a value for each line equal to the mean across the line. aparc and wmpar will attach the integer label of the nearest voxel in the corresponding image.

    lut=True can be used together with scalars to get an appropriate lookup table

    waypoint = <model> will filter the tractography to the lines that pass through the given structure

    waypoint = <model-list> will filter the tractography to the lines that pass through all models in the list. If operation='or' is also specified the behaviour changes to the lines that pass through at least one of the models in the list.

    ids=True will return the ids of the polylines, based in the whole tractography, that cross the specified waypoints.

    name=<tract-name> can be used to access tracts defined through python functions. To get a list of such available tracts add index=True

    db-id=<id> returns a tract stored in the database with the given index
    Tracula Tracula probabilistic tractography

    index=True returns a list of available bundles

    name=<bundle> returns the isosurface at 0.20 of the maximum aposteriori probability for the given bundle. Use contour=<percentage> to change this value.

    map=True returns the probability map as an image

    color=True returns the standard FreeSurfer color associated with the bundle.
  • subj_id – The id of the subject whose data is requested. Use data=’ids’ to get a list of available subjects
  • space (str) –

    The coordinate systems in which the result is requested. Available spaces are

    subject Defined by the subject’s MRI image
    talairach MRI image after applying an affine transformation to the Talairach coordinates
    dartel Non-linear warp towards a template
    diff Defined by the diffusion images
    fmri-<pdgm> Defined by the SPM results
    native Ignores all transformations, raw voxels data

    Notice that some data types are not available in every space, in this case an exception will be risen.

  • **kwargs – Arguments specific to each data type

Coordinate systems

BaseReader.move_img_to_subject(self, img, source_space, subj, interpolate=False)[source]

Resamples an image into the subject coordinate system

Parameters:
  • img (vtkImageData) – source image
  • source_space (str) – source image coordinate system
  • subj – Subject to whom the image belongs
  • interpolate (bool) – If False nearest neighbours interpolation is applied, useful for label maps
Returns:

Resliced image in subject coordinate system
BaseReader.move_img_from_subject(self, img, target_space, subj, interpolate=False)[source]

Resamples an image from the subject coordinates into some other coordinate system

Parameters:
  • img (vtkImageData) – source image
  • target_space (str) – destination coordinate system
  • subj – Subject to whom the image belongs
  • interpolate (bool) – If False nearest neighbours interpolation is applied, useful for label maps
Returns:

Resliced image in target_space coordinates
BaseReader.transform_points_to_space(self, point_set, space, subj, inverse=False)[source]

Transforms a set of points into another coordinate system

By defaults moves from subject coordinates to another system, but these behaviour is reversed if the inverse parameter is True. At the moment, to move from an arbitrary coordinate system to another it is necessary to use the subject coordinates as stopover

Parameters:
  • point_set (vtkPolyData,vtkPoints,vtkDataSet) – source points
  • space (str) – origin or destination coordinate system, depending on inverse
  • subj – Subject to whom the points belong
  • inverse (bool) – If false points are moved from subject to space, else the points are moved from space to subject.
Returns:

Transformed points

Cache

BaseReader.clear_mem_cache(self)[source]

Clears the contents of the memory cache

BaseReader.save_into_cache(self, key, data)[source]

Saves some data into a cache, uses vtkDataWriter or cPickle for python objects.

Data is stored using a key. This value is required to retrieve the data or to overwrite it. To retrieve data use load_from_cache().

Parameters:
  • key (str) – Unique value used to reference the data into the cache, if data with the same key exists it will be overwritten
  • data – Data object to store
Returns:

True if the value was successfully saved, False if there was a problem
BaseReader.load_from_cache(self, key)[source]

Loads data stored into cache with save_into_cache()

Parameters:key (str) – Key used to store the object
Returns:If successful returns the object as it was previously stored.

In case of failure returns None
BaseReader.clear_cache_dir(self, last_word=False)[source]

Clears all the contents of the disk cache

Parameters:last_word (bool) – If True goes on to clear the cache, otherwise does nothing

File System

BaseReader.get_data_root(self)[source]

Returns the root directory from which this instance reads data

This directory should be readable by the current user

BaseReader.get_dyn_data_root(self)[source]

Returns the root directory into which this instance stores cache and data

This directory should be writable by the current user

static BaseReader.get_auto_data_root()[source]

Returns the root directory that would be used by an auto_reader to read data

static BaseReader.get_auto_dyn_data_root()[source]

Returns the root directory that would be used by an auto_reader to store data

static BaseReader.initialize_dynamic_data_dir(dir_name=None)[source]

Creates the basic directory structure used for braviz starting at the specified path.

Parameters:dir_name (str) – The path where the structure will be created. If None, the value returned by get_auto_dyn_data_root() will be used
static BaseReader.clear_dynamic_data_dir(dir_name)[source]

Clears data written by braviz from a directory

Parameters:dir_name (str) – Path to the root location where data was written, this is, the value returned by get_dyn_data_root() in the reader that stored the data.

Custom Readers

Custom readers should be subclasses of BaseReader. They should be included in a module with the same name as the project (in lowercase) and named after the project followed by "Reader". Look at the examples below

class Kmc40Reader(path, max_cache=2000)[source]

Braviz reader class designed to work with the file structure and data from the KMC pilot

This project contains 50 subjects (40 preterms). Data is organized into folders, and path and names for the different files can be derived from data type and id. The constructor requires the root to this structure

class Kmc400Reader(static_root, dynamic_route, max_cache=2000)[source]

A Braviz reader designed to work with the file structure and data from the KMC saving-brains project

This project contains data from around 450 subjects but only 250 of them have images. Data is organized into folders, and path and names for the different files can be derived from data type and id. This project reads data from a non-writable directory and writes braviz specific data to a different directory. This is done to protect raw data and to allow to share it between different users.