From 3a7418737f059450fac3ac7d717de513a0ace762 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 16 Sep 2023 20:11:28 +0000 Subject: [PATCH] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- demos/MoAE/moae_01_bids_app.ipynb | 720 +++++++++---------- demos/renaming/spm_2_bids_filenames.ipynb | 836 +++++++++++----------- 2 files changed, 778 insertions(+), 778 deletions(-) diff --git a/demos/MoAE/moae_01_bids_app.ipynb b/demos/MoAE/moae_01_bids_app.ipynb index df8848ea8..7871a527b 100644 --- a/demos/MoAE/moae_01_bids_app.ipynb +++ b/demos/MoAE/moae_01_bids_app.ipynb @@ -1,369 +1,369 @@ { - "cells": [ - { - "cell_type": "markdown", - "id": "13de9b92", - "metadata": {}, - "source": [ - "# MoAE demo\n", - "\n", - "This script shows how to use the bidspm BIDS app\n", - "\n", - "- **Download**\n", - "\n", - " - download the dataset from the FIL for the block design SPM tutorial\n", - "\n", - "\n", - "- **Preprocessing**\n", - "\n", - " - copies the necessary data from the raw to the derivative folder,\n", - " - runs spatial preprocessing\n", - "\n", - " those are otherwise handled by the workflows:\n", - "\n", - " - ``bidsCopyInputFolder.m``\n", - " - ``bidsSpatialPrepro.m``\n", - "\n", - "\n", - "- **Stats**\n", - "\n", - " This will run the subject level GLM and contrasts on it of the MoaE dataset\n", - "\n", - " - GLM specification + estimation\n", - " - compute contrasts\n", - " - show results\n", - "\n", - " that are otherwise handled by the workflows\n", - "\n", - " - ``bidsFFX.m``\n", - " - ``bidsResults.m``\n", - "\n", - " .. note::\n", - "\n", - " Results might be a bit different from those in the SPM manual as some\n", - " default options are slightly different in this pipeline\n", - " (e.g use of FAST instead of AR(1), motion regressors added)\n", - "\n", - "\n", - " type `bidspm help` or `bidspm('action', 'help')`\n", - " or see this page: https://bidspm.readthedocs.io/en/stable/bids_app_api.html\n", - " for more information on what parameters are obligatory or optional\n", - "\n", - "\n", - " (C) Copyright 2022 Remi Gau\n" - ] - }, - { - "cell_type": "markdown", - "id": "76d1d26b-50a2-499d-9349-12809e6069e8", - "metadata": { - "tags": [] - }, - "source": [ - "## Note: octave notebook\n", - "\n", - "If you are running in an octave notebook.\n", - "\n", - "### Graphic output\n", - "\n", - "When using on Binder some of the SPM graphic output will not be generated, \n", - "as SPM takes this environment as being command line only. \n", - "\n", - "### Running the demo locally\n", - "\n", - "**If you are running this notebook locally AND if SPM is not the in Octave path**\n", - "\n", - "Run the following cell with the appropriate path for your computer.\n", - "\n", - "**Note:** \n", - "SPM will need to be compiled to work for Octave \n", - "for some parts of this demo to work." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "e0e9b1e0", - "metadata": { - "tags": [] - }, - "outputs": [], - "source": [ - "% addpath('/home/remi/matlab/SPM/spm12');" - ] - }, - { - "cell_type": "markdown", - "id": "fdde68b2-6c8f-4a03-9564-f00443f3351d", - "metadata": {}, - "source": [ - "## Initialize bidspm" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "08ce31bb", - "metadata": { - "tags": [] - }, - "outputs": [], - "source": [ - "this_dir = fileparts(mfilename('fullpath'));\n", - "\n", - "addpath(fullfile(this_dir, '..', '..'));\n", - "\n", - "bidspm();" - ] - }, - { - "cell_type": "markdown", - "id": "92963b3b", - "metadata": {}, - "source": [ - "## Download the dataset" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "a34cc928", - "metadata": {}, - "outputs": [], - "source": [ - "download_data = true;\n", - "clean = false;\n", - "download_moae_ds(download_data, clean);" - ] - }, - { - "cell_type": "markdown", - "id": "e1e754e3", - "metadata": {}, - "source": [ - "If the `tree` command is installed on your computer, you view it:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "116eab45-792c-499a-925a-14695895a3ac", - "metadata": {}, - "outputs": [], - "source": [ - "system('tree inputs/raw')" - ] - }, - { - "cell_type": "markdown", - "id": "89e10f7c", - "metadata": {}, - "source": [ - "## Preprocessing\n", - "\n", - "This will run:\n", - "\n", - "- copy the input dataset into a derivative one\n", - "- write a summary description of the data set\n", - "- do slice time correction (if not ignored and if slice timing is specified)\n", - "- realign the functional data (and apply unwarping - if not ignored)\n", - "- coregister the functional to the anatomical one\n", - "- segmentation the anatomical data\n", - "- skullstripping the anatomical data and creation of brain mask in native space\n", - "- normalization to SPM MNI space (IXI549Space)\n", - "- smooth the data" - ] - }, - { - "cell_type": "markdown", - "id": "dbe6fe64", - "metadata": {}, - "source": [ - "You can type `bidspm help` to get more info \n", - "on the arguments and parameters needed by the bidspm app.\n", - "\n", - "But it follows the general pattern of any bidsapp:\n", - "\n", - "```matlab\n", - "bidspm(bids_dir, output_dir, analysis_level, ...)\n", - "```" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "2afd6329", - "metadata": {}, - "outputs": [], - "source": [ - "bidspm help" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "8d9dea94", - "metadata": {}, - "outputs": [], - "source": [ - "% where the raw bids data is\n", - "bids_dir = fullfile(this_dir, 'inputs', 'raw');\n", - "\n", - "% where we want to output it\n", - "% the data will be saved there in bidspm-preproc subfolder\n", - "output_dir = fullfile(this_dir, 'outputs', 'derivatives');\n", - "\n", - "% the subject we want to analyse\n", - "subject_label = '01';\n", - "\n", - "verbosity = 3;" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "954c1e4e", - "metadata": { - "scrolled": true - }, - "outputs": [], - "source": [ - "bidspm(bids_dir, output_dir, 'subject', ...\n", - " 'participant_label', {subject_label}, ... \n", - " 'action', 'preprocess', ...\n", - " 'task', {'auditory'}, ...\n", - " 'ignore', {'unwarp', 'slicetiming'}, ...\n", - " 'space', {'IXI549Space'}, ...\n", - " 'fwhm', 6, ...\n", - " 'verbosity', verbosity);" - ] - }, - { - "cell_type": "markdown", - "id": "ea14282b", - "metadata": {}, - "source": [ - "## Stats" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "7e70cfb4", - "metadata": {}, - "outputs": [], - "source": [ - "% for the stats we need to specifcy where the preprocessed data is\n", - "preproc_dir = fullfile(output_dir, 'bidspm-preproc');" - ] - }, - { - "cell_type": "markdown", - "id": "58d4fec7", - "metadata": {}, - "source": [ - "### BIDS stats model\n", - "\n", - "The model specification as well as the contrasts to compute\n", - "are defined in a BIDS stats model:\n", - "https://bids-standard.github.io/stats-models/" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "309b91a5", - "metadata": {}, - "outputs": [], - "source": [ - "model_file = fullfile(pwd, 'models', 'model-MoAE_smdl.json');" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "726646d7", - "metadata": {}, - "outputs": [], - "source": [ - "system('cat models/model-MoAE_smdl.json')" - ] - }, - { - "cell_type": "markdown", - "id": "cf4d697a", - "metadata": {}, - "source": [ - "### Specify the result to show\n", - "\n", - "Running bidspm for the stats will perform:\n", - "\n", - "- model specification and estimation\n", - "- contrasts computation\n", - "- displaying the results\n", - "\n", - "Hence we need to specify in the options which results\n", - "we want to view and how we want to save it.\n", - "\n", - "The results of a given contrat can be saved as:\n", - "- an png image\n", - "- a SPM montage of slices\n", - "- a thresholded statistical map\n", - "- a binary mask\n", - "- an NIDM results zip file\n", - "- a table of labelled activations\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "d9c0e491", - "metadata": {}, - "outputs": [], - "source": [ - "bidspm(bids_dir, output_dir, 'subject', ...\n", - " 'participant_label', {subject_label}, ...\n", - " 'action', 'stats', ...\n", - " 'preproc_dir', preproc_dir, ...\n", - " 'model_file', model_file, ...\n", - " 'concatenate', false, ...\n", - " 'fwhm', 6, ...\n", - " 'verbosity', verbosity);" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Octave", - "language": "python", - "name": "octave" - }, - "language_info": { - "file_extension": ".m", - "help_links": [ + "cells": [ + { + "cell_type": "markdown", + "id": "13de9b92", + "metadata": {}, + "source": [ + "# MoAE demo\n", + "\n", + "This script shows how to use the bidspm BIDS app\n", + "\n", + "- **Download**\n", + "\n", + " - download the dataset from the FIL for the block design SPM tutorial\n", + "\n", + "\n", + "- **Preprocessing**\n", + "\n", + " - copies the necessary data from the raw to the derivative folder,\n", + " - runs spatial preprocessing\n", + "\n", + " those are otherwise handled by the workflows:\n", + "\n", + " - ``bidsCopyInputFolder.m``\n", + " - ``bidsSpatialPrepro.m``\n", + "\n", + "\n", + "- **Stats**\n", + "\n", + " This will run the subject level GLM and contrasts on it of the MoaE dataset\n", + "\n", + " - GLM specification + estimation\n", + " - compute contrasts\n", + " - show results\n", + "\n", + " that are otherwise handled by the workflows\n", + "\n", + " - ``bidsFFX.m``\n", + " - ``bidsResults.m``\n", + "\n", + " .. note::\n", + "\n", + " Results might be a bit different from those in the SPM manual as some\n", + " default options are slightly different in this pipeline\n", + " (e.g use of FAST instead of AR(1), motion regressors added)\n", + "\n", + "\n", + " type `bidspm help` or `bidspm('action', 'help')`\n", + " or see this page: https://bidspm.readthedocs.io/en/stable/bids_app_api.html\n", + " for more information on what parameters are obligatory or optional\n", + "\n", + "\n", + " (C) Copyright 2022 Remi Gau\n" + ] + }, + { + "cell_type": "markdown", + "id": "76d1d26b-50a2-499d-9349-12809e6069e8", + "metadata": { + "tags": [] + }, + "source": [ + "## Note: octave notebook\n", + "\n", + "If you are running in an octave notebook.\n", + "\n", + "### Graphic output\n", + "\n", + "When using on Binder some of the SPM graphic output will not be generated, \n", + "as SPM takes this environment as being command line only. \n", + "\n", + "### Running the demo locally\n", + "\n", + "**If you are running this notebook locally AND if SPM is not the in Octave path**\n", + "\n", + "Run the following cell with the appropriate path for your computer.\n", + "\n", + "**Note:** \n", + "SPM will need to be compiled to work for Octave \n", + "for some parts of this demo to work." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e0e9b1e0", + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "% addpath('/home/remi/matlab/SPM/spm12');" + ] + }, + { + "cell_type": "markdown", + "id": "fdde68b2-6c8f-4a03-9564-f00443f3351d", + "metadata": {}, + "source": [ + "## Initialize bidspm" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "08ce31bb", + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "this_dir = fileparts(mfilename('fullpath'));\n", + "\n", + "addpath(fullfile(this_dir, '..', '..'));\n", + "\n", + "bidspm();" + ] + }, + { + "cell_type": "markdown", + "id": "92963b3b", + "metadata": {}, + "source": [ + "## Download the dataset" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a34cc928", + "metadata": {}, + "outputs": [], + "source": [ + "download_data = true;\n", + "clean = false;\n", + "download_moae_ds(download_data, clean);" + ] + }, + { + "cell_type": "markdown", + "id": "e1e754e3", + "metadata": {}, + "source": [ + "If the `tree` command is installed on your computer, you view it:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "116eab45-792c-499a-925a-14695895a3ac", + "metadata": {}, + "outputs": [], + "source": [ + "system('tree inputs/raw')" + ] + }, + { + "cell_type": "markdown", + "id": "89e10f7c", + "metadata": {}, + "source": [ + "## Preprocessing\n", + "\n", + "This will run:\n", + "\n", + "- copy the input dataset into a derivative one\n", + "- write a summary description of the data set\n", + "- do slice time correction (if not ignored and if slice timing is specified)\n", + "- realign the functional data (and apply unwarping - if not ignored)\n", + "- coregister the functional to the anatomical one\n", + "- segmentation the anatomical data\n", + "- skullstripping the anatomical data and creation of brain mask in native space\n", + "- normalization to SPM MNI space (IXI549Space)\n", + "- smooth the data" + ] + }, + { + "cell_type": "markdown", + "id": "dbe6fe64", + "metadata": {}, + "source": [ + "You can type `bidspm help` to get more info \n", + "on the arguments and parameters needed by the bidspm app.\n", + "\n", + "But it follows the general pattern of any bidsapp:\n", + "\n", + "```matlab\n", + "bidspm(bids_dir, output_dir, analysis_level, ...)\n", + "```" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2afd6329", + "metadata": {}, + "outputs": [], + "source": [ + "bidspm help" + ] + }, { - "text": "GNU Octave", - "url": "https://www.gnu.org/software/octave/support.html" + "cell_type": "code", + "execution_count": null, + "id": "8d9dea94", + "metadata": {}, + "outputs": [], + "source": [ + "% where the raw bids data is\n", + "bids_dir = fullfile(this_dir, 'inputs', 'raw');\n", + "\n", + "% where we want to output it\n", + "% the data will be saved there in bidspm-preproc subfolder\n", + "output_dir = fullfile(this_dir, 'outputs', 'derivatives');\n", + "\n", + "% the subject we want to analyse\n", + "subject_label = '01';\n", + "\n", + "verbosity = 3;" + ] }, { - "text": "Octave Kernel", - "url": "https://github.com/Calysto/octave_kernel" + "cell_type": "code", + "execution_count": null, + "id": "954c1e4e", + "metadata": { + "scrolled": true + }, + "outputs": [], + "source": [ + "bidspm(bids_dir, output_dir, 'subject', ...\n", + " 'participant_label', {subject_label}, ... \n", + " 'action', 'preprocess', ...\n", + " 'task', {'auditory'}, ...\n", + " 'ignore', {'unwarp', 'slicetiming'}, ...\n", + " 'space', {'IXI549Space'}, ...\n", + " 'fwhm', 6, ...\n", + " 'verbosity', verbosity);" + ] }, { - "text": "MetaKernel Magics", - "url": "https://metakernel.readthedocs.io/en/latest/source/README.html" + "cell_type": "markdown", + "id": "ea14282b", + "metadata": {}, + "source": [ + "## Stats" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7e70cfb4", + "metadata": {}, + "outputs": [], + "source": [ + "% for the stats we need to specifcy where the preprocessed data is\n", + "preproc_dir = fullfile(output_dir, 'bidspm-preproc');" + ] + }, + { + "cell_type": "markdown", + "id": "58d4fec7", + "metadata": {}, + "source": [ + "### BIDS stats model\n", + "\n", + "The model specification as well as the contrasts to compute\n", + "are defined in a BIDS stats model:\n", + "https://bids-standard.github.io/stats-models/" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "309b91a5", + "metadata": {}, + "outputs": [], + "source": [ + "model_file = fullfile(pwd, 'models', 'model-MoAE_smdl.json');" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "726646d7", + "metadata": {}, + "outputs": [], + "source": [ + "system('cat models/model-MoAE_smdl.json')" + ] + }, + { + "cell_type": "markdown", + "id": "cf4d697a", + "metadata": {}, + "source": [ + "### Specify the result to show\n", + "\n", + "Running bidspm for the stats will perform:\n", + "\n", + "- model specification and estimation\n", + "- contrasts computation\n", + "- displaying the results\n", + "\n", + "Hence we need to specify in the options which results\n", + "we want to view and how we want to save it.\n", + "\n", + "The results of a given contrat can be saved as:\n", + "- an png image\n", + "- a SPM montage of slices\n", + "- a thresholded statistical map\n", + "- a binary mask\n", + "- an NIDM results zip file\n", + "- a table of labelled activations\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d9c0e491", + "metadata": {}, + "outputs": [], + "source": [ + "bidspm(bids_dir, output_dir, 'subject', ...\n", + " 'participant_label', {subject_label}, ...\n", + " 'action', 'stats', ...\n", + " 'preproc_dir', preproc_dir, ...\n", + " 'model_file', model_file, ...\n", + " 'concatenate', false, ...\n", + " 'fwhm', 6, ...\n", + " 'verbosity', verbosity);" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Octave", + "language": "python", + "name": "octave" + }, + "language_info": { + "file_extension": ".m", + "help_links": [ + { + "text": "GNU Octave", + "url": "https://www.gnu.org/software/octave/support.html" + }, + { + "text": "Octave Kernel", + "url": "https://github.com/Calysto/octave_kernel" + }, + { + "text": "MetaKernel Magics", + "url": "https://metakernel.readthedocs.io/en/latest/source/README.html" + } + ], + "mimetype": "text/x-octave", + "name": "python", + "version": "3.9.13 | packaged by conda-forge | (main, May 27 2022, 16:58:50) \n[GCC 10.3.0]" + }, + "vscode": { + "interpreter": { + "hash": "57bcab47fba392aaf2481e270a6c32db0c9d247c375febbd49c7b44fb61a4644" + } } - ], - "mimetype": "text/x-octave", - "name": "python", - "version": "3.9.13 | packaged by conda-forge | (main, May 27 2022, 16:58:50) \n[GCC 10.3.0]" }, - "vscode": { - "interpreter": { - "hash": "57bcab47fba392aaf2481e270a6c32db0c9d247c375febbd49c7b44fb61a4644" - } - } - }, - "nbformat": 4, - "nbformat_minor": 5 + "nbformat": 4, + "nbformat_minor": 5 } diff --git a/demos/renaming/spm_2_bids_filenames.ipynb b/demos/renaming/spm_2_bids_filenames.ipynb index 07a2b5b23..794c0bc31 100644 --- a/demos/renaming/spm_2_bids_filenames.ipynb +++ b/demos/renaming/spm_2_bids_filenames.ipynb @@ -1,426 +1,426 @@ { - "cells": [ - { - "cell_type": "markdown", - "id": "748352c4", - "metadata": {}, - "source": [ - "# BIDS filenames\n", - "\n", - "Ideally we would like to have the same pipeline for statistical analysis\n", - "whether our data was preprocessed with SPM or with fmriprep.\n", - "\n", - "## BIDS filenames\n", - "\n", - "Ideally we would like to have the same pipeline for statistical analysis\n", - "whether our data was preprocessed with SPM or with fmriprep (for example).\n", - "\n", - "This is possible under the condition that the input files\n", - "for the statistical analysis are BIDS compliant:\n", - "meaning that they follow the typical pattern of BIDS files:\n", - "\n", - "- pseudo \"regular expression\" : `entity-label(_entity-label)+_suffix.extension`\n", - "\n", - "\n", - "- `entity`, `label`, `suffix`, `extension` are alphanumeric only (no special character): `([a-zA-Z0-9])+`\n", - " - suffixes can be: `T1w` or `bold` but not `T1w_skullstripped` (no underscore allowed)\n", - "\n", - "\n", - "- entity and label are separated by a dash:\n", - " `entity-label --> ([a-zA-Z0-9])+-([a-zA-Z0-9])+`\n", - " - you can have: `sub-01` but not `sub-01-blind`\n", - "\n", - "\n", - "- entity-label pairs are separated by an underscore:\n", - " `entity-label(_entity-label)+ --> ([a-zA-Z0-9])+-([a-zA-Z0-9])+(_([a-zA-Z0-9])+-([a-zA-Z0-9])+)+`\n", - "\n", - "\n", - "- **prefixes are not a thing in official BIDS names**\n", - "\n", - "BIDS has a number of officially recognised entities \n", - "(`sub`, `ses`, `task`...) that must come in a specific order for each data type.\n", - "\n", - "https://bids-specification.readthedocs.io/en/stable/99-appendices/04-entity-table.html\n", - "\n", - "BIDS derivatives adds a few more entities (`desc`, `space`, `res`...)\n", - "and suffixes (`pseg`, `dseg`, `mask`...)\n", - "that can be used to name and describe preprocessed data.\n", - "\n", - "\n", - "(C) Copyright 2022 Remi Gau" - ] - }, - { - "cell_type": "markdown", - "id": "d6eeb784", - "metadata": {}, - "source": [ - "The toolbox BIDS Matlab has some function to help you create bids valid names." - ] - }, - { - "cell_type": "markdown", - "id": "cf83233d", - "metadata": {}, - "source": [ - "## Note: octave notebook\n", - "\n", - "If you are running in an octave notebook.\n", - "\n", - "### Graphic output\n", - "\n", - "When using on Binder some of the SPM graphic output will not be generated, \n", - "as SPM takes this environment as being command line only. \n", - "\n", - "### Running the demo locally\n", - "\n", - "**If you are running this notebook locally AND if SPM is not the in Octave path**\n", - "\n", - "Run the following cell with the appropriate path for your computer.\n", - "\n", - "**Note:** \n", - "SPM will need to be compiled to work for Octave \n", - "for some parts of this demo to work." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "e212e022", - "metadata": {}, - "outputs": [], - "source": [ - "% addpath('/home/remi/matlab/SPM/spm12');" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "efeae953", - "metadata": {}, - "outputs": [], - "source": [ - "this_dir = fileparts(mfilename('fullpath'));\n", - "\n", - "addpath(fullfile(this_dir, '..', '..'));\n", - "\n", - "bidspm();" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "61d66ea6", - "metadata": {}, - "outputs": [], - "source": [ - "file_spec = struct('entities', struct('run', '01', ...\n", - " 'sub', '01', ...\n", - " 'task', 'visMotionLocalizer'), ...\n", - " 'suffix', 'bold', ...\n", - " 'ext', '.nii');\n", - "\n", - "bidsFile = bids.File(file_spec)\n", - "bidsFile.filename" - ] - }, - { - "cell_type": "markdown", - "id": "c968b79a", - "metadata": {}, - "source": [ - "If not enough information is provided, BIDS matlab should hopefully help you figure out what is missing." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "c5b24443", - "metadata": {}, - "outputs": [], - "source": [ - "file_spec = struct('entities', struct('run', '01', ...\n", - " 'sub', '01', ...\n", - " 'task', 'visMotionLocalizer'), ...\n", - " 'suffix', 'events', ...\n", - " 'ext', '.tsv');\n", - " \n", - "bidsFile = bids.File(file_spec)\n", - "bidsFile.filename" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "80e96806", - "metadata": {}, - "outputs": [], - "source": [ - "file_spec.modality = 'func';\n", - "bidsFile = bids.File(file_spec)\n", - "bidsFile.filename" - ] - }, - { - "cell_type": "markdown", - "id": "16feaf02", - "metadata": {}, - "source": [ - "Entities must have a specific order to be BIDS valid.\n", - "You can ignore those rules by not using the bids schema." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "b69c412f", - "metadata": {}, - "outputs": [], - "source": [ - "file_spec = struct('entities', struct('run', '01', ...\n", - " 'sub', '01', ...\n", - " 'task', 'visMotionLocalizer'), ...\n", - " 'suffix', 'bold', ...\n", - " 'ext', '.nii', ...\n", - " 'use_schema', false);\n", - "\n", - "bidsFile = bids.File(file_spec)\n", - "bidsFile.filename" - ] - }, - { - "cell_type": "markdown", - "id": "8200da07", - "metadata": { - "tags": [] - }, - "source": [ - "## Typical SPM filenames\n", - "\n", - "SPM typically adds prefixes to filenames and concatenates them.\n", - "\n", - "- `r` for realigned or resliced\n", - "- `w` for warped (often means normalized in MNI space)\n", - "- `a` for slice time corrected images\n", - "- `u` for unwarped\n", - "- `s` for smoothed\n", - "- `c1` for grey matter tissue probability maps\n", - "- ..." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "c5501a62", - "metadata": {}, - "outputs": [], - "source": [ - "% typical gray matter probabilistic segmentation\n", - "file_spec = struct('entities', struct('sub', '01'), ...\n", - " 'suffix', 'T1w', ...\n", - " 'ext', '.nii', ...\n", - " 'prefix', 'c1');\n", - "\n", - "bidsFile = bids.File(file_spec)\n", - "bidsFile.filename\n", - "\n", - "% typical preprocessed data in native space\n", - "file_spec = struct('entities', struct('run', '01', ...\n", - " 'sub', '01', ...\n", - " 'task', 'visMotionLocalizer'), ...\n", - " 'suffix', 'bold', ...\n", - " 'ext', '.nii', ...\n", - " 'prefix', 'ua');\n", - "\n", - "bidsFile = bids.File(file_spec)\n", - "bidsFile.filename\n", - "\n", - "% typical smoothed preprocessed data in MNI space\n", - "file_spec = struct('entities', struct('run', '01', ...\n", - " 'sub', '01', ...\n", - " 'task', 'visMotionLocalizer'), ...\n", - " 'suffix', 'bold', ...\n", - " 'ext', '.nii', ...\n", - " 'prefix', 'swua');\n", - "\n", - "bidsFile = bids.File(file_spec)\n", - "bidsFile.filename" - ] - }, - { - "cell_type": "markdown", - "id": "e959dead", - "metadata": {}, - "source": [ - "## BIDS derivatives filenames\n", - "But those SPM files are not BIDS valid because official valid BIDS files don't have prefixes.\n", - "\n", - "So SPM output must be renamed to be able to create BIDS valid output datasets." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "46bbae6d", - "metadata": {}, - "outputs": [], - "source": [ - "% space: can specify if this image is in MNI space or individual space\n", - "% desc: description can give more info about what is this file about: \n", - "% \"preproc\" --> \"preprocessed\"\n", - "file_spec = struct('entities', struct('sub', '01', ...\n", - " 'run', '01', ...\n", - " 'task', 'visMotionLocalizer', ...\n", - " 'space', 'MNI', ...\n", - " 'desc', 'preproc'), ...\n", - " 'suffix', 'bold', ...\n", - " 'ext', '.nii');\n", - "\n", - "bidsFile = bids.File(file_spec)\n", - "bidsFile.filename" - ] - }, - { - "cell_type": "markdown", - "id": "ed26d428", - "metadata": {}, - "source": [ - "It can be a pain to create the right map \n", - "between a specific SPM type of output and \"the right\" BIDS equivalent.\n", - "\n", - "So easier to use [the CPP `spm_2_bids` library](https://github.com/cpp-lln-lab/spm_2_bids)\n", - "which will also try to use the \"proper\" MNI space name \n", - "(`IXI594Sapce` is the one used by most of SPM)." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "35ca15c4", - "metadata": {}, - "outputs": [], - "source": [ - "input_name = 'wc1sub-01_T1w.nii';\n", - "output_name = spm_2_bids(input_name)\n", - "\n", - "input_name = 'uasub-01_task-visMotionLocalizer_run-01_bold.nii';\n", - "output_name = spm_2_bids(input_name)\n", - "\n", - "input_name = 'wuasub-01_task-visMotionLocalizer_run-01_bold.nii';\n", - "output_name = spm_2_bids(input_name)" - ] - }, - { - "cell_type": "markdown", - "id": "df5b40b4", - "metadata": {}, - "source": [ - "spm_2_bids contains a certain list of default mapping to use\n", - "for renaming but you can also add some extra or modify the defaults.\n", - "\n", - "bidspm comes with its own preset `spm_2_bids` renaming map." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "4b556407", - "metadata": {}, - "outputs": [], - "source": [ - "opt = checkOptions(struct());\n", - "opt = set_spm_2_bids_defaults(opt);\n", - "\n", - "input_name = 'wc1sub-01_T1w.nii';\n", - "output_name = spm_2_bids(input_name, opt.spm_2_bids)\n", - "\n", - "input_name = 'uasub-01_task-visMotionLocalizer_run-01_bold.nii';\n", - "output_name = spm_2_bids(input_name, opt.spm_2_bids)\n", - "\n", - "input_name = 'wuasub-01_task-visMotionLocalizer_run-01_bold.nii';\n", - "output_name = spm_2_bids(input_name, opt.spm_2_bids)\n", - "\n", - "opt.fwhm.func = 6;\n", - "input_name = 'swuasub-01_task-visMotionLocalizer_run-01_bold.nii';\n", - "output_name = spm_2_bids(input_name, opt.spm_2_bids)" - ] - }, - { - "cell_type": "markdown", - "id": "631f25d0", - "metadata": {}, - "source": [ - "### `bidsRename`\n", - "\n", - "The `bidsRename` workflow uses this to rename all \"SPM files\" at the end of each step.\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "642b1bb8", - "metadata": {}, - "outputs": [], - "source": [ - "demo_dir = fullfile(pwd, '..', 'MoAE');\n", - "\n", - "opt.dir.derivatives = fullfile(demo_dir, 'outputs', 'derivatives');\n", - "opt.dir.preproc = fullfile(opt.dir.derivatives, 'bidspm-preproc');\n", - "\n", - "opt = checkOptions(opt);\n", - "\n", - "bidsRename(opt);" - ] - }, - { - "cell_type": "markdown", - "id": "d7b580ec", - "metadata": {}, - "source": [ - "Example of the end of spatial preprocessing\n", - "\n", - "```matlab\n", - " if ~opt.realign.useUnwarp\n", - " opt.spm_2_bids = opt.spm_2_bids.add_mapping('prefix', opt.spm_2_bids.realign, ...\n", - " 'name_spec', opt.spm_2_bids.cfg.preproc);\n", - "\n", - " opt.spm_2_bids = opt.spm_2_bids.add_mapping('prefix', [opt.spm_2_bids.realign 'mean'], ...\n", - " 'name_spec', opt.spm_2_bids.cfg.preproc);\n", - " opt.spm_2_bids = opt.spm_2_bids.flatten_mapping();\n", - " end\n", - "\n", - " bidsRename(opt);\n", - "``` " - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Octave", - "language": "octave", - "name": "octave" - }, - "language_info": { - "file_extension": ".m", - "help_links": [ + "cells": [ + { + "cell_type": "markdown", + "id": "748352c4", + "metadata": {}, + "source": [ + "# BIDS filenames\n", + "\n", + "Ideally we would like to have the same pipeline for statistical analysis\n", + "whether our data was preprocessed with SPM or with fmriprep.\n", + "\n", + "## BIDS filenames\n", + "\n", + "Ideally we would like to have the same pipeline for statistical analysis\n", + "whether our data was preprocessed with SPM or with fmriprep (for example).\n", + "\n", + "This is possible under the condition that the input files\n", + "for the statistical analysis are BIDS compliant:\n", + "meaning that they follow the typical pattern of BIDS files:\n", + "\n", + "- pseudo \"regular expression\" : `entity-label(_entity-label)+_suffix.extension`\n", + "\n", + "\n", + "- `entity`, `label`, `suffix`, `extension` are alphanumeric only (no special character): `([a-zA-Z0-9])+`\n", + " - suffixes can be: `T1w` or `bold` but not `T1w_skullstripped` (no underscore allowed)\n", + "\n", + "\n", + "- entity and label are separated by a dash:\n", + " `entity-label --> ([a-zA-Z0-9])+-([a-zA-Z0-9])+`\n", + " - you can have: `sub-01` but not `sub-01-blind`\n", + "\n", + "\n", + "- entity-label pairs are separated by an underscore:\n", + " `entity-label(_entity-label)+ --> ([a-zA-Z0-9])+-([a-zA-Z0-9])+(_([a-zA-Z0-9])+-([a-zA-Z0-9])+)+`\n", + "\n", + "\n", + "- **prefixes are not a thing in official BIDS names**\n", + "\n", + "BIDS has a number of officially recognised entities \n", + "(`sub`, `ses`, `task`...) that must come in a specific order for each data type.\n", + "\n", + "https://bids-specification.readthedocs.io/en/stable/99-appendices/04-entity-table.html\n", + "\n", + "BIDS derivatives adds a few more entities (`desc`, `space`, `res`...)\n", + "and suffixes (`pseg`, `dseg`, `mask`...)\n", + "that can be used to name and describe preprocessed data.\n", + "\n", + "\n", + "(C) Copyright 2022 Remi Gau" + ] + }, + { + "cell_type": "markdown", + "id": "d6eeb784", + "metadata": {}, + "source": [ + "The toolbox BIDS Matlab has some function to help you create bids valid names." + ] + }, + { + "cell_type": "markdown", + "id": "cf83233d", + "metadata": {}, + "source": [ + "## Note: octave notebook\n", + "\n", + "If you are running in an octave notebook.\n", + "\n", + "### Graphic output\n", + "\n", + "When using on Binder some of the SPM graphic output will not be generated, \n", + "as SPM takes this environment as being command line only. \n", + "\n", + "### Running the demo locally\n", + "\n", + "**If you are running this notebook locally AND if SPM is not the in Octave path**\n", + "\n", + "Run the following cell with the appropriate path for your computer.\n", + "\n", + "**Note:** \n", + "SPM will need to be compiled to work for Octave \n", + "for some parts of this demo to work." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e212e022", + "metadata": {}, + "outputs": [], + "source": [ + "% addpath('/home/remi/matlab/SPM/spm12');" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "efeae953", + "metadata": {}, + "outputs": [], + "source": [ + "this_dir = fileparts(mfilename('fullpath'));\n", + "\n", + "addpath(fullfile(this_dir, '..', '..'));\n", + "\n", + "bidspm();" + ] + }, { - "text": "GNU Octave", - "url": "https://www.gnu.org/software/octave/support.html" + "cell_type": "code", + "execution_count": null, + "id": "61d66ea6", + "metadata": {}, + "outputs": [], + "source": [ + "file_spec = struct('entities', struct('run', '01', ...\n", + " 'sub', '01', ...\n", + " 'task', 'visMotionLocalizer'), ...\n", + " 'suffix', 'bold', ...\n", + " 'ext', '.nii');\n", + "\n", + "bidsFile = bids.File(file_spec)\n", + "bidsFile.filename" + ] }, { - "text": "Octave Kernel", - "url": "https://github.com/Calysto/octave_kernel" + "cell_type": "markdown", + "id": "c968b79a", + "metadata": {}, + "source": [ + "If not enough information is provided, BIDS matlab should hopefully help you figure out what is missing." + ] }, { - "text": "MetaKernel Magics", - "url": "https://metakernel.readthedocs.io/en/latest/source/README.html" + "cell_type": "code", + "execution_count": null, + "id": "c5b24443", + "metadata": {}, + "outputs": [], + "source": [ + "file_spec = struct('entities', struct('run', '01', ...\n", + " 'sub', '01', ...\n", + " 'task', 'visMotionLocalizer'), ...\n", + " 'suffix', 'events', ...\n", + " 'ext', '.tsv');\n", + " \n", + "bidsFile = bids.File(file_spec)\n", + "bidsFile.filename" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "80e96806", + "metadata": {}, + "outputs": [], + "source": [ + "file_spec.modality = 'func';\n", + "bidsFile = bids.File(file_spec)\n", + "bidsFile.filename" + ] + }, + { + "cell_type": "markdown", + "id": "16feaf02", + "metadata": {}, + "source": [ + "Entities must have a specific order to be BIDS valid.\n", + "You can ignore those rules by not using the bids schema." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b69c412f", + "metadata": {}, + "outputs": [], + "source": [ + "file_spec = struct('entities', struct('run', '01', ...\n", + " 'sub', '01', ...\n", + " 'task', 'visMotionLocalizer'), ...\n", + " 'suffix', 'bold', ...\n", + " 'ext', '.nii', ...\n", + " 'use_schema', false);\n", + "\n", + "bidsFile = bids.File(file_spec)\n", + "bidsFile.filename" + ] + }, + { + "cell_type": "markdown", + "id": "8200da07", + "metadata": { + "tags": [] + }, + "source": [ + "## Typical SPM filenames\n", + "\n", + "SPM typically adds prefixes to filenames and concatenates them.\n", + "\n", + "- `r` for realigned or resliced\n", + "- `w` for warped (often means normalized in MNI space)\n", + "- `a` for slice time corrected images\n", + "- `u` for unwarped\n", + "- `s` for smoothed\n", + "- `c1` for grey matter tissue probability maps\n", + "- ..." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c5501a62", + "metadata": {}, + "outputs": [], + "source": [ + "% typical gray matter probabilistic segmentation\n", + "file_spec = struct('entities', struct('sub', '01'), ...\n", + " 'suffix', 'T1w', ...\n", + " 'ext', '.nii', ...\n", + " 'prefix', 'c1');\n", + "\n", + "bidsFile = bids.File(file_spec)\n", + "bidsFile.filename\n", + "\n", + "% typical preprocessed data in native space\n", + "file_spec = struct('entities', struct('run', '01', ...\n", + " 'sub', '01', ...\n", + " 'task', 'visMotionLocalizer'), ...\n", + " 'suffix', 'bold', ...\n", + " 'ext', '.nii', ...\n", + " 'prefix', 'ua');\n", + "\n", + "bidsFile = bids.File(file_spec)\n", + "bidsFile.filename\n", + "\n", + "% typical smoothed preprocessed data in MNI space\n", + "file_spec = struct('entities', struct('run', '01', ...\n", + " 'sub', '01', ...\n", + " 'task', 'visMotionLocalizer'), ...\n", + " 'suffix', 'bold', ...\n", + " 'ext', '.nii', ...\n", + " 'prefix', 'swua');\n", + "\n", + "bidsFile = bids.File(file_spec)\n", + "bidsFile.filename" + ] + }, + { + "cell_type": "markdown", + "id": "e959dead", + "metadata": {}, + "source": [ + "## BIDS derivatives filenames\n", + "But those SPM files are not BIDS valid because official valid BIDS files don't have prefixes.\n", + "\n", + "So SPM output must be renamed to be able to create BIDS valid output datasets." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "46bbae6d", + "metadata": {}, + "outputs": [], + "source": [ + "% space: can specify if this image is in MNI space or individual space\n", + "% desc: description can give more info about what is this file about: \n", + "% \"preproc\" --> \"preprocessed\"\n", + "file_spec = struct('entities', struct('sub', '01', ...\n", + " 'run', '01', ...\n", + " 'task', 'visMotionLocalizer', ...\n", + " 'space', 'MNI', ...\n", + " 'desc', 'preproc'), ...\n", + " 'suffix', 'bold', ...\n", + " 'ext', '.nii');\n", + "\n", + "bidsFile = bids.File(file_spec)\n", + "bidsFile.filename" + ] + }, + { + "cell_type": "markdown", + "id": "ed26d428", + "metadata": {}, + "source": [ + "It can be a pain to create the right map \n", + "between a specific SPM type of output and \"the right\" BIDS equivalent.\n", + "\n", + "So easier to use [the CPP `spm_2_bids` library](https://github.com/cpp-lln-lab/spm_2_bids)\n", + "which will also try to use the \"proper\" MNI space name \n", + "(`IXI594Sapce` is the one used by most of SPM)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "35ca15c4", + "metadata": {}, + "outputs": [], + "source": [ + "input_name = 'wc1sub-01_T1w.nii';\n", + "output_name = spm_2_bids(input_name)\n", + "\n", + "input_name = 'uasub-01_task-visMotionLocalizer_run-01_bold.nii';\n", + "output_name = spm_2_bids(input_name)\n", + "\n", + "input_name = 'wuasub-01_task-visMotionLocalizer_run-01_bold.nii';\n", + "output_name = spm_2_bids(input_name)" + ] + }, + { + "cell_type": "markdown", + "id": "df5b40b4", + "metadata": {}, + "source": [ + "spm_2_bids contains a certain list of default mapping to use\n", + "for renaming but you can also add some extra or modify the defaults.\n", + "\n", + "bidspm comes with its own preset `spm_2_bids` renaming map." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "4b556407", + "metadata": {}, + "outputs": [], + "source": [ + "opt = checkOptions(struct());\n", + "opt = set_spm_2_bids_defaults(opt);\n", + "\n", + "input_name = 'wc1sub-01_T1w.nii';\n", + "output_name = spm_2_bids(input_name, opt.spm_2_bids)\n", + "\n", + "input_name = 'uasub-01_task-visMotionLocalizer_run-01_bold.nii';\n", + "output_name = spm_2_bids(input_name, opt.spm_2_bids)\n", + "\n", + "input_name = 'wuasub-01_task-visMotionLocalizer_run-01_bold.nii';\n", + "output_name = spm_2_bids(input_name, opt.spm_2_bids)\n", + "\n", + "opt.fwhm.func = 6;\n", + "input_name = 'swuasub-01_task-visMotionLocalizer_run-01_bold.nii';\n", + "output_name = spm_2_bids(input_name, opt.spm_2_bids)" + ] + }, + { + "cell_type": "markdown", + "id": "631f25d0", + "metadata": {}, + "source": [ + "### `bidsRename`\n", + "\n", + "The `bidsRename` workflow uses this to rename all \"SPM files\" at the end of each step.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "642b1bb8", + "metadata": {}, + "outputs": [], + "source": [ + "demo_dir = fullfile(pwd, '..', 'MoAE');\n", + "\n", + "opt.dir.derivatives = fullfile(demo_dir, 'outputs', 'derivatives');\n", + "opt.dir.preproc = fullfile(opt.dir.derivatives, 'bidspm-preproc');\n", + "\n", + "opt = checkOptions(opt);\n", + "\n", + "bidsRename(opt);" + ] + }, + { + "cell_type": "markdown", + "id": "d7b580ec", + "metadata": {}, + "source": [ + "Example of the end of spatial preprocessing\n", + "\n", + "```matlab\n", + " if ~opt.realign.useUnwarp\n", + " opt.spm_2_bids = opt.spm_2_bids.add_mapping('prefix', opt.spm_2_bids.realign, ...\n", + " 'name_spec', opt.spm_2_bids.cfg.preproc);\n", + "\n", + " opt.spm_2_bids = opt.spm_2_bids.add_mapping('prefix', [opt.spm_2_bids.realign 'mean'], ...\n", + " 'name_spec', opt.spm_2_bids.cfg.preproc);\n", + " opt.spm_2_bids = opt.spm_2_bids.flatten_mapping();\n", + " end\n", + "\n", + " bidsRename(opt);\n", + "``` " + ] } - ], - "mimetype": "text/x-octave", - "name": "octave", - "version": "6.4.0" - } - }, - "nbformat": 4, - "nbformat_minor": 5 + ], + "metadata": { + "kernelspec": { + "display_name": "Octave", + "language": "octave", + "name": "octave" + }, + "language_info": { + "file_extension": ".m", + "help_links": [ + { + "text": "GNU Octave", + "url": "https://www.gnu.org/software/octave/support.html" + }, + { + "text": "Octave Kernel", + "url": "https://github.com/Calysto/octave_kernel" + }, + { + "text": "MetaKernel Magics", + "url": "https://metakernel.readthedocs.io/en/latest/source/README.html" + } + ], + "mimetype": "text/x-octave", + "name": "octave", + "version": "6.4.0" + } + }, + "nbformat": 4, + "nbformat_minor": 5 }