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 thedesign.fsf
file.- Basis function EV. One or more columns derived from a normal EV. A normal EV with the
convolve
value set to4
,5
, or6
will be followed by a set of basis function EVs (the number of additional EVs can be determined by thebasisfnum
flag).- Voxelwise EVs. An EV with different values for each voxel. An EV with the
shape
value set to9
is a voxelwise EV. The voxel data will be stored in a file in the FEAT directory calleddesignVoxelwiseEVN.nii.gz
(whereN
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
andven.dat
. Thevef.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 calledInputConfoundEVN.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 indesign.fsf
is set to1
, then 6 motion EVs are added; ifmotionevs
is2
, 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. |
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.
-
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.-
getEVs
()¶ Returns a list containing the
EV
instances that represent each column of thisFEATFSFDesign
.
-
getDesign
(voxel=None)¶ Returns the design matrix for the specified voxel.
Parameters: voxel – A tuple containing the (x, y, z)
voxel coordinates of interest. IfNone
(the default), or if thisFEATFSFDesign
was created withloadVoxelwiseEVs=False
, the design matrix is returned, with any voxelwise EV columns containing the mean voxelwise EV data.
-
-
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
.
-
class
fsl.data.featdesign.
NormalEV
(realIdx, origIdx, title)¶ Bases:
fsl.data.featdesign.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 theEV
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).
-
class
fsl.data.featdesign.
TemporalDerivativeEV
(realIdx, origIdx, title)¶ Bases:
fsl.data.featdesign.NormalEV
Class representing a temporal derivative EV, derived from a normal EV.
-
class
fsl.data.featdesign.
BasisFunctionEV
(realIdx, origIdx, title)¶ Bases:
fsl.data.featdesign.NormalEV
Class representing a basis function EV, derived from a normal EV.
-
class
fsl.data.featdesign.
VoxelwiseEV
(realIdx, origIdx, title, filename)¶ Bases:
fsl.data.featdesign.NormalEV
Class representing an EV with different values for each voxel in the analysis.
VoxelwiseEV
instances contain the following attributes (in addition to theNormalEV
attributes):filename
Path to the image file containing the data for this EV image
Reference to the Image
objectNote
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 thefilename
andimage
attributes toNone
it it does not exist.
-
class
fsl.data.featdesign.
ConfoundEV
(index, confIndex, title)¶ Bases:
fsl.data.featdesign.EV
Class representing a confound EV.
ConfoundEV
instances contain the following attributes (in addition to theEV
attributes):confIndex
Index of this ConfoundEV
(starting from 0) in relation to all other confound EVs.
-
class
fsl.data.featdesign.
MotionParameterEV
(index, motionIndex, title)¶ Bases:
fsl.data.featdesign.EV
Class representing a motion parameter EV.
MotionParameterEV
instances contain the following attributes (in addition to theEV
attributes):motionIndex
Index of this MotionParameterEV
(starting from 0) in relation to all other motion parameter EVs.
-
class
fsl.data.featdesign.
VoxelwiseConfoundEV
(index, voxIndex, title, filename)¶ Bases:
fsl.data.featdesign.EV
Class representing a voxelwise confound EV.
VoxelwiseConfoundEV
instances contain the following attributes (in addition to theEV
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
-
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 (seefeatanalysis.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 (seefeatanalysis.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.