fsl.data.featanalysis
¶
This module provides a few utility functions for loading/querying the
contents of a FEAT analysis directory. They are primarily for use by the
FEATImage
class, but are available for other uses if needed. The
following functions are provided:
Returns |
|
Returns |
|
Returns |
|
Returns |
|
If the given path is contained within a FEAT directory, the path to that FEAT directory is returned. |
|
If the given path is contained within a hierarchy of FEAT or MELODIC directories, the path to the highest-level (i.e. |
|
Returns |
|
Loads the design matrix from a FEAT directory. |
|
Loads the contrasts from a FEAT directory. |
|
Loads the analysis settings from a FEAT directory. |
|
Given a FEAT settings dictionary, returns a dictionary of |
|
If cluster thresholding was used in the FEAT analysis, this function will load and return the cluster results for the specified (0-indexed) contrast number. |
The following functions return the names of various files of interest:
Returns the name of the file in the FEAT directory which contains the model input data (typically called |
|
Returns the name of the file in the FEAT results which contains the model fit residuals (typically called |
|
Returns the name of the file in the FEAT results which contains the melodic components (if melodic ICA was performed as part of the FEAT analysis). |
|
Returns the path of the PE file for the specified EV. |
|
Returns the path of the COPE file for the specified contrast. |
|
Returns the path of the Z-statistic file for the specified contrast. |
|
Returns the path of the cluster mask file for the specified contrast. |
-
fsl.data.featanalysis.
isFEATImage
(path)¶ Returns
True
if the given path looks like it is the input data to a FEAT analysis,False
otherwise.
-
fsl.data.featanalysis.
isFEATDir
(path)¶ Returns
True
if the given path looks like a FEAT directory, or looks like the input data for a FEAT analysis,False
otherwise. A FEAT directory:Must be named
*.feat
.Must contain a file called
filtered_func_data.nii.gz
.Must contain a file called
design.fsf
.Must contain a file called
design.mat
.Must contain a file called
design.con
.
- Parameters
path – A file / directory path.
-
fsl.data.featanalysis.
hasStats
(featdir)¶ Returns
True
if it looks like statistics have been calculated for the given FEAT analysis,False
otherwise.
-
fsl.data.featanalysis.
hasMelodicDir
(featdir)¶ Returns
True
if the data for the given FEAT directory has had MELODIC run on it,False
otherwise.
-
fsl.data.featanalysis.
getAnalysisDir
(path)¶ If the given path is contained within a FEAT directory, the path to that FEAT directory is returned. Otherwise,
None
is returned.
-
fsl.data.featanalysis.
getTopLevelAnalysisDir
(path)¶ If the given path is contained within a hierarchy of FEAT or MELODIC directories, the path to the highest-level (i.e. the shallowest in the file system) directory is returned. Otherwise,
None
is returned.
-
fsl.data.featanalysis.
getReportFile
(featdir)¶ Returns the path to the FEAT report index file, or
None
if there is no report.
-
fsl.data.featanalysis.
loadContrasts
(featdir)¶ Loads the contrasts from a FEAT directory. Returns a tuple containing:
A list of names, one for each contrast.
A list of contrast vectors (each of which is a list itself).
- Parameters
featdir – A FEAT directory.
-
fsl.data.featanalysis.
loadSettings
(featdir)¶ Loads the analysis settings from a FEAT directory.
Returns a dict containing the settings specified in the
design.fsf
file within the directory- Parameters
featdir – A FEAT directory.
-
fsl.data.featanalysis.
loadDesign
(featdir, settings)¶ Loads the design matrix from a FEAT directory.
- Parameters
featdir – A FEAT directory.
settings – Dictionary containing FEAT settings (see
loadSettings()
).
- Returns
a
FEATFSFDesign
instance which represents the design matrix.
-
fsl.data.featanalysis.
getThresholds
(settings)¶ Given a FEAT settings dictionary, returns a dictionary of
{stat : threshold}
mappings, containing the thresholds used in the FEAT statistical analysis.The following keys will be present. Threshold values will be
None
if the respective statistical thresholding was not carried out:p
: P-value thresholdingz
: Z-statistic thresholding
- Parameters
settings – A FEAT settings dictionary (see
loadSettings()
).
-
fsl.data.featanalysis.
isFirstLevelAnalysis
(settings)¶ Returns
True
if the FEAT analysis described bysettings
is a first level analysis,False
otherwise.- Parameters
settings – A FEAT settings dictionary (see
loadSettings()
).
-
fsl.data.featanalysis.
loadClusterResults
(featdir, settings, contrast)¶ If cluster thresholding was used in the FEAT analysis, this function will load and return the cluster results for the specified (0-indexed) contrast number.
If there are no cluster results for the given contrast,
None
is returned.An error will be raised if the cluster file cannot be parsed.
- Parameters
featdir – A FEAT directory.
settings – A FEAT settings dictionary.
contrast – 0-indexed contrast number.
- Returns
A list of
Cluster
instances, each of which contains information about one cluster. ACluster
object has the following attributes:index
Cluster index.
nvoxels
Number of voxels in cluster.
p
Cluster p value.
logp
\(-log_{10}\) of the cluster P value.
zmax
Maximum Z value in cluster.
zmaxx
X voxel coordinate of maximum Z value.
zmaxy
Y voxel coordinate of maximum Z value.
zmaxz
Z voxel coordinate of maximum Z value.
zcogx
X voxel coordinate of cluster centre of gravity.
zcogy
Y voxel coordinate of cluster centre of gravity.
zcogz
Z voxel coordinate of cluster centre of gravity.
copemax
Maximum COPE value in cluster.
copemaxx
X voxel coordinate of maximum COPE value.
copemaxy
Y voxel coordinate of maximum COPE value.
copemaxz
Z voxel coordinate of maximum COPE value.
copemean
Mean COPE of all voxels in the cluster.
-
fsl.data.featanalysis.
getDataFile
(featdir)¶ Returns the name of the file in the FEAT directory which contains the model input data (typically called
filtered_func_data.nii.gz
).Raises a
PathError
if the file does not exist.- Parameters
featdir – A FEAT directory.
-
fsl.data.featanalysis.
getMelodicFile
(featdir)¶ Returns the name of the file in the FEAT results which contains the melodic components (if melodic ICA was performed as part of the FEAT analysis). This file can be loaded as a
MelodicImage
.Raises a
PathError
if the file does not exist.
-
fsl.data.featanalysis.
getResidualFile
(featdir)¶ Returns the name of the file in the FEAT results which contains the model fit residuals (typically called
res4d.nii.gz
).Raises a
PathError
if the file does not exist.- Parameters
featdir – A FEAT directory.
-
fsl.data.featanalysis.
getPEFile
(featdir, ev)¶ Returns the path of the PE file for the specified EV.
Raises a
PathError
if the file does not exist.- Parameters
featdir – A FEAT directory.
ev – The EV number (0-indexed).
-
fsl.data.featanalysis.
getCOPEFile
(featdir, contrast)¶ Returns the path of the COPE file for the specified contrast.
Raises a
PathError
if the file does not exist.- Parameters
featdir – A FEAT directory.
contrast – The contrast number (0-indexed).