`fsl.data.atlases`¶

This module provides access to FSL atlas images, typically contained in $FSLDIR/data/atlases/. The AtlasRegistry class provides access to these atlases, and allows the user to load atlases stored in other locations. A single AtlasRegistry instance is created when this module is first imported - it is available as a module level attribute called registry, and some of its methods are available as module-level functions:

`rescanAtlases`	Causes the `AtlasRegistry` to rescan available atlases from `$FSLDIR`.
`listAtlases`	Returns a list containing `AtlasDescription` objects for all available atlases.
`hasAtlas`	Returns `True` if this `AtlasRegistry` has an atlas with the specified `atlasID`.
`getAtlasDescription`	Returns an `AtlasDescription` instance describing the atlas with the given `atlasID`.
`loadAtlas`	Loads and returns an `Atlas` instance for the atlas with the given `atlasID`.
`addAtlas`	Add an atlas from the given XML specification file to the registry.
`removeAtlas`	Removes the atlas with the specified `atlasID` from this `AtlasRegistry`.
`rescanAtlases`	Causes the `AtlasRegistry` to rescan available atlases from `$FSLDIR`.

You must call the AtlasRegistry.rescanAtlases() function before any of the other functions will work. The loadAtlas() function allows you to load an atlas image, which will be one of the following atlas-specific Image sub-classes:

`LabelAtlas`	A 3D atlas which contains integer labels for each region.
`ProbabilisticAtlas`	A 4D atlas which contains one volume for each region.

class fsl.data.atlases.AtlasRegistry¶

Bases: fsl.utils.notifier.Notifier

The AtlasRegistry maintains a list of all known atlases.

When the rescanAtlases() method is called, the AtlasRegistry loads all of the FSL XML atlas specification files in $FSLDIR/data/atlases, and builds a list of AtlasDescription instances, each of which contains information about one atlas.

The addAtlas() method allows other atlases to be added to the registry. Whenever a new atlas is added, the AtlasRegistry notifies any registered listeners via the Notifier interface with the topic 'add', passing it the newly loaded class:AtlasDecsription. Similarly, the removeAtlas() method allows individual atlases to be removed. When this occurs, registered listeners on the 'remove' topic are notified, and passed the AtlasDescription instance of the removed atlas.

The AtlasRegistry stores a list of all known atlases via the settings module. When an AtlasRegistry is created, it loads in any previously known atlases. Whenever a new atlas is added, this list is updated. See the __getKnownAtlases() and _saveKnownAtlases() methods.

rescanAtlases()¶: Causes the AtlasRegistry to rescan available atlases from $FSLDIR. Atlases are loaded from the fsl.data.atlases setting (via the settings module), and from $FSLDIR/data/atlases/.

listAtlases()¶: Returns a list containing AtlasDescription objects for all available atlases. The atlases are ordered in terms of the AtlasDescription.name attribute (converted to lower case).

hasAtlas(atlasID)¶: Returns True if this AtlasRegistry has an atlas with the specified atlasID.

getAtlasDescription(atlasID)¶: Returns an AtlasDescription instance describing the atlas with the given atlasID.

loadAtlas(atlasID, loadSummary=False, resolution=None, **kwargs)¶

Loads and returns an Atlas instance for the atlas with the given atlasID.

Parameters:	loadSummary – If `True`, a 3D `LabelAtlas` image is loaded. Otherwise, if the atlas is probabilistic, a 4D `ProbabilisticAtlas` image is loaded. resolution – Optional. Desired isotropic atlas resolution in millimetres, e.g. `1.0` or `2.0`. The available atlas with the nearest resolution to this value will be returned. If not provided, the highest resolution atlas will be loaded.

addAtlas(filename, atlasID=None, save=True)¶

Add an atlas from the given XML specification file to the registry.

Parameters:	filename – Path to a FSL XML atlas specification file. atlasID – ID to give this atlas. If not provided, the file base name (converted to lower-case) is used. If an atlas with the given ID already exists, this new atlas is given a unique id. save – If `True` (the default), this atlas will be saved so that it will be available in future instantiations.

removeAtlas(atlasID)¶: Removes the atlas with the specified atlasID from this AtlasRegistry.

