fsl.data.fixlabels

This module contains functions for loading/saving FIX/ICA-AROMA label files.

loadLabelFile	Loads component labels from the specified file. The file is assumed to be of the format generated by FIX, Melview or ICA-AROMA; such a file should have a structure resembling the following::.
saveLabelFile	Saves the given classification labels to the specified file.
isNoisyComponent	Given a set of component labels, returns True if the component is ultimately classified as noise, False otherwise.
InvalidLabelFileError	Exception raised by the loadLabelFile() function when an attempt is made to load an invalid label file.

fsl.data.fixlabels.loadLabelFile(filename, includeLabel=None, excludeLabel=None, returnIndices=False, missingLabel='Unknown', returnProbabilities=False)

Loads component labels from the specified file. The file is assumed to be of the format generated by FIX, Melview or ICA-AROMA; such a file should have a structure resembling the following:

filtered_func_data.ica
1, Signal, False
2, Unclassified Noise, True
3, Unknown, False
4, Signal, False
5, Unclassified Noise, True
6, Unclassified Noise, True
7, Unclassified Noise, True
8, Signal, False
[2, 5, 6, 7]

Note

This function will also parse files which only contain a component list, e.g.:

[2, 5, 6, 7]

The square brackets may or may not be present, i.e. the following format is also accepted (this format is generated by ICA-AROMA):

2, 5, 6, 7

In this case, the returned melodic directory path will be None. The includeLabel and excludeLabel arguments allow you to control the labels assigned to included/excluded components.

The first line of the file contains the name of the melodic directory. Then, one line is present for each component, containing the following, separated by commas:

• The component index (starting from 1).

• One or more labels for the component (multiple labels must be comma-separated).

• 'True' if the component has been classified as bad, 'False' otherwise. This field is optional - if the last non-numeric comma-separated token on a line is not equal to True or False (case-insensitive) , it is interpreted as a component label.

• A value between 0 and 1, which gives the probability of the component being signal, as generated by an automatic classifier (e.g. FIX). This field is optional - it is output by some versions of FIX.

The last line of the file contains the index (starting from 1) of all bad components, i.e. those components which are not classified as signal or unknown.

Parameters:

• filename – Name of the label file to load.

• includeLabel – If the file contains a single line containing a list component indices, this label will be used for the components in the list. Defaults to 'Unclassified noise' for FIX-like files, and 'Movement' for ICA-AROMA-like files.

• excludeLabel – If the file contains a single line containing component indices, this label will be used for the components that are not in the list. Defaults to 'Signal' for FIX-like files, and 'Unknown' for ICA-AROMA-like files.

• returnIndices – Defaults to False. If True, a list containing the noisy component numbers that were listed in the file is returned.

• missingLabel – Label to use for any components which are not present (only used for label files, not for noise component files).

• returnProbabilities – Defaults to False. If True, a list containing the component classification probabilities is returned. If the file does not contain probabilities, every value in this list will be nan.

Returns:

A tuple containing:

• The path to the melodic directory as specified in the label file

• A list of lists, one list per component, with each list containing the labels for the corresponding component.

• If returnIndices is True, a list of the noisy component indices (starting from 1) that were specified in the file.

• If returnProbabilities is True, a list of the component classification probabilities that were specified in the file (all nan if they are not in the file).

Note

Some label files generated by old versions of FIX/Melview do not contain a line for every component (unknown/unlabelled components may not be listed). For these files, and also for files which only contain a component list, there is no way of knowing how many components were in the data, so the returned list may contain fewer entries than there are components.

fsl.data.fixlabels._parseSingleLineLabelFile(lines, includeLabel, excludeLabel)

Called by loadLabelFile(). Parses the contents of an ICA-AROMA-style label file which just contains a list of noise components (and possibly the MELODIC directory path), e.g.:

filtered_func_data.ica
[2, 5, 6, 7]

fsl.data.fixlabels._parseFullLabelFile(filename, lines, missingLabel)

Called by loadLabelFile(). Parses the contents of a FIX/Melview-style label file which contains labels for each component, e.g.:

filtered_func_data.ica 1, Signal, False 2, Unclassified Noise, True 3, Unknown, False 4, Signal, False 5, Unclassified Noise, True 6, Unclassified Noise, True 7, Unclassified Noise, True 8, Signal, False [2, 5, 6, 7]

fsl.data.fixlabels._isfloat(s)

Returns True if the given string appears to contain a floating point number, False otherwise.

fsl.data.fixlabels.saveLabelFile(allLabels, filename, dirname=None, listBad=True, signalLabels=None, probabilities=None)

Saves the given classification labels to the specified file. The classifications are saved in the format described in the loadLabelFile() method.

Parameters:

• allLabels – A list of lists, one list for each component, where each list contains the labels for the corresponding component.

• filename – Name of the file to which the labels should be saved.

• dirname – If provided, is output as the first line of the file. Intended to be a relative path to the MELODIC analysis directory with which this label file is associated. If not provided, a '.' is output as the first line.

• listBad – If True (the default), the last line of the file will contain a comma separated list of components which are deemed ‘noisy’ (see isNoisyComponent()).

• signalLabels – Labels which should be deemed ‘signal’ - see the isNoisyComponent() function.

• probabilities – Classification probabilities. If provided, the probability for each component is saved to the file.

fsl.data.fixlabels.isNoisyComponent(labels, signalLabels=None)

Given a set of component labels, returns True if the component is ultimately classified as noise, False otherwise.

Parameters:

signalLabels – Labels which are deemed signal. If a component has no labels in this list, it is deemed noise. Defaults to ['Signal', 'Unknown'].

exception fsl.data.fixlabels.InvalidLabelFileError

Bases: Exception

Exception raised by the loadLabelFile() function when an attempt is made to load an invalid label file.

__module__ = 'fsl.data.fixlabels'

__weakref__

list of weak references to the object (if defined)