`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.
`StatisticAtlas`	A `StatisticAtlas` is a 4D image which contains one volume for each region in the atlas; each volume contains some statistic value for the corresponding region.
`ProbabilisticAtlas`	A 4D atlas which contains one volume for each region.

class fsl.data.atlases.AtlasRegistry(*args, **kwargs)[source]

Bases: 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.

__init__()[source]: Create an AtlasRegistry.

rescanAtlases()[source]: 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()[source]: 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)[source]: Returns True if this AtlasRegistry has an atlas with the specified atlasID.

getAtlasDescription(atlasID)[source]: Returns an AtlasDescription instance describing the atlas with the given atlasID.

loadAtlas(atlasID, loadSummary=False, resolution=None, **kwargs)[source]

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)[source]

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)[source]: Removes the atlas with the specified atlasID from this AtlasRegistry.

__getKnownAtlases()

Returns a list of tuples containing the IDs and paths of all known atlases .

The atlases are retrieved via the settings module - a setting with the name fsl.data.atlases is assumed to contain a string of atlasID=specPath pairs, separated with the operating system file path separator (: on Unix/Linux). See also __saveKnownAtlases().

__saveKnownAtlases(): Saves the IDs and paths of all atlases which are currently in the registry. The atlases are saved via the settings module.

__module__ = 'fsl.data.atlases'

class fsl.data.atlases.AtlasLabel(name, index, value, x, y, z)[source]

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 statistic/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).

__init__(name, index, value, x, y, z)[source]

__eq__(other)[source]: Compares the index of this AtlasLabel with another.

__neq__(other)[source]: Compares the index of this AtlasLabel with another.

__lt__(other)[source]: Compares this AtlasLabel with another by their index attribute.

__repr__()[source]: Represents AtlasLabel as string

__dict__ = mappingproxy({'__module__': 'fsl.data.atlases', '__doc__': 'The ``AtlasLabel`` class is used by the :class:`AtlasDescription` class\n as a container object used for storing atlas label information.\n\n An ``AtlasLabel`` instance contains the following attributes:\n\n ========= ================================================================\n ``name`` Region name\n ``index`` The index of this label into the list of all labels in the\n ``AtlasDescription`` that owns it. For statistic/probabilistic\n atlases, this is also the index into the 4D atlas image of the\n volume that corresponds to this region.\n ``value`` For label atlases and summary images, the value of voxels that\n are in this region.\n ``x`` X coordinate of the region in world space\n ``y`` Y coordinate of the region in world space\n ``z`` Z coordinate of the region in world space\n ========= ================================================================\n\n .. note:: The ``x``, ``y`` and ``z`` label coordinates are pre-calculated\n centre-of-gravity coordinates, as listed in the atlas xml file.\n They are in the coordinate system defined by the transformation\n matrix for the first image in the ``images`` list of the atlas\n XML file (typically MNI152 space).\n ', '__init__': <function AtlasLabel.__init__>, '__eq__': <function AtlasLabel.__eq__>, '__neq__': <function AtlasLabel.__neq__>, '__lt__': <function AtlasLabel.__lt__>, '__repr__': <function AtlasLabel.__repr__>, '__dict__': <attribute '__dict__' of 'AtlasLabel' objects>, '__weakref__': <attribute '__weakref__' of 'AtlasLabel' objects>, '__hash__': None, '__annotations__': {}})

__hash__ = None

__module__ = 'fsl.data.atlases'

__weakref__: list of weak references to the object (if defined)

class fsl.data.atlases.AtlasDescription(filename, atlasID=None)[source]

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>           # 'Statistic', 'Probabilistic' or 'Label'
    <statistic></statistic> # Optional. Type of statistic
    <units></units>         # Optional. Units of measurement
    <precision></precision> # Optional. Decimal precision to report
    <upper></upper>         # Optional. Upper threshold
    <lower></lower>         # Optional. Lower threshold
    <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 statistic/probabilistic atlases, index of corresponding
  #         volume in 4D image file. For label images, the value of
  #         voxels which are in the corresponding region. For
  #         statistic/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 statistic, probabilistic or label.
`statistic`	Type of statistic, for statistic atlases.
`units`	Unit of measurement, for statistic atlases.
`precision`	Reporting precision, for statistic atlases.
`upper`	Upper threshold, for statistic atlases.
`lower`	Lower threshold, for statistic atlases.
`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.

__init__(filename, atlasID=None)[source]

Create an AtlasDescription instance.

Parameters:

