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

image

Returns the Image containing the voxelwise EV data.

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 the EV 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 the EV 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 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
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.