class fsl.data.atlases.AtlasLabel(name, index, value, x, y, z)¶

Bases: object

The AtlasLabel class is used by the AtlasDescription class as a container object used for storing atlas label information.

An AtlasLabel instance contains the following attributes:

`name`	Region name
`index`	The index of this label into the list of all labels in the `AtlasDescription` that owns it. For probabilistic atlases, this is also the index into the 4D atlas image of the volume that corresponds to this region.
`value`	For label atlases and summary images, the value of voxels that are in this region.
`x`	X coordinate of the region in world space
`y`	Y coordinate of the region in world space
`z`	Z coordinate of the region in world space

Note

The x, y and z label coordinates are pre-calculated centre-of-gravity coordinates, as listed in the atlas xml file. They are in the coordinate system defined by the transformation matrix for the first image in the images list of the atlas XML file (typically MNI152 space).

class fsl.data.atlases.AtlasDescription(filename, atlasID=None)¶

Bases: object

An AtlasDescription instance parses and stores the information stored in the FSL XML file that describes a single FSL atlas. An XML atlas specification file is assumed to have a structure that looks like the following:

<atlas>
  <header>
    <name></name>        # Atlas name
    <type></type>        # 'Probabilistic' or 'Label'
    <images>
     <imagefile>
     </imagefile>        # If type is Probabilistic, path
                         # to 4D image file, one volume per
                         # label, Otherwise, if type is
                         # Label, path to 3D label file
                         # (identical to the summaryimagefile
                         # below). The path must be specified
                         # as relative to the location of this
                         # XML file.

     <summaryimagefile>  # Path to 3D label summary file,
     </summaryimagefile> # Every <image> must be accompanied
                         # by a <summaryimage> - for label
                         # atlases, they will typically refer
                         # to the same image file.

    </images>
    ...                  # More images - generally both
                         # 1mm and 2mm  versions (in
                         # MNI152 space) are available
  </header>
 <data>

  # index - For probabilistic atlases, index of corresponding volume in
  #         4D image file. For label images, the value of voxels which
  #         are in the corresponding region. For probabilistic atlases,
  #         it is assumed that the value for each region in the  summary
  #         image(s) are equal to ``index + 1``.
  #
  #
  # x    |
  # y    |- XYZ *voxel* coordinates into the first image of the <images>
  #      |  list
  # z    |
  <label index="0" x="0" y="0" z="0">Name</label>
  ...
 </data>
</atlas>

Each AtlasDescription is assigned an identifier, which is simply the XML file name describing the atlas, sans-suffix, and converted to lower case. For exmaple, the atlas described by:

$FSLDIR/data/atlases/HarvardOxford-Cortical.xml

is given the identifier

harvardoxford-cortical

This identifier is intended to be unique.

The following attributes are available on an AtlasDescription instance:

`atlasID`	The atlas ID, as described above.
`name`	Name of the atlas.
`specPath`	Path to the atlas XML specification file.
`atlasType`	Atlas type - either probabilistic or label.
`images`	A list of images available for this atlas - usually $1mm^3$ and $2mm^3$ images are present.
`summaryImages`	For probabilistic atlases, a list of summary images, which are just 3D labelled variants of the atlas.
`pixdims`	A list of `(x, y, z)` pixdim tuples in mm, one for each image in `images`.
`xforms`	A list of affine transformation matrices (as `4*4` `numpy` arrays), one for each image in `images`, defining the voxel to world coordinate transformations.
`labels`	A list of :class`AtlasLabel` objects, describing each region / label in the atlas.

find(index=None, value=None)¶

Find an AtlasLabel either by index, or by value.

Exactly one of index or value may be specified - a ValueError is raised otherwise. If an invalid index or value is specified, an IndexError or KeyError will be raised.

Note

A 4D ProbabilisticAtlas may have more volumes than labels, and a 3D LabelAtlas may have more values than labels.

class fsl.data.atlases.Atlas(atlasDesc, resolution=None, isLabel=False, **kwargs)¶

Bases: fsl.data.image.Image

This is the base class for the LabelAtlas and ProbabilisticAtlas classes. It contains some initialisation logic common to both.

