{"id":32394451,"url":"https://github.com/jfortin1/ravel","last_synced_at":"2026-02-23T12:04:07.429Z","repository":{"id":36202572,"uuid":"40506810","full_name":"Jfortin1/RAVEL","owner":"Jfortin1","description":"Intensity normalization of structural MRIs using RAVEL","archived":false,"fork":false,"pushed_at":"2023-09-07T16:13:24.000Z","size":1173,"stargazers_count":26,"open_issues_count":0,"forks_count":12,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-09-25T00:10:26.348Z","etag":null,"topics":["brain-imaging","image-normalization","image-preprocessing","image-processing","mri","normalization","ravel","smri","structural-mri"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jfortin1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-08-10T21:21:16.000Z","updated_at":"2024-03-04T08:58:19.000Z","dependencies_parsed_at":"2022-09-05T18:30:39.803Z","dependency_job_id":"ba05817f-fe0e-4e8d-beac-620af1b89b63","html_url":"https://github.com/Jfortin1/RAVEL","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Jfortin1/RAVEL","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jfortin1%2FRAVEL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jfortin1%2FRAVEL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jfortin1%2FRAVEL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jfortin1%2FRAVEL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jfortin1","download_url":"https://codeload.github.com/Jfortin1/RAVEL/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jfortin1%2FRAVEL/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280911340,"owners_count":26412209,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-25T02:00:06.499Z","response_time":81,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brain-imaging","image-normalization","image-preprocessing","image-processing","mri","normalization","ravel","smri","structural-mri"],"created_at":"2025-10-25T05:58:32.227Z","updated_at":"2025-10-25T05:59:50.025Z","avatar_url":"https://github.com/Jfortin1.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n# RAVEL \u003cimg src=\"sticker.png\" width = \"150\" align=\"right\" /\u003e\n\n\n\n### Intensity normalization methods for structural MRIs\n\n**Creator**: Jean-Philippe Fortin, \u003cfortin946@gmail.com\u003e\n\n**Authors**: Jean-Philippe Fortin, John Muschelli\n\n**License**:\nGPL-2\n\n##### Software status\n\n| Resource:   | Travis CI                                                                                                                                |\n| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- |\n| Platform:   | OSX                                                                                                                                      |\n| R CMD check | \u003ca href=\"https://travis-ci.org/Jfortin1/RAVEL\"\u003e\u003cimg src=\"https://travis-ci.org/Jfortin1/RAVEL.svg?branch=master\" alt=\"Build status\"\u003e\u003c/a\u003e |\n\n##### References\n\n| Method      | Citation                                                                                                                                                                                                                                                                                                                                                                                                 | Paper Link                                                                 |\n| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |\n| RAVEL       | Jean-Philippe Fortin, Elizabeth M Sweeney, John Muschelli, Ciprian M Crainiceanu, Russell T Shinohara, Alzheimer’s Disease Neuroimaging Initiative, et al. **Removing inter-subject technical variability in magnetic resonance imaging studies**. NeuroImage, 132:198–212, 2016.                                                                                                                        | [Link](http://www.sciencedirect.com/science/article/pii/S1053811916001452) |\n| WhiteStripe | Russell T Shinohara, Elizabeth M Sweeney, Jeff Goldsmith, Navid Shiee, Farrah J Mateen, Peter A Calabresi, Samson Jarso, Dzung L Pham, Daniel S Reich, Ciprian M Crainiceanu, Australian Imaging Biomarkers Lifestyle Flagship Study of Ageing, and Alzheimer’s Disease Neuroimaging Initiative. **Statistical normalization techniques for magnetic resonance imaging**. Neuroimage Clin, 6:9–19, 2014. | [Link](http://www.sciencedirect.com/science/article/pii/S221315821400117X) |\n\n## Table of content\n\n  - [1. Introduction](#id-section1)\n  - [2. Image preprocessing](#id-section2)\n  - [3. Intensity normalization and RAVEL correction](#id-section3)\n\n## 1\\. Introduction\n\nRAVEL is an R package that combines the preprocessing and statistical\nanalysis of magnetic resonance imaging (MRI) datasets within one\nframework. Users can start with raw images in the NIfTI format, and end\nup with a variety of statistical results associated with voxels and\nregions of interest (ROI) in the brain. RAVEL stands for *Removal of\nArtificial Voxel Effect by Linear regression*, the main preprocessing\nfunction of the package that allows an effective removal of between-scan\nunwanted variation. We have shown in [a recent\npaper](http://www.sciencedirect.com/science/article/pii/S1053811916001452)\nthat RAVEL improves significantly population-wide statistical inference.\nRAVEL is now part of the [Neuroconductor\nproject](https://neuroconductor.org/).\n\n### Installation\n\nThe following dependencies need to be installed first:\n\n```r\ninstall.packages(\"devtools\")\ndevtools::install_github(\"muschellij2/neurobase\")\ndevtools::install_github(\"muschellij2/WhiteStripe\")\n```\n\nRAVEL can be installed using the following command:\n\n``` r\ndevtools::install_github(\"jfortin1/RAVEL\")\n```\n\n## 2\\. Image preprocessing\n\nWe present a pre-normalization preprocessing pipeline implemented in the\nR software, from raw images to images ready for intensity normalization\nand statistical analysis. Once the images are preprocessed, users can\napply their favorite intensity normalization and the scan-effect\ncorrection tool RAVEL as presented in Section 1 above. We present a\npreprocessing pipeline that uses the R packages `ANTsR` and `fslr`.\nWhile we have chosen to use a specific template space (JHU-MNI-ss), a\nspecific registration (non-linear diffeomorphic registration) and a\nspecific tissue segmentation (FSL FAST), users can choose other\nalgorithms prior to intensity normalization and in order for RAVEL to\nwork. The only requirement is that the images are registered to the same\ntemplate space.\n\n### 2.1. Prelude\n\nTo preprocess the images, we use the packages `fslr` and `ANTsR`. The\npackage `fslr` is available on CRAN, and requires FSL to be installed on\nyour machine; see the [FSL\nwebsite](http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/) for installation. For\n`ANTsR`, we recommend to install the latest stable version available at\nthe ANTsR [GitHub page](https://github.com/stnava/ANTsR/releases/). The\nversion used for this vignette was `ANTsR_0.3.2.tgz`. For the template\nspace, we use the JHU-MNI-ss atlas (see Section 1.2) included in the\n`EveTemplate` package, available on GitHub at\n\u003chttps://github.com/Jfortin1/EveTemplate\u003e. For data examples, we use 4\nT1-w scans from the package `RAVELData` available on GitHub at\n\u003chttps://github.com/Jfortin1/RAVELData\u003e. Once the packages are properly\ninstalled, we are ready to start our preprocessing of T1-w images. We\nfirst load the packages into R:\n\n``` r\nlibrary(fslr)\nlibrary(ANTsR)\nlibrary(RAVELData)\nlibrary(EveTemplate)\nhave.fsl() # Should be TRUE if fsl is correctly installed\n```\n\nand let’s specify the path for the different files that we will need:\n\n``` r\n# JHU-MNI-ss template:\nlibrary(EveTemplate)\ntemplate_path \u003c- getEvePath(\"T1\")\n# JHU-MNI-ss template brain mask:\ntemplate_brain_mask_path \u003c- getEvePath(\"Brain_Mask\")\n# Example of T1-w MPRAGE image\nscan_path \u003c- system.file(package=\"RAVELData\", \"extdata/scan1.nii.gz\")\n```\n\n### 2.2. JHU-MNI-ss template (\\_EVE\\_ atlas)\n\n### 2.3. Registration to template\n\nTp perform a non-linear registration to the JHU-MNI-ss template, one can\nuse the diffeomorphism algorithm via the `ANTsR` package. Note that we\nperform the registration with the skulls on. Here is an example where we\nregister the scan1 from the `RAVELData` package to the JHU-MNI-ss\ntemplate:\n\n``` r\nlibrary(ANTsRCore)\nlibrary(ANTsR)\ntemplate    \u003c- antsImageRead(template_path, 3)\nscan \u003c- antsImageRead(scan_path,3)\noutprefix \u003c- gsub(\".nii.gz\",\"\",scan_path) # Prefix for the output files\noutput \u003c- antsRegistration(fixed = template, moving = scan, typeofTransform = \"SyN\",  outprefix = outprefix)\nscan_reg   \u003c- antsImageClone(output$warpedmovout) # Registered brain\n```\n\nThe object `scan_reg` contains the scan registed to the template. Note\nthat the object is in the `ANTsR` format. Since I prefer to work with\nthe `oro.nifti` package, which is compatible with `flsr`, I convert the\nobject to a `nifti` object using the function `ants2oro` as follows:\n\n``` r\n# devtools::install_github(\"muschellij2/extrantsr\")\n# or\n# source(\"https://neuroconductor.org/sites/default/files/neurocLite.R\")\n# neuro_install(\"extrantsr\")\nlibrary(extrantsr)\nscan_reg \u003c- extrantsr::ants2oro(scan_reg)\n```\n\nWe can save the registered brain in the NIfTi format using the\n`writeNIfTI` command:\n\n``` r\nwriteNIfTI(scan_reg, \"scan_reg\")\n```\n\nSince `scan_reg` is converted to a `nifti` object, we can use the\nfunction `ortho2` from the `fslr` package to visualize the scan:\n\n``` r\northo2(scan_reg, crosshairs=FALSE, mfrow=c(1,3), add.orient=FALSE)\n```\n\n### 2.4. Intensity inhomogeneity correction\n\nWe perform intensity inhomogeneity correction on the registered scan\nusing the N4 Correction from the `ANTsR` package:\n\n``` r\nscan_reg \u003c- extrantsr::oro2ants(scan_reg) # Convert to ANTsR object\nscan_reg_n4 \u003c- n4BiasFieldCorrection(scan_reg)\nscan_reg_n4 \u003c- extrantsr::ants2oro(scan_reg_n4) # Conversion to nifti object for further processing\n```\n\n### 2.5. Skull stripping\n\n``` r\ntemplate_brain_mask \u003c- readNIfTI(template_brain_mask_path, reorient=FALSE)\nscan_reg_n4_brain \u003c- niftiarr(scan_reg_n4, scan_reg_n4*template_brain_mask)\northo2(scan_reg_n4_brain, crosshairs=FALSE, mfrow=c(1,3), add.orient=FALSE)\n```\n\n### 2.6. Tissue Segmentation\n\nThere are different tissue segmentation algorithms available in R. My\nfavorite is the FSL FAST segmentation via the\n[`fslr`](https://cran.r-project.org/web/packages/fslr/index.html)\npackage. Let’s produce the tissue segmentation for the\n`scan_reg_n4_brain` scan\nabove:\n\n``` r\northo2(scan_reg_n4_brain, crosshairs=FALSE, mfrow=c(1,3), add.orient=FALSE, ylim=c(0,400))\n```\n\nThe last line of code produces via the `ortho2` function from the `fslr`\npackage the following visualization of the template:\n\n\u003cp align=\"center\"\u003e\n\n\u003cimg src=\"images/template.png\" width=\"600\"/\u003e\n\n\u003c/p\u003e\n\nWe perform a 3-class tissue segmentation on the T1-w image with the FAST\nsegmentation\nalgorithm:\n\n``` r\nscan_reg_n4_brain_seg \u003c- fast(scan_reg_n4_brain, verbose=FALSE, opts=\"-t 1 -n 3\") \northo2(scan_reg_n4_brain_seg, crosshairs=FALSE, mfrow=c(1,3), add.orient=FALSE)\n```\n\n\u003cp align=\"center\"\u003e\n\n\u003cimg src=\"images/seg.png\" width=\"600\"/\u003e\n\n\u003c/p\u003e\n\nThe object `scan_reg_n4_brain_seg` is an image that contains the\nsegmentation labels `0,1,2` and `3` referring to Background, CSF, GM and\nWM voxels respectively.\n\n### 2.7. Creation of a tissue mask\n\nSuppose we want to create a mask for CSF.\n\n``` r\nscan_reg_n4_brain_csf_mask \u003c- scan_reg_n4_brain_seg\nscan_reg_n4_brain_csf_mask[scan_reg_n4_brain_csf_mask!=1] \u003c- 0\northo2(scan_reg_n4_brain_csf_mask, crosshairs=FALSE, mfrow=c(1,3), add.orient=FALSE)\n```\n\nWe use the fact that the file `scan_reg_n4_brain_seg` is equal to 1 for\nCSF, 2 for GM and 3 for WM. For instance, a WM mask could be created as\nfollows:\n\n``` r\nscan_reg_n4_brain_wm_mask \u003c- scan_reg_n4_brain_seg\nscan_reg_n4_brain_wm_mask[scan_reg_n4_brain_wm_mask!=3] \u003c- 0\northo2(scan_reg_n4_brain_wm_mask, crosshairs=FALSE, mfrow=c(1,3), add.orient=FALSE)\n```\n\n## 3\\. Intensity normalization and RAVEL correction\n\nSince MRI intensities are acquired in arbitrary units, image intensities\nare not comparable across scans, between subjects and across sites.\nIntensity normalization (or intensity standardization) is paramount\nbefore performing between-subject intensity comparisons. The `RAVEL`\npackage includes the popular histogram matching normalization\n(`normalizeHM`) as well as the White Stripe normalization\n(`normalizeWS`); see the table below for the reference papers. Once the\nimages intensities are normalized, the RAVEL correction tool can be\napplied using the function `normalizeRAVEL` to remove additional\nunwanted variation using a control region. Because we have found that\nthe combination White Stripe + RAVEL was best at removing unwanted\nvariation, the function `normalizeRAVEL` performs White Stripe\nnormalization by default prior to the RAVEL correction.\n\nNote: registration is also called *spatial normalization* which is\nunrelated to *intensity\nnormalization*.\n\n##### Available methods\n\n| Function         | Method             | Modalities supported at the moment | Paper Link                                                                 |\n| ---------------- | ------------------ | ---------------------------------- | -------------------------------------------------------------------------- |\n| `normalizeRaw`   | No normalization   | T1, T2, FLAIR, PD                  |                                                                            |\n| `normalizeRAVEL` | RAVEL              | T1, T2, FLAIR                      | [Link](http://www.sciencedirect.com/science/article/pii/S1053811916001452) |\n| `normalizeWS`    | White Stripe       | T1, T2, FLAIR                      | [Link](http://www.sciencedirect.com/science/article/pii/S221315821400117X) |\n| `normalizeHM`    | Histogram Matching | T1, T2, FLAIR, PD                  | [Link](http://www.ncbi.nlm.nih.gov/pubmed/10571928)                        |\n| `normalizeZScore`| Z-score transformation  | T1, T2, FLAIR, PD                  |                                                                            |\n\nBriefly, each function takes as input a list of NIfTI file paths\nspecifying the images to be normalized, and return a matrix of\nnormalized intensities where rows are voxels and columns are scans. We\nnote that the input files must be the files associated with preprocessed\nimages registered to a common template. The different functions are\ndescribed below.\n\n### 3.1 No normalization\n\nThe function `normalizeRaw` takes as input the preprocessed and\nregistered images, and create a matrix of voxel intensities without\nintensity normalization. For conventional MRI images, we recommend to\napply an intensity normalization to the images (see `normalizeWS` or\n`normalizeRAVEL`). The main purpose of the function `normalizeRaw` is\nfor exploration data analysis (EDA), methods development and methods\ncomparison.\n\n| Argument       | Description                                                                                                                               | Default |\n| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------- |\n| `input.files`  | `vector` or `list` of the paths for the input NIfTI image files to be normalized                                                          |         |\n| `output.files` | Optionnal `vector` or `list` of the paths for the output images. By default, will be the `input.files` with \"\\_RAW\" appended at the end.  | `NULL`  |\n| `brain.mask`   | NIfTI image path for the binary brain mask. Must have value `1` for the brain and `0` otherwise                                           |         |\n| `returnMatrix` | Should the matrix of normalized images be returned? Rows correspond to voxels specified by `brain.mask`, and columns correspond to scans. | `TRUE`  |\n| `writeToDisk`  | Should the normalized images be saved to the disk as NIfTI files?                                                                         | `FALSE` |\n| `verbose`      | Should the function be verbose?                                                                                                           | `TRUE`  |\n\n### 3.2 White Stripe normalization\n\nThe function `normalizeWS` takes as input the preprocessed and\nregistered images, applies the White Stripe normalization algorithm to\neach image separately via the `WhiteStripe` R package, and creates a\nmatrix of normalized voxel intensities. Note that the White Stripe\nnormalization is also included as a first step in the RAVEL algorithm\nimplemented in the `normalizeRAVEL`\nfunction.\n\n| Argument           | Description                                                                                                                               | Default |\n| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------- |\n| `input.files`      | `vector` or `list` of the paths for the input NIfTI image files to be normalized                                                          |         |\n| `output.files`     | Optionnal `vector` or `list` of the paths for the output images. By default, will be the `input.files` with \"\\_WS\" appended at the end.   | `NULL`  |\n| `brain.mask`       | NIfTI image path for the binary brain mask. Must have value `1` for the brain and `0` otherwise                                           |         |\n| `WhiteStripe_Type` | What is the type of images to be normalized? Must be one of “T1”, “T2” and “FLAIR”.                                                       | `T1`    |\n| `returnMatrix`     | Should the matrix of normalized images be returned? Rows correspond to voxels specified by `brain.mask`, and columns correspond to scans. | `TRUE`  |\n| `writeToDisk`      | Should the normalized images be saved to the disk as NIfTI files?                                                                         | `FALSE` |\n| `verbose`          | Should the function be verbose?                                                                                                           | `TRUE`  |\n\n### 3.3 Histogram matching normalization\n\nThe function `normalizeHM` takes as input the preprocessed and\nregistered images, applies the Histogram matching normalization algorithm to\neach image separately, and creates a\nmatrix of normalized voxel intensities.\n\n| Argument           | Description                                                                                                                               | Default |\n| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------- |\n| `input.files`      | `vector` or `list` of the paths for the input NIfTI image files to be normalized                                                          |         |\n| `output.files`     | Optionnal `vector` or `list` of the paths for the output images. By default, will be the `input.files` with \"\\_WS\" appended at the end.   | `NULL`  |\n| `brain.mask`       | NIfTI image path for the binary brain mask. Must have value `1` for the brain and `0` otherwise                                           |         |\n| `type` | What is the type of images to be normalized? Must be one of “T1”, “T2”, \"PD\", and “FLAIR”.                                                       | `T1`    |\n| `returnMatrix`     | Should the matrix of normalized images be returned? Rows correspond to voxels specified by `brain.mask`, and columns correspond to scans. | `TRUE`  |\n| `writeToDisk`      | Should the normalized images be saved to the disk as NIfTI files?                                                                         | `FALSE` |\n| `verbose`          | Should the function be verbose?                                                                                                           | `TRUE`  |\n\n\n### 3.4 Z-score transformation (whole-brain)\n\nThe function `normalizeZScore` takes as input the preprocessed and\nregistered images, applies a whole-brain z-score transformation to\neach image separately, and creates a\nmatrix of normalized voxel intensities.\n\n| Argument           | Description                                                                                                                               | Default |\n| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------- |\n| `input.files`      | `vector` or `list` of the paths for the input NIfTI image files to be normalized                                                          |         |\n| `output.files`     | Optionnal `vector` or `list` of the paths for the output images. By default, will be the `input.files` with \"\\_WS\" appended at the end.   | `NULL`  |\n| `brain.mask`       | NIfTI image path for the binary brain mask. Must have value `1` for the brain and `0` otherwise                                           |         |\n| `type` | What is the type of images to be normalized? Must be one of “T1”, “T2”, \"PD\", and “FLAIR”.                                                       | `T1`    |\n| `returnMatrix`     | Should the matrix of normalized images be returned? Rows correspond to voxels specified by `brain.mask`, and columns correspond to scans. | `TRUE`  |\n| `writeToDisk`      | Should the normalized images be saved to the disk as NIfTI files?                                                                         | `FALSE` |\n| `verbose`          | Should the function be verbose?                                                                                                           | `TRUE`  |\n\n\n\n### 3.5 RAVEL normalization\n\nThe function `normalizeRAVEL` takes as input the preprocessed and\nregistered images, and a control region mask, and applies the RAVEL\ncorrection method to create a matrix of normalized voxel intensities.\nThe White Stripe normalization is included by default as a first step in\nthe RAVEL algorithm. The next section explains how to create a control\nregion\nmask.\n\n| Argument           | Description                                                                                                                                                                                       | Default |\n| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |\n| `input.files`      | `vector` or `list` of the paths for the input NIfTI image files to be normalized                                                                                                                  |         |\n| `output.files`     | Optionnal `vector` or `list` of the paths for the output images. By default, will be the `input.files` with \"\\_RAVEL\" appended at the end.                                                        | `NULL`  |\n| `brain.mask`       | NIfTI image path for the binary brain mask. Must have value `1` for the brain and `0` otherwise                                                                                                   |         |\n| `control.mask`     | NIfTI image path for the binary control region mask. Must have value `1` for the control region and `0` otherwise. See the helper function `mask_intersect` for the creation of a `control.mask`. |         |\n| `mod`     | Model matrix for outcome of interest and other covariates  |    `NULL`     |\n| `WhiteStripe`      | Should White Stripe normalization be performed before RAVEL?                                                                                                                                      | `TRUE`  |\n| `WhiteStripe_Type` | If `WhiteStripe` is `TRUE`, what is the type of images to be normalized? Must be one of “T1”, “T2” and “FLAIR”.                                                                                   | `T1`    |\n| `k`                | Integer specifying the number of principal components to be included in the RAVEL correction.                                                                                                     | `1`     |\n| `returnMatrix`     | Should the matrix of normalized images be returned? Rows correspond to voxels specified by `brain.mask`, and columns correspond to scans.                                                         | `TRUE`  |\n| `writeToDisk`      | Should the normalized images be saved to the disk as NIfTI files?                                                                                                                                 | `FALSE` |\n| `verbose`          | Should the function be verbose?                                                                                                                                                                   | `TRUE`  |\n\n### 3.6 Creation of a control region for RAVEL\n\nRAVEL uses a control region of the brain to infer unwanted variation\nacross subjects. The control region is made of voxels known to be\n**not** associated with the phenotype of interest. For instance, it is\nknown that CSF intensities on T1-w images are not associated with the\nprogression of AD. The control region must be specified in the argument\n`control.mask` of the function `normalizeRAVEL` as a path to a NIfTI\nfile storing a binary mask. In the case of a CSF control region, one way\nto create such a binary mask is to create a CSF binary mask for each\nscan first, and then to take the intersection of all those binary masks. This\ncan be done with the function `maskIntersect` in `RAVEL`. The function takes as\ninput a list of binary masks (either `nifti` objects or a list of NIfTI\nfile paths), and will output the intersection of all the binary masks.\nBy default, the function will save the intersection mask to the disk as\na NIfTI file, as specified by\n`output.file`:\n\nExample:\n\n``` r\ndir   \u003c- file.path(find.package(\"RAVELData\"), \"extdata\")\nmasks \u003c- list.files(dir, full.names=TRUE, pattern=\"*mask*.nii*\")\nintersect_mask  \u003c- maskIntersect(masks, output.file=tempfile())\n```\n\nWhen the number of subjects is large, the intersection mask may be\nempty, as a consequence of anatomical variation between subjects. As a\nsolution, the function `maskIntersect` has the option to create an\nintersection mask that is less stringent by requiring the control region\nto be present in only a given percentage of the subjects, using the\noption `prob`. By default, `prob` is equal to 1, meaning 100% of the\nsubjects has the final voxels labelled as CSF. For instance, to require\nthat the final control region is shared for at least 90% of the\nsubjects, one would\ntype\n\n``` r\nintersect_mask  \u003c- maskIntersect(masks, output.file=tempfile(), prob=0.9)\n```\n\nFor studies with a small number of subjects, the opposite problem may\narise: too many voxels labelled as CSF, close to the skull, might be\nretained in the final intersection mask. Mask erosion, for instance\nusing [fslr](https://github.com/muschellij2/fslr), may be performed to\nremove such voxels and refine the control mask.\n\n### 3.7 Controlling for biological covariates in RAVEL\n\nIn removing the unwanted variation estimated using control voxels, it is possible to preserve biological variation by specifying biological covariates in the `normalizeRAVEL` function, similar to ComBat harmonization. \n\nFor instance, suppose we want to normalize intensities across participants using CSF, and also want to make sure that we don't remove variation in intensities associated with age. We first need to build a model matrix for the biological covariates (here age):\n\n``` r\nage \u003c- c(70,62,43,76) #Simulated age\ngender \u003c- c(\"M\", \"M\", \"F\", \"F\")\nmod \u003c- model.matrix(~age+gender)\n```\n\nNote that while the model matrix has an intercept column, this will be automatically handled internally by the ```normalizeRAVEL``` function. To run RAVEL while adjusting for age and gender, we include ```mod``` as an argument as follows:\n\n``` r\nY.ravel.mod \u003c- normalizeRAVEL(input.files=input.files,\n\tcontrol.mask=control.mask,\n\tbrain.mask=brain.mask,\n\tk=1, \n\tmod=mod,\n\treturnMatrix=TRUE,\n\tWhiteStripe=FALSE\n)\n```\n\nLogo from: \u003chttps://openclipart.org/detail/14743/violin-bow\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjfortin1%2Fravel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjfortin1%2Fravel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjfortin1%2Fravel/lists"}