filename – Name of the XML file describing the atlas.
atlasID – ID to use for this atlas. If not provided, the file base name is used.

find(index=None, value=None, name=None)[source]

Find an AtlasLabel either by index, or by value.

Exactly one of index, value, or name may be specified - a ValueError is raised otherwise. If an invalid index, name, 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.

__eq__(other)[source]: Compares the atlasID of this AtlasDescription with another.

__neq__(other)[source]: Compares the atlasID of this AtlasDescription with another.

__lt__(other)[source]: Compares this AtlasDescription with another by their name attribute.

__repr__()[source]: String representation of AtlasDescription

__dict__ = mappingproxy({'__module__': 'fsl.data.atlases', '__doc__': 'An ``AtlasDescription`` instance parses and stores the information\n stored in the FSL XML file that describes a single FSL atlas. An XML\n atlas specification file is assumed to have a structure that looks like\n the following:\n\n .. code-block:: xml\n\n <atlas>\n <header>\n <name></name> # Atlas name\n <type></type> # \'Statistic\', \'Probabilistic\' or \'Label\'\n <statistic></statistic> # Optional. Type of statistic\n <units></units> # Optional. Units of measurement\n <precision></precision> # Optional. Decimal precision to report\n <upper></upper> # Optional. Upper threshold\n <lower></lower> # Optional. Lower threshold\n <images>\n <imagefile>\n </imagefile> # If type is Probabilistic, path\n # to 4D image file, one volume per\n # label, Otherwise, if type is\n # Label, path to 3D label file\n # (identical to the summaryimagefile\n # below). The path must be specified\n # as relative to the location of this\n # XML file.\n\n <summaryimagefile> # Path to 3D label summary file,\n </summaryimagefile> # Every <image> must be accompanied\n # by a <summaryimage> - for label\n # atlases, they will typically refer\n # to the same image file.\n\n </images>\n ... # More images - generally both\n # 1mm and 2mm versions (in\n # MNI152 space) are available\n </header>\n <data>\n\n # index - For statistic/probabilistic atlases, index of corresponding\n # volume in 4D image file. For label images, the value of\n # voxels which are in the corresponding region. For\n # statistic/probabilistic atlases, it is assumed that the\n # value for each region in the summary image(s) are equal to\n # ``index + 1``.\n #\n #\n # x |\n # y |- XYZ *voxel* coordinates into the first image of the <images>\n # | list\n # z |\n <label index="0" x="0" y="0" z="0">Name</label>\n ...\n </data>\n </atlas>\n\n\n Each ``AtlasDescription`` is assigned an identifier, which is simply the\n XML file name describing the atlas, sans-suffix, and converted to lower\n case. For exmaple, the atlas described by:\n\n ``$FSLDIR/data/atlases/HarvardOxford-Cortical.xml``\n\n is given the identifier\n\n ``harvardoxford-cortical``\n\n\n This identifier is intended to be unique.\n\n\n The following attributes are available on an ``AtlasDescription`` instance:\n\n ================= ======================================================\n ``atlasID`` The atlas ID, as described above.\n\n ``name`` Name of the atlas.\n\n ``specPath`` Path to the atlas XML specification file.\n\n ``atlasType`` Atlas type - either *statistic*, *probabilistic* or\n *label*.\n\n ``statistic`` Type of statistic, for statistic atlases.\n\n ``units`` Unit of measurement, for statistic atlases.\n\n ``precision`` Reporting precision, for statistic atlases.\n\n ``upper`` Upper threshold, for statistic atlases.\n\n ``lower`` Lower threshold, for statistic atlases.\n\n ``images`` A list of images available for this atlas - usually\n :math:`1mm^3` and :math:`2mm^3` images are present.\n\n ``summaryImages`` For probabilistic atlases, a list of *summary* images,\n which are just 3D labelled variants of the atlas.\n\n ``pixdims`` A list of ``(x, y, z)`` pixdim tuples in mm, one for\n each image in ``images``.\n\n ``xforms`` A list of affine transformation matrices (as ``4*4``\n ``numpy`` arrays), one for each image in ``images``,\n defining the voxel to world coordinate transformations.\n\n ``labels`` A list of :class`AtlasLabel` objects, describing each\n region / label in the atlas.\n ================= ======================================================\n ', '__init__': <function AtlasDescription.__init__>, 'find': <function AtlasDescription.find>, '__eq__': <function AtlasDescription.__eq__>, '__neq__': <function AtlasDescription.__neq__>, '__lt__': <function AtlasDescription.__lt__>, '__repr__': <function AtlasDescription.__repr__>, '__dict__': <attribute '__dict__' of 'AtlasDescription' objects>, '__weakref__': <attribute '__weakref__' of 'AtlasDescription' objects>, '__hash__': None, '__annotations__': {}})

