fsl.data.featdesign

This module provides the FEATFSFDesign class, which encapsulates a FEAT design matrix.

The FEATFSFDesign class is intended to be used to access the design matrix for a FEAT analysis. The main reason for using the FEATFSFDesign class, instead of just using the design matrix loaded directly from the [analysis].feat/design.mat file, is because FEAT supports voxelwise EVs, where the contents of the design matrix will differ for each voxel in the analysis. For all voxelwise EVs (confound or otherwise), the design matrix (in design.mat) contains a dummy column which contains the mean across all voxels. The FEATFSFDesign.getDesign() method will return an appropriate design matrix for a specific voxel.

Note

Interaction EVs are not currently supported.

Explanatory variables in a FEAT design

A FEAT design matrix may contain the following types of explanatory variables:

• Normal EVs. This is simply a column in the design matrix, defined by the user.

• Temporal derivative of normal EVs. A column in the design matrix containing the derivative of a normal EV. The presence of a temporal derivative EV for a given normal EV can be determined by the deriv_yn flag in the design.fsf file.

• Basis function EV. One or more columns derived from a normal EV. A normal EV with the convolve value set to 4, 5, or 6 will be followed by a set of basis function EVs (the number of additional EVs can be determined by the basisfnum flag).

• Voxelwise EVs. An EV with different values for each voxel. An EV with the shape value set to 9 is a voxelwise EV. The voxel data will be stored in a file in the FEAT directory called designVoxelwiseEVN.nii.gz (where N is the EV number, relative to the order in which the EVs were set up by the user).

A FEAT design matrix will contain EVs of the above types, followed by the following types of confound EVs:

• Voxelwise confound EVs. These are confound EVs with different values for each voxel. If the design matrix contains confound EVs, two additional files will be present in the FEAT directory, vef.dat and ven.dat. The vef.dat file contains a list of comma separated file names, which are paths to the confound images (these should be in the FEAT directory, and called InputConfoundEVN.nii.gz). ven.dat is a list of comma separated integers, specifying the column number (starting from 1) of each voxelwise confound EV in the final design matrix.

• Motion parameter EVs. The user can choose to add 6 or 24 motion parameters as regressors to the design matrix. If the motionevs value in design.fsf is set to 1, then 6 motion EVs are added; if motionevs is 2, then 24 motion EVs are added.

• Confound EVs. These are any other EVs added by the user.

Module contents

In addition to the FEATFSFDesign class, this module contains a few other functions and classes that may be useful to advanced users.

The loadDesignMat() function loads the design.mat file from a FEAT directory, and returns it as a numpy array.

The following functions, defined in this module, will analyse a FEAT analysis to determine the contents of its design matrix (these functions are called by the FEATFSFDesign.__init__() method, but may be called directly):

getFirstLevelEVs	Derives the EVs for the given first level FEAT analysis.
getHigherLevelEVs	Derives the EVs for the given higher level FEAT analysis.

These functions return a list containing one instance of the following classes for each column in the design matrix:

NormalEV	Class representing a normal EV in a FEAT design matrix, i.e. one which has been explicitly provided by the user.
TemporalDerivativeEV	Class representing a temporal derivative EV, derived from a normal EV.
BasisFunctionEV	Class representing a basis function EV, derived from a normal EV.
VoxelwiseEV	Class representing an EV with different values for each voxel in the analysis.
ConfoundEV	Class representing a confound EV.
MotionParameterEV	Class representing a motion parameter EV.
VoxelwiseConfoundEV	Class representing a voxelwise confound EV.

exception fsl.data.featdesign.FSFError

Bases: Exception

Exception raised by various things in this module, primarily when the contents of the FEAT directory are not valid.

__module__ = 'fsl.data.featdesign'

__weakref__

list of weak references to the object (if defined)

class fsl.data.featdesign.FEATFSFDesign(featDir, settings=None, loadVoxelwiseEVs=True)

Bases: object

The FEATFSFDesign class encapsulates the design matrix from a FEAT analysis. This class is intended to be used for FEAT analyses generated with FSL 5.0.9 and newer.

__init__(featDir, settings=None, loadVoxelwiseEVs=True)

Create a FEATFSFDesign.

Parameters:

• featDir – Path to the FEAT directory.

• settings – A dictionary containing the FEAT analysis settings from its design.fsf. If not provided, is loaded via featanalysis.loadSettings().

• loadVoxelwiseEVs – If True (the default), image files for all voxelwise EVs are loaded. Otherwise they are not loaded, and all calls to meth:getDesign will contain the mean data for any voxelwise EV columns.

getEVs()

Returns a list containing the EV instances that represent each column of this FEATFSFDesign.

getDesign(voxel=None)

Returns the design matrix for the specified voxel.

Parameters:

voxel – A tuple containing the (x, y, z) voxel coordinates of interest. If None (the default), or if this FEATFSFDesign was created with loadVoxelwiseEVs=False, the design matrix is returned, with any voxelwise EV columns containing the mean voxelwise EV data.