find(*args, **kwargs)¶: Find an AtlasLabel - see the AtlasDescription.find() method.

prepareMask(mask)¶

Makes sure that the given mask has the same resolution as this atlas, so it can be used for querying. Used by the LabelAtlas.maskLabels() and ProbabilisticAtlas.maskProportions() methods.

Parameters:	mask – A `Image`
Returns:	A `numpy` array containing the resampled mask data.
Raises:	A `MaskError` if the mask is not in the same space as this atlas, or does not have three dimensions.

exception fsl.data.atlases.MaskError¶

Bases: Exception

Exception raised by the LabelAtlas.maskLabel() and ProbabilisticAtlas.maskProportions() when a mask is provided which does not match the atlas space.

class fsl.data.atlases.LabelAtlas(atlasDesc, resolution=None, **kwargs)¶

Bases: fsl.data.atlases.Atlas

A 3D atlas which contains integer labels for each region.

The LabelAtlas class provides the label() method, which makes looking up the label at a location easy.

label(location, *args, **kwargs)¶

Looks up and returns the label of the region at the given location.

Parameters:

location –

Can be one of the following:

A sequence of three values, interpreted as atlas coordinates. In this case, coordLabel() is called.
An Image which is interpreted as a weighted mask. In this case, maskLabel() is called.

All other arguments are passed through to the coordLabel() or maskLabel() methods.

Returns:	The return value of either `coordLabel()` or `maskLabel()`.

coordLabel(loc, voxel=False)¶

Looks up and returns the label at the given location.

Parameters:	loc – A sequence of three values, interpreted as atlas coordinates. In this case, `coordLabel()` is called. voxel – Defaults to `False`. If `True`, the `location` is interpreted as voxel coordinates.
Returns:	The label at the given coordinates, or `None` if the coordinates are out of bounds.

Note

Use the find() method to retrieve the AtlasLabel associated with each returned value.

maskLabel(mask)¶

Looks up and returns the proportions of all regions that are present in the given mask.

Parameters:	mask – A 3D Image` which is interpreted as a weighted mask. If the `mask` shape does not match that of this `LabelAtlas`, it is resampled using `Image.resample()`, with nearest-neighbour interpolation.
Returns:	A tuple containing: A sequence of all values which are present in the mask A sequence containing the proportion, within the mask, of each present value. The proportions are returned as values between 0 and 100.

Note

Use the find() method to retrieve the AtlasLabel associated with each returned value.

class fsl.data.atlases.ProbabilisticAtlas(atlasDesc, resolution=None, **kwargs)¶

Bases: fsl.data.atlases.Atlas

A 4D atlas which contains one volume for each region.

The ProbabilisticAtlas provides the :meth`proportions` method, which makes looking up region probabilities easy.

proportions(location, *args, **kwargs)¶

Looks up and returns the proportions of of all regions at the given location.

Parameters:

location –

Can be one of the following:

A sequence of three values, interpreted as atlas coordinates. In this case, coordProportions() is called.
An Image which is interpreted as a weighted mask. In this case, maskProportions() is called.

All other arguments are passed through to the coordProportions() or maskProportions() methods.

Returns:	The return value of either `coordProportions()` or `maskProportions()`.

coordProportions(loc, voxel=False)¶

Looks up the region probabilities for the given location.

Parameters:	loc – A sequence of three values, interpreted as atlas world or voxel coordinates. voxel – Defaults to `False`. If `True`, the `loc` argument is interpreted as voxel coordinates.
Returns:	a list of values, one per region, which represent the probability of each region for the specified location. Returns an empty list if the given location is out of bounds.

maskProportions(mask)¶

Looks up the probabilities of all regions in the given mask.

Parameters:	mask – A 3D Image` which is interpreted as a weighted mask. If the `mask` shape does not match that of this `ProbabilisticAtlas`, it is resampled using `Image.resample()`, with nearest-neighbour interpolation.
Returns:	A sequence containing the proportion, within the mask, of all regions in the atlas. The proportions are returned as values between 0 and 100.

fsl.data.atlases¶

`fsl.data.atlases`¶