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

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 directory

Parameters:	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 thresholding

z: Z-statistic thresholding

Parameters:	settings – A FEAT settings dictionary (see `loadSettings()`).

fsl.data.featanalysis.isFirstLevelAnalysis(settings)[source]¶

Returns True if the FEAT analysis described by settings 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. A Cluster 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).