{ "cells": [ { "cell_type": "markdown", "id": "76ad5adb", "metadata": {}, "source": [ "# Graphical user interface quickstart\n", "\n", "The GUI allows you to load and explore the following types of data:\n", "\n", "- fMRIprep-processed datasets \n", "- NIFTI files (`.nii`, `.nii.gz`) \n", "- CIFTI files (`.dtseries.nii`) \n", "- Time series data in multiple formats (`.txt`, `.csv`, `.tsv`, `.npy`, `.mat`) \n", "\n", "## Downloading data\n", "\n", "In this tutorial, we will use two examples to demonstrate the GUI. \n", "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.\n", "\n", "\n", "### Single NIfTI file\n", "\n", "Download a single NIfTI file from the ADHD dataset via nilearn and save it in your working directory. \n", "(This process may take about a minute. Set `verbose=1` if you would like to see the download progress.)" ] }, { "cell_type": "code", "execution_count": 1, "id": "b92c5d2f", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
[fetch_adhd] Dataset found in adhd\n",
       "
\n" ], "text/plain": [ "\u001b[1;34m[\u001b[0m\u001b[34mfetch_adhd\u001b[0m\u001b[1;34m]\u001b[0m Dataset found in adhd\n" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "from nilearn import datasets\n", "\n", "save_dir = \".\"\n", "adhd_data = datasets.fetch_adhd(data_dir=save_dir, n_subjects=1)" ] }, { "cell_type": "markdown", "id": "72a5f05e", "metadata": {}, "source": [ "### BIDS Dataset\n", "\n", "As a secod option, you can fetch fMRIprep-processed data from the [Engaging in word recognition elicits highly specific modulations in visual cortex](https://openneuro.org/datasets/ds004489/versions/1.0.0) dataset (ds004489) on OpenNeuro:\n", "\n", "For this, `datalad` and `git-annex` are required: https://www.datalad.org/. \n", "You can install them by running the following commands in any terminal (ideally one where your Comet Python environment is activated):\n", "\n", "```bash\n", "pip install datalad-installer\n", "datalad-installer git-annex -m datalad/packages\n", "pip install datalad\n", "```\n", "\n", "You can then install the dataset in the current working directory and download a single BOLD + confounds file by typing:\n", "\n", "```bash\n", "datalad install https://github.com/OpenNeuroDatasets/ds004489.git\n", "cd ds004489\n", "datalad get derivatives/sub-114/ses-1/func/sub-114_ses-1_task-catLoc_run-1_space-T1w_desc-preproc_bold.nii.gz\n", "datalad get derivatives/sub-114/ses-1/func/sub-114_ses-1_task-catLoc_run-1_desc-confounds_timeseries.tsv\n", "```" ] }, { "cell_type": "markdown", "id": "b7aca261", "metadata": {}, "source": [ "## Starting the GUI\n", "\n", "You can launch the graphical user interface by running `comet-gui` in the terminal. \n", "For example, if you have installed the toolbox in an environment called `comet`, this will looks something like this:\n", "\n", "```bash\n", "(comet) user@pc:~$ comet-gui\n", "```\n", "\n", "As a result, you should be greeted with the data tab of the graphical user interface.\n", "\n", "\"start\"" ] }, { "cell_type": "markdown", "id": "c4345561", "metadata": {}, "source": [ "## Data preparation\n", "\n", "### Using a single NIFTI file\n", "\n", "Click **Load from single file** and select the previously downloaded file: \n", "`adhd/data/0010042/0010042_rest_tshift_RPI_voreg_mni.nii.gz`.\n", "\n", "A panel will appear with several preprocessing options, such as:\n", "\n", "- Detrending and standardising the data (enabled by default) \n", "- Temporal filtering (requires the TR to be specified) \n", "- Selecting a parcellation scheme \n", "- Discarding initial frames (non-stationary volumes are also detected automatically) \n", "- … \n", "\n", "In the example below, we additionally loaded the corresponding confounds file, \n", "selected a subset of regressors (CSF, WM, and translational motion), and applied low-pass filtering at 0.1 Hz.\n", "\n", "Once your settings are chosen, click **Extract time series** to process and parcellate the data. \n", "The extracted time series will then be available in the **Connectivity Analysis** tab.\n", "\n", "\"single\"\n" ] }, { "cell_type": "markdown", "id": "f8dac83b", "metadata": {}, "source": [ "### Using fMRIprep-processed data\n", "\n", "Click **Load from fMRIprep outputs** and open the `ds004489/derivatives` folder. \n", "\n", "Once the dataset layout is loaded, select: \n", "- Subject: `sub114` \n", "- Task: `catLoc` \n", "- Session: `1` \n", "- Run: `1` \n", "\n", "*Note: Although the full dataset structure is initialised, only the data for this specific participant and run was downloaded above.* \n", "\n", "The preprocessing options are similar to those for a single NIFTI file. \n", "However, since fMRIprep outputs include several confound regressors, additional cleaning options are available in the **Cleaning strategy** panel. \n", "\n", "For example, in the screenshot below we selected `motion`, `wm_csf`, and `high_pass` \n", "\n", "This setup regresses out motion, white matter, and cerebrospinal fluid confounds, and applies a high-pass filter. \n", "These strategies follow the implementation documented in [nilearn](https://nilearn.github.io/dev/modules/generated/nilearn.interfaces.fmriprep.load_confounds.html). \n", "You can also hover over the **ℹ️** icons in the GUI to view short explanations. \n", "\n", "Finally, click **Extract time series** to process and parcellate the data. \n", "The resulting time series will then appear in the **Connectivity Analysis** tab.\n", "\n", "\"fmriprep\"\n" ] }, { "cell_type": "markdown", "id": "3a0c3046", "metadata": {}, "source": [ "## Connectivity analysis\n", "\n", "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. \n", "After the estimation is complete, key metrics can be explored on the right-hand side of the GUI.\n", "\n", "\"sw\"\n", "\n", "A particularly useful feature is the ability to compare different connectivity estimates. \n", "For example, you can quickly explore how varying key parameters—such as the window size or window shape—affects sliding-window correlations:\n", "\n", "

\n", " \"sw2\"\n", " \"sw3\"\n", "

\n" ] }, { "cell_type": "markdown", "id": "ae26770c", "metadata": {}, "source": [ "### State-based analysis\n", "\n", "For state-based connectivity analyses, it is often useful to work with data from multiple time series. \n", "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}}$.\n", "\n", "These could be created e.g. from data as shown in [State-based dynamic functional connectivity](example_dfc_state1.ipynb) notebook. \n", "When loaded, the data will appear in the GUI as shown below:\n", "\n", "

\n", " \"state1\"\n", " \"state2\"\n", "

" ] }, { "cell_type": "markdown", "id": "f7e2f50c", "metadata": {}, "source": [ "## Graph analysis\n", "\n", "Connectivity estimates from the **Connectivity analysis** tab can be directly used for graph analysis. \n", "Alternatively, you may also load connectivity estimates from a file. \n", "\n", "The typical workflow is as follows:\n", "\n", "1. Apply processing steps to the connectivity matrices, such as handling negative values or applying thresholding. \n", " *Example: In the screenshots below, negative values were removed and matrices were thresholded to 40% density before computing the clustering coefficient.* \n", "2. Estimate graph measures, which are then visualised in the **Graph Measures** tab. \n", "\n", "

\n", " \"graph1\"\n", " \"graph2\"\n", "

\n" ] }, { "cell_type": "markdown", "id": "68787ed4", "metadata": {}, "source": [ "## Multiverse analysis\n", "\n", "We generally recommend performing multiverse analyses in code, but the GUI also provides some basic functionality. \n", "As a starting point, you can simply run the multiverse example included with the GUI.\n", "\n", "1. Click **Create multiverse** to open a file dialog and choose where the multiverse analysis folder should be created. \n", "2. Click **Run multiverse** to execute the analysis. Results will then appear in the **Multiverse Overview** and **Specification Curve** tabs. \n", "\n", "

\n", " \"mv1\"\n", " \"mv2\"\n", "

\n", "\n", "You can also modify the example:\n", "\n", "1. For instance, add the number `5` to the `number_2` decision and confirm with the checkmark button. \n", "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. \n", "\n", "### Running a previously implemented multiverse analysis\n", "\n", "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. \n", "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. \n", "\n", "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):\n", "\n", "```python\n", "SUB_IDS = [50012, 50014, 50015, 50016, 50020, 50022, 50023, 50024, 50025, 50027, # controls\n", " 50030, 50031, 50032, 50033, 50034, 50035, 50036, 50037, 50038, 50040] # autism\n", "\n", "# Get data (if available, it will be loaded from disk)\n", "data = datasets.fetch_abide_pcp(SUB_ID=SUB_IDs,\n", " data_dir=\"\",\n", " verbose=0, \n", " pipeline={{pipeline}},\n", " derivatives={{parcellation}},\n", " band_pass_filtering={{band_pass}},\n", " global_signal_regression={{global_signal}})\n", "```\n", "\n", "

\n", " \"mv3\"\n", " \"mv4\"\n", " \"mv5\"\n", "

" ] } ], "metadata": { "kernelspec": { "display_name": "comet", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.13.0" } }, "nbformat": 4, "nbformat_minor": 5 }