`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. the shallowest in the file system) directory is returned.
`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.
`loadFTests`	Loads F-tests from a FEAT directory.
`loadFsf`	Loads the analysis settings from a text file (.fsf) used to configure FEAT.
`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 or f-test.
`loadFEATDesignFile`	Load a FEAT design file, e.g. `design.mat`, `design.con`, `design.fts`.

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.
`getZFStatFile`	Returns the path of the Z-statistic file for the specified F-test.
`getClusterMaskFile`	Returns the path of the cluster mask file for the specified contrast.
`getFClusterMaskFile`	Returns the path of the cluster mask file for the specified f-test.

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.loadFTests(featdir)[source]

Loads F-tests from a FEAT directory. Returns a list of f-test vectors (each of which is a list itself), where each vector contains a 1 or a 0 denoting the contrasts included in the F-test.

Parameters:: featdir – A FEAT directory.

fsl.data.featanalysis.loadFsf(designfsf)[source]

Loads the analysis settings from a text file (.fsf) used to configure FEAT.

Returns a dict containing the settings specified in the file

Parameters:: designfsf – A .fsf file.

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, ftest=False)[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 or f-test.

If there are no cluster results for the given contrast/f-test, 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 or f-test number.
ftest – If False (default), return cluster results for the contrast numbered contrast. Otherwise, return cluster results for the f-test numbered contrast.

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 (not present for f-tests).

copemaxx

X voxel coordinate of maximum COPE value (not present for f-tests).

copemaxy

Y voxel coordinate of maximum COPE value. (not present for f-tests).

copemaxz

Z voxel coordinate of maximum COPE value. (not present for f-tests).

copemean

Mean COPE of all voxels in the cluster. (not present for f-tests).

fsl.data.featanalysis.loadFEATDesignFile(filename)[source]

Load a FEAT design file, e.g. design.mat, design.con, design.fts.

These files contain key-value pairs, and are formatted according to an undocumented structure where each key is of the form “/KeyName”, and is followed immediately by a whitespace character, and then the value.

Parameters:: filename – File to load
Returns:: A dictionary of key-value pairs. The values are all left as strings.

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