__dict__ = mappingproxy({'__module__': 'fsl.data.featdesign', '__doc__': 'The ``FEATFSFDesign`` class encapsulates the design matrix from a FEAT\n    analysis. This class is intended to be used for FEAT analyses generated\n    with FSL 5.0.9 and newer.\n    ', '__init__': <function FEATFSFDesign.__init__>, 'getEVs': <function FEATFSFDesign.getEVs>, 'getDesign': <function FEATFSFDesign.getDesign>, '__dict__': <attribute '__dict__' of 'FEATFSFDesign' objects>, '__weakref__': <attribute '__weakref__' of 'FEATFSFDesign' objects>, '__annotations__': {}})

__module__ = 'fsl.data.featdesign'

__weakref__

list of weak references to the object (if defined)

class fsl.data.featdesign.VoxelwiseEVMixin(filename)

Bases: object

Mixin class for voxelwise EVs.

VoxelwiseEVMixin instances contain the following attributes:

filename	Path to the image file containing the data for this EV
image	Reference to the Image object

Some FSL tools (e.g. PNM) generate compressed voxelwise EVs, where there is only one voxel per slice. For example, if the input data has shape (x, y, z, t), and slices are acquired along the Z plane, voxelwise EV files generated by PNM will have shape (1, 1, z, t).

Therefore, using the getData() method is preferable to accessing the image() directly, as getData will check for compressed images, and adjust the voxel coordinates accordingly.

__init__(filename)

Create a VoxelwiseEVMixin.

Parameters:

filename – Path to the file containing the data for this VoxelwiseEV.

__del__()

Clears any reference to the voxelwise EV image.

property filename

Returns the path to the image file containing the data for this EV.

property image

Returns the Image containing the voxelwise EV data.

getData(x, y, z)

Returns the data at the specified voxel, taking into account compressed voxelwise EVs.

__dict__ = mappingproxy({'__module__': 'fsl.data.featdesign', '__doc__': 'Mixin class for voxelwise EVs.\n\n    ``VoxelwiseEVMixin`` instances contain the following attributes:\n\n    ============ ======================================================\n    ``filename`` Path to the image file containing the data for this EV\n    ``image``    Reference to the :class:`.Image` object\n    ============ ======================================================\n\n    Some FSL tools (e.g. `PNM\n    <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/PNM>`_) generate *compressed*\n    voxelwise EVs, where there is only one voxel per slice. For example,\n    if the input data has shape ``(x, y, z, t)``, and slices are acquired\n    along the Z plane, voxelwise EV files generated by PNM will have shape\n    ``(1, 1, z, t)``.\n\n    Therefore, using the :meth:`getData` method is preferable to accessing\n    the :meth:`image` directly, as ``getData`` will check for compressed\n    images, and adjust the voxel coordinates accordingly.\n    ', '__init__': <function VoxelwiseEVMixin.__init__>, '__del__': <function VoxelwiseEVMixin.__del__>, 'filename': <property object>, 'image': <property object>, 'getData': <function VoxelwiseEVMixin.getData>, '__dict__': <attribute '__dict__' of 'VoxelwiseEVMixin' objects>, '__weakref__': <attribute '__weakref__' of 'VoxelwiseEVMixin' objects>, '__annotations__': {}})

__module__ = 'fsl.data.featdesign'

__weakref__

list of weak references to the object (if defined)

class fsl.data.featdesign.EV(index, title)

Bases: object

Class representing an explanatory variable in a FEAT design matrix.

EV instances contain the following attributes:

index	Index of this EV (starting from 0) in the design matrix.
title	Name of this EV.

__init__(index, title)

Create an EV.

Parameters:

• index – Index (starting from 0) of this EV in the design matrix.

• title – Name of this EV.

__dict__ = mappingproxy({'__module__': 'fsl.data.featdesign', '__doc__': 'Class representing an explanatory variable in a FEAT design matrix.\n\n    ``EV`` instances contain the following attributes:\n\n    ========= ============================================================\n    ``index`` Index of this ``EV`` (starting from 0) in the design matrix.\n    ``title`` Name of this ``EV``.\n    ========= ============================================================\n    ', '__init__': <function EV.__init__>, '__dict__': <attribute '__dict__' of 'EV' objects>, '__weakref__': <attribute '__weakref__' of 'EV' objects>, '__annotations__': {}})

__module__ = 'fsl.data.featdesign'

__weakref__

list of weak references to the object (if defined)

class fsl.data.featdesign.NormalEV(realIdx, origIdx, title)

Bases: EV

Class representing a normal EV in a FEAT design matrix, i.e. one which has been explicitly provided by the user.

NormalEV instances contain the following attributes (in addition to the EV attributes):

origIndex

Index (starting from 0) of this NormalEV, as it was when the user set up the design matrix (i.e. not taking into account temporal derivative or basis function EVs).

__init__(realIdx, origIdx, title)

Create a NormalEV.

Parameters:

• realIdx – Index (starting from 0) of this NormalEV in the design matrix.

• origIdx – Original index (starting from 0) of this NormalEV.

• title – Name of this NormalEV.

__annotations__ = {}

__module__ = 'fsl.data.featdesign'

