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:
isFEATImage |
Returns True if the given path looks like it is the input data to a FEAT analysis, False otherwise. |
isFEATDir |
Returns True if the given path looks like a FEAT directory, or looks like the input data for a FEAT analysis, False otherwise. |
hasStats |
Returns True if it looks like statistics have been calculated for the given FEAT analysis, False otherwise. |
hasMelodicDir |
Returns True if the data for the given FEAT directory has had MELODIC run on it, False otherwise. |
getAnalysisDir |
If the given path is contained within a FEAT directory, the path to that FEAT directory is returned. |
getTopLevelAnalysisDir |
If the given path is contained within a hierarchy of FEAT or MELODIC directories, the path to the highest-level (i.e. |
isFirstLevelAnalysis |
Returns True if the FEAT analysis described by settings is a first level analysis, False otherwise. |
loadDesign |
Loads the design matrix from a FEAT directory. |
loadContrasts |
Loads the contrasts from a FEAT directory. |
loadSettings |
Loads the analysis settings from a FEAT directory. |
getThresholds |
Given a FEAT settings dictionary, returns a dictionary of {stat : threshold} mappings, containing the thresholds used in the FEAT statistical analysis. |
loadClusterResults |
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:
getDataFile |
Returns the name of the file in the FEAT directory which contains the model input data (typically called filtered_func_data.nii.gz ). |
getResidualFile |
Returns the name of the file in the FEAT results which contains the model fit residuals (typically called res4d.nii.gz ). |
getMelodicFile |
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). |
getPEFile |
Returns the path of the PE file for the specified EV. |
getCOPEFile |
Returns the path of the COPE file for the specified contrast. |
getZStatFile |
Returns the path of the Z-statistic file for the specified contrast. |
getClusterMaskFile |
Returns the path of the cluster mask file for the specified contrast. |
-
fsl.data.featanalysis.
isFEATImage
(path)[source]¶ Returns
True
if the given path looks like it is the input data to a FEAT analysis,False
otherwise.
-
fsl.data.featanalysis.
isFEATDir
(path)[source]¶ 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. - Must be named
-
fsl.data.featanalysis.
hasStats
(featdir)[source]¶ Returns
True
if it looks like statistics have been calculated for the given FEAT analysis,False
otherwise.
-
fsl.data.featanalysis.
hasMelodicDir
(featdir)[source]¶ Returns
True
if the data for the given FEAT directory has had MELODIC run on it,False
otherwise.
-
fsl.data.featanalysis.
getAnalysisDir
(path)[source]¶ 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)[source]¶ 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)[source]¶ Returns the path to the FEAT report index file, or
None
if there is no report.
-
fsl.data.featanalysis.
loadContrasts
(featdir)[source]¶ 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)[source]¶ Loads the analysis settings from a FEAT directory.
Returns a dict containing the settings specified in the
design.fsf
file within the directoryParameters: featdir – A FEAT directory.
-
fsl.data.featanalysis.
loadDesign
(featdir, settings)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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).