IC classification

FSLeyes has some features to assist you in viewing and classifying the results of a MELODIC analysis. In particular, FSLeyes offers similar capability to the Melview tool, for manual component classification. Manual classification of MELODIC components is a necessary step in training the FIX classifier.

Loading a MELODIC analysis

You can load a MELODIC analysis in a few different ways:

  • From the command line - you can specify either an .ica directory *:

    fsleyes path/to/my_analysis.ica
    

    Or the melodic_IC image:

    fsleyes path/to/my_analysis.ica/melodic_IC
    
  • Via FileAdd from directory - select your .ica analysis directory.

  • Via FileAdd from file - select the melodic_IC image located in your .ica analysis directory.

*

If you are working with a single-subject analysis generated via the MELODIC GUI, there will be two levels of directories ending in .ica. You need to pass the path to the inner directory to FSLeyes - this is typically called filtered_func_data.ica.

The MELODIC layout

The MELODIC layout arranges the FSLeyes interface in a layout inspired by Melview, to assist in manual component classification.

_images/ic_classification_melodic_perspective.png

The MELODIC layout comprises a lightbox view, a time series and power spectrum view, and an IC classification panel (described below).

You can activate the MELODIC layout via the ViewLayoutsMELODIC mode menu item. Or you can tell FSLeyes to start up with the MELODIC layout via the command line:

fsleyes -s melodic path/to/my_analysis.ica

Component time series and power spectra

The time series and power spectrum views both recognise when you are viewing a melodic_IC image from a MELODIC analysis. Instead of plotting the intensities at the current voxel, the time series and power spectrum for the current component is plotted - the current component is determined by the 3D volume that you are currently viewing.

If, instead of viewing the time series and power spectrum for the current component, you actually want to view the voxel intensities or voxel power spectrum from a melodic_IC file, both plotting views have an option, accessed through the plot control panel:

_images/ic_classification_time_series_settings.png _images/ic_classification_power_spectrum_settings.png

The Plot component time series for Melodic images and Plot component power spectra for Melodic images, both enabled by default, allow you to choose between plotting data for the current component, or plotting data for the current voxel.

Classifying components with the classification panel

The IC classification panel allows you to view and modify classification labels for each component in a melodic_IC file . The IC classification panel displays a list of components, and one or more classification labels for each component:

_images/ic_classification_classification_panel_components.png

The Components and Labels tabs along the top allow you to switch between organising the list by component, or organising the list by label. The Labels tab displays the same information, but organised by label, instead of by component:

_images/ic_classification_classification_panel_labels.png

The buttons along the bottom of the panel allow you to:

  • Load labels Load a set of classifications from a file (see the section on the label file format below).

  • Save labels Save your labels to a file. These files can be used as inputs to FIX.

  • Clear labels Clear all of the existing labels - each component will be given a label of Unknown.

When working in the Components list, each row contains the labels for one component, corresponding to one volume in the melodic_IC file . If you are using the MELODIC layout, when you select a row in the component list, the lightbox, time series, and power spectrum views will update to display the volume, time course, and power spectrum corresponding to the selected component.

The classification panel can actually be used to label the volumes of any 4D NIFTI image, not just melodic_IC images.

Important: In FSLeyes 1.1.0, component indices start at 1, but volume indices start at 0! This means that, for example, IC #1 in the classification panel corresponds to volume 0 in the melodic_IC file (as reported in the location panel).

The classification panel is designed to be used entirely with the keyboard §:

  1. Move up and down the list with the ↑ and ↓ keys.

  2. When you select a row, simply start typing the label you wish to apply to the component. A drop-down box will appear containing a list of known labels. You can use the ↑ and ↓ keys to select an entry from this list, or continue typing the label manually. Press Enter when you have finished typing, and the label will be added to the component.

  3. When you select a row, you can also press Enter to display the drop down box immediately, instead of typing a label.

  4. You can use the ← and → keys to move between labels for the current component. When a label is selected (the label box will be outlined with a faint pink border) you can push the Delete key to remove that label from the component.

While the above description pertains to the Components list, the Labels list can be used in the same manner.

§

Keyboard navigation may not work correctly on some platforms - refer to the troubleshooting page for more details.

IC Classification file format

The file format used by FSLeyes for storing IC classification labels is compatible to that used by Melview and FIX. FSLeyes is also able to load label files generated by ICA-AROMA, a classifier for detecting motion-related ICs.

An IC classificaiton file is a plain text file which looks like this:

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, Non-brain, Movement, True
8, Signal, False
[2, 5, 6, 7]

The file format comprises three sections:

  • The first line of the file contains the name of the MELODIC directory which the label file corresponds to (specified as a path relative to the location of the label file).

  • Then, one line is present for each component. Each component line contains the following, separated by commas:

    • The component index (starting from 1).

    • One or more labels for the component (multiple labels are separated with a comma).

    • True if the component has been classified as a bad component #, False otherwise.

  • The last line of the file contains the indices (starting from 1) of all bad components. These indices are separated with commas, and contained within square brackets.

FSLeyes is also capable of loading classification files which only contain the bad component list. Such files contain a single line of comma-separated component indices, which may or may not be contained within square brackets. For example:

[2, 5, 6, 7]

This is also valid:

2, 5, 6, 7

The one exception to this is that files saved with FSLeyes, which contain more than one label per component, cannot be loaded into Melview. These files can be used with FIX, however.

#

A bad component is defined as any component which does not have a a label of Signal or Unknown.