class fsl.data.featdesign.TemporalDerivativeEV(realIdx, origIdx, title)

Bases: NormalEV

Class representing a temporal derivative EV, derived from a normal EV.

__annotations__ = {}

__module__ = 'fsl.data.featdesign'

class fsl.data.featdesign.BasisFunctionEV(realIdx, origIdx, title)

Bases: NormalEV

Class representing a basis function EV, derived from a normal EV.

__annotations__ = {}

__module__ = 'fsl.data.featdesign'

class fsl.data.featdesign.VoxelwiseEV(realIdx, origIdx, title, filename)

Bases: NormalEV, VoxelwiseEVMixin

Class representing an EV with different values for each voxel in the analysis.

VoxelwiseEV instances contain the following attributes (in addition to the NormalEV attributes):

filename	Path to the image file containing the data for this EV
image	Reference to the Image object

Note

The file for voxelwise EVs in a higher level analysis are not copied into the FEAT directory, so if the user has removed them, or moved the .gfeat directory, the file path here will not be valid. Therefore, a VoxelwiseEV will test to see if the file exists, and will set the filename and image attributes to None it it does not exist.

__init__(realIdx, origIdx, title, filename)

Create a VoxelwiseEV.

Parameters:

• realIdx – Index (starting from 0) of this VoxelwiseEV in the design matrix.

• origIdx – Original index (starting from 0) of this VoxelwiseEV.

• title – Name of this VoxelwiseEV.

• filename – Path to the file containing the data for this VoxelwiseEV.

__annotations__ = {}

__module__ = 'fsl.data.featdesign'

class fsl.data.featdesign.ConfoundEV(index, confIndex, title)

Bases: EV

Class representing a confound EV.

ConfoundEV instances contain the following attributes (in addition to the EV attributes):

confIndex

Index of this ConfoundEV (starting from 0) in relation to all other confound EVs.

__init__(index, confIndex, title)

Create a ConfoundEV.

Parameters:

• index – Index (starting from 0) of this ConfoundEV in the design matrix.

• confIndex – Index (starting from 0) of this ConfoundEV in relation to all other confound EVs.

• title – Name of this ConfoundEV.

__annotations__ = {}

__module__ = 'fsl.data.featdesign'

class fsl.data.featdesign.MotionParameterEV(index, motionIndex, title)

Bases: EV

Class representing a motion parameter EV.

MotionParameterEV instances contain the following attributes (in addition to the EV attributes):

motionIndex

Index of this MotionParameterEV (starting from 0) in relation to all other motion parameter EVs.

__init__(index, motionIndex, title)

Create a MotionParameterEV.

Parameters:

• index – Index (starting from 0) of this MotionParameterEV in the design matrix.

• confIndex – Index (starting from 0) of this MotionParameterEV in relation to all other motion parameter EVs.

• title – Name of this MotionParameterEV.

__annotations__ = {}

__module__ = 'fsl.data.featdesign'

class fsl.data.featdesign.VoxelwiseConfoundEV(index, voxIndex, title, filename)

Bases: EV, VoxelwiseEVMixin

Class representing a voxelwise confound EV.

VoxelwiseConfoundEV instances contain the following attributes (in addition to the EV attributes):

voxIndex	Index of this VoxelwiseConfoundEV (starting from 0) in relation to all other voxelwise confound EVs.
filename	Path to the image file containing the data for this EV
image	Reference to the Image object

__init__(index, voxIndex, title, filename)

Create a Voxelwise ConfoundEV.

Parameters:

• index – Index (starting from 0) of this VoxelwiseConfoundEV in the design matrix.

• confIndex – Index (starting from 0) of this VoxelwiseConfoundEV in relation to all other voxelwise confound EVs.

• title – Name of this VoxelwiseConfoundEV.

• filename – Path to the file containing the data for this VoxelwiseConfoundEV.

__annotations__ = {}

__module__ = 'fsl.data.featdesign'

fsl.data.featdesign.getFirstLevelEVs(featDir, settings, designMat)

Derives the EVs for the given first level FEAT analysis.

Parameters:

• featDir – Path to the FEAT analysis.

• settings – A dictionary containing the FEAT analysis settings from its design.fsf file (see featanalysis.loadSettings()).

• designMat – The FEAT design matrix (a numpy array - see loadDesignMat()).

Returns:

A list of EV instances, one for each column in the design matrix.

fsl.data.featdesign.getHigherLevelEVs(featDir, settings, designMat)

Derives the EVs for the given higher level FEAT analysis.

Parameters:

• featDir – Path to the FEAT analysis.

• settings – A dictionary containing the FEAT analysis settings from its design.fsf file (see featanalysis.loadSettings()).

• designMat – The FEAT design matrix (a numpy array - see loadDesignMat()).

Returns:

A list of EV instances, one for each column in the design matrix.

fsl.data.featdesign.loadDesignMat(designmat)

Loads the specified design matrix.

Returns a numpy array containing the design matrix data, where the first dimension corresponds to the data points, and the second to the EVs.

Parameters:

designmat – Path to the design.mat file.