__hash__ = None

__module__ = 'fsl.data.atlases'

__weakref__: list of weak references to the object (if defined)

class fsl.data.atlases.Atlas(*args, **kwargs)[source]

Bases: Image

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

__init__(atlasDesc, resolution=None, isLabel=False, **kwargs)[source]

Initialise an Atlas.

Parameters:

atlasDesc – The AtlasDescription instance which describes the atlas.
resolution – Desired isotropic resolution in millimetres.
isLabel – Pass in True for label atlases, False for statistic/probabilistic atlases.

All other arguments are passed to Image.__init__().

find(*args, **kwargs)[source]: Find an AtlasLabel - see the AtlasDescription.find() method.

prepareMask(mask)[source]

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 StatisticAtlas.maskValues() 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.

__annotations__ = {}

__module__ = 'fsl.data.atlases'

exception fsl.data.atlases.MaskError[source]

Bases: Exception

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

__module__ = 'fsl.data.atlases'

__weakref__: list of weak references to the object (if defined)

class fsl.data.atlases.LabelAtlas(*args, **kwargs)[source]

Bases: 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.

__init__(atlasDesc, resolution=None, **kwargs)[source]

Create a LabelAtlas instance.

Parameters:

atlasDesc – The AtlasDescription instance describing the atlas.
resolution – Desired isotropic resolution in millimetres.

label(location, *args, **kwargs)[source]

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)[source]

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)[source]

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

Calling this method will cause the atlas image data to be loaded into memory.

Note

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

get(label=None, index=None, value=None, name=None, binary=True)[source]

Returns the binary image for the given label.

Only one of the arguments should be used to define the label

Parameters:

label – AtlasLabel contained within this atlas
index – index of the label
value – value of the label
name – string of the label
binary – If True (the default), the image will contain 1s in the label region. Otherwise the image will contain the label value.

Returns:

Image with the mask

__annotations__ = {}

__module__ = 'fsl.data.atlases'

class fsl.data.atlases.StatisticAtlas(*args, **kwargs)[source]

Bases: Atlas

A StatisticAtlas is a 4D image which contains one volume for each region in the atlas; each volume contains some statistic value for the corresponding region.

The ProbabilisticAtlas is a specialisation of the StatisticAtlas

__init__(atlasDesc, resolution=None, **kwargs)[source]

Create a StatisticAtlas instance.

Parameters:

atlasDesc – The AtlasDescription instance describing the atlas.
resolution – Desired isotropic resolution in millimetres.

get(label=None, index=None, value=None, name=None)[source]

Returns the statistic image at the given label.

Only one of the arguments should be used to define the label

Parameters:

label – AtlasLabel contained within this atlas
index – index of the label
value – value of the label
name – string of the label

Returns:

Image with the statistic values for the specified label.

values(location, *args, **kwargs)[source]

Looks up and returns the values 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, coordValues() is called.
An Image which is interpreted as a weighted mask. In this case, maskValues() is called.

All other arguments are passed through to the coordValues() or maskValues() methods.

Returns:: The return value of either coordValues() or maskValues().

coordValues(loc, voxel=False)[source]

Looks up the region values 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. Returns an empty list if the given location is out of bounds.

maskValues(mask)[source]

Looks up the average values 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 StatisticAtlas, it is resampled using Atlas.prepareMask().
Returns:: A sequence containing the average value, within the mask, of all regions in the atlas.

__annotations__ = {}

__module__ = 'fsl.data.atlases'

class fsl.data.atlases.ProbabilisticAtlas(*args, **kwargs)[source]

Bases: StatisticAtlas

A 4D atlas which contains one volume for each region. Each volume contains probabiliy values for one region, between 0 and 100.

__annotations__ = {}

__module__ = 'fsl.data.atlases'

fsl.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).

fsl.data.atlases.hasAtlas(atlasID): Returns True if this AtlasRegistry has an atlas with the specified atlasID.

fsl.data.atlases.getAtlasDescription(atlasID): Returns an AtlasDescription instance describing the atlas with the given atlasID.

fsl.data.atlases.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.

fsl.data.atlases.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.

fsl.data.atlases.removeAtlas(atlasID): Removes the atlas with the specified atlasID from this AtlasRegistry.

fsl.data.atlases.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/.

fsl.data.atlases

`fsl.data.atlases`