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)

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 thresholding

  • z: Z-statistic thresholding

Parameters

settings – A FEAT settings dictionary (see loadSettings()).

fsl.data.featanalysis.isFirstLevelAnalysis(settings)

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)

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)

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

fsl.data.featanalysis.getZStatFile(featdir, contrast)

Returns the path of the Z-statistic 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).

fsl.data.featanalysis.getClusterMaskFile(featdir, contrast)

Returns the path of the cluster mask 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).