Graphical user interface quickstart

The GUI allows you to load and explore the following types of data:

• fMRIprep-processed datasets

• NIFTI files (.nii, .nii.gz)

• CIFTI files (.dtseries.nii)

• Time series data in multiple formats (.txt, .csv, .tsv, .npy, .mat)

Downloading data

In this tutorial, we will use two examples to demonstrate the GUI.

You can run either (or both) of the following code cells to download sample data, or simply use your own data if you already have some.

Single NIfTI file

Download a single NIfTI file from the ADHD dataset via nilearn and save it in your working directory.

(This process may take about a minute. Set verbose=1 if you would like to see the download progress.)

from nilearn import datasets

save_dir = "."
adhd_data = datasets.fetch_adhd(data_dir=save_dir, n_subjects=1)

[fetch_adhd] Dataset found in adhd

BIDS Dataset

As a secod option, you can fetch fMRIprep-processed data from the Engaging in word recognition elicits highly specific modulations in visual cortex dataset (ds004489) on OpenNeuro:

For this, datalad and git-annex are required: https://www.datalad.org/.

You can install them by running the following commands in any terminal (ideally one where your Comet Python environment is activated):

pip install datalad-installer
datalad-installer git-annex -m datalad/packages
pip install datalad

You can then install the dataset in the current working directory and download a single BOLD + confounds file by typing:

datalad install https://github.com/OpenNeuroDatasets/ds004489.git
cd ds004489
datalad get derivatives/sub-114/ses-1/func/sub-114_ses-1_task-catLoc_run-1_space-T1w_desc-preproc_bold.nii.gz
datalad get derivatives/sub-114/ses-1/func/sub-114_ses-1_task-catLoc_run-1_desc-confounds_timeseries.tsv

Starting the GUI

You can launch the graphical user interface by running comet-gui in the terminal.

For example, if you have installed the toolbox in an environment called comet, this will looks something like this:

(comet) user@pc:~$ comet-gui

As a result, you should be greeted with the data tab of the graphical user interface.

Data preparation

Using a single NIFTI file

Click Load from single file and select the previously downloaded file:

adhd/data/0010042/0010042_rest_tshift_RPI_voreg_mni.nii.gz.

A panel will appear with several preprocessing options, such as:

• Detrending and standardising the data (enabled by default)

• Temporal filtering (requires the TR to be specified)

• Selecting a parcellation scheme

• Discarding initial frames (non-stationary volumes are also detected automatically)

• …

In the example below, we additionally loaded the corresponding confounds file,

selected a subset of regressors (CSF, WM, and translational motion), and applied low-pass filtering at 0.1 Hz.

Once your settings are chosen, click Extract time series to process and parcellate the data.

The extracted time series will then be available in the Connectivity Analysis tab.

Using fMRIprep-processed data

Click Load from fMRIprep outputs and open the ds004489/derivatives folder.

Once the dataset layout is loaded, select:

• Subject: sub114

• Task: catLoc

• Session: 1

• Run: 1

Note: Although the full dataset structure is initialised, only the data for this specific participant and run was downloaded above.

The preprocessing options are similar to those for a single NIFTI file.

However, since fMRIprep outputs include several confound regressors, additional cleaning options are available in the Cleaning strategy panel.

For example, in the screenshot below we selected motion, wm_csf, and high_pass

This setup regresses out motion, white matter, and cerebrospinal fluid confounds, and applies a high-pass filter.

These strategies follow the implementation documented in nilearn.

You can also hover over the ℹ️ icons in the GUI to view short explanations.

Finally, click Extract time series to process and parcellate the data.

The resulting time series will then appear in the Connectivity Analysis tab.

Connectivity analysis

Once the data has been prepared in the Data Preparation tab, connectivity estimation is straightforward: simply choose a method and adjust its parameters as needed.

After the estimation is complete, key metrics can be explored on the right-hand side of the GUI.

A particularly useful feature is the ability to compare different connectivity estimates.

For example, you can quickly explore how varying key parameters—such as the window size or window shape—affects sliding-window correlations:

State-based analysis

For state-based connectivity analyses, it is often useful to work with data from multiple time series.

In the GUI, this is currently supported via 3D time series arrays of shape: \(N_{\text{subjects}} \times N_{\text{timepoints}} \times N_{\text{regions}}\).

These could be created e.g. from data as shown in State-based dynamic functional connectivity notebook.

When loaded, the data will appear in the GUI as shown below:

Graph analysis

Connectivity estimates from the Connectivity analysis tab can be directly used for graph analysis.

Alternatively, you may also load connectivity estimates from a file.

The typical workflow is as follows:

1. Apply processing steps to the connectivity matrices, such as handling negative values or applying thresholding. Example: In the screenshots below, negative values were removed and matrices were thresholded to 40% density before computing the clustering coefficient.

2. Estimate graph measures, which are then visualised in the Graph Measures tab.

Multiverse analysis

We generally recommend performing multiverse analyses in code, but the GUI also provides some basic functionality.

As a starting point, you can simply run the multiverse example included with the GUI.

1. Click Create multiverse to open a file dialog and choose where the multiverse analysis folder should be created.

2. Click Run multiverse to execute the analysis. Results will then appear in the Multiverse Overview and Specification Curve tabs.

You can also modify the example:

1. For instance, add the number 5 to the number_2 decision and confirm with the checkmark button.

2. If you don’t mind overwriting previous results, you can skip creating a new multiverse and simply press Run multiverse again to update the analysis.

Running a previously implemented multiverse analysis

If you already defined a multiverse analysis in a Jupyter Notebook (e.g. the tutorial multiverse example), you can load it into the GUI via the Load script button and continue interacting with it.

Decisions and options can be added or removed through the left-hand panel, while code changes can be directly edited in the right-hand panel.

For example, the autism classification workflow can be loaded from tutorials/example_mv_abide.ipynb and explored in the GUI. Before creating and running the multiverse, make sure you have previously downloaded the data as described in tutorials/example_mv_abide.ipynb and provide an absolute path to it (as well as a a subset of subjects to speed up the calculation):

SUB_IDS = [50012, 50014, 50015, 50016, 50020, 50022, 50023, 50024, 50025, 50027, # controls
           50030, 50031, 50032, 50033, 50034, 50035, 50036, 50037, 50038, 50040] # autism

# Get data (if available, it will be loaded from disk)
data = datasets.fetch_abide_pcp(SUB_ID=SUB_IDs,
                                data_dir="<PATH_TO_DATA>",
                                verbose=0,
                                pipeline={{pipeline}},
                                derivatives={{parcellation}},
                                band_pass_filtering={{band_pass}},
                                global_signal_regression={{global_signal}})