
<!-- README.md is generated from README.Rmd. Please edit that file -->

# fMRIscrub

<!-- badges: start -->

[![CRAN
status](https://www.r-pkg.org/badges/version/fMRIscrub)](https://cran.r-project.org/package=fMRIscrub)
[![R-CMD-check](https://github.com/mandymejia/fMRIscrub/workflows/R-CMD-check/badge.svg)](https://github.com/mandymejia/fMRIscrub/actions)
[![Codecov test
coverage](https://codecov.io/gh/mandymejia/fMRIscrub/branch/master/graph/badge.svg)](https://app.codecov.io/gh/mandymejia/fMRIscrub?branch=master)
<!-- badges: end -->

`fMRIscrub` is a collection of routines for data-driven scrubbing
(projection scrubbing and DVARS), motion scrubbing, and other fMRI
denoising strategies such as anatomical CompCor, detrending, and
nuisance regression. Projection scrubbing is also applicable to other
outlier detection tasks involving high-dimensional data.

This package builds off of
[`fMRItools`](https://github.com/mandymejia/fMRItools), which collects
common functions for handling fMRI data, and
[`ciftiTools`](https://github.com/mandymejia/ciftiTools) to support
working with the CIFTI format. Also check out our new package,
[`rrobot`](https://github.com/mandymejia/rrobot), for methods made for
robust outlier detection.

## Installation

You can install the development version of fMRIscrub from CRAN with:

``` r
install.packages("fMRIscrub")
```

## Quick start guide

``` r
s_Dat1 <- IDvols(Dat1)
plot(s_Dat1)
Dat1_cleaned <- Dat1[!s_Dat1$outlier_flag,]
```

## Data

Two scans from the [ABIDE
I](http://fcon_1000.projects.nitrc.org/indi/abide/abide_I.html) are
included in `fMRIscrub`: `Dat1` has many artifacts whereas `Dat2` has
few visible artifacts. Both are vectorized sagittal slices stored as
numeric matrices. They are loaded into the environment upon loading the
package.

We acknowledge the corresponding funding for the ABIDE I data:

> Primary support for the work by Adriana Di Martino was provided by the
> (NIMH K23MH087770) and the Leon Levy Foundation. Primary support for
> the work by Michael P. Milham and the INDI team was provided by gifts
> from Joseph P. Healy and the Stavros Niarchos Foundation to the Child
> Mind Institute, as well as by an NIMH award to MPM ( NIMH
> R03MH096321).

## Vignette/Demo

See [this
link](https://github.com/mandymejia/fMRIscrub/blob/master/vignettes/projection_scrubbing.rmd)
to view the tutorial vignette.

## Citation

If using projection scrubbing, you can cite our 2023 paper [“Less is
more: balancing noise reduction and data retention in fMRI with
data-driven
scrubbing”](https://doi.org/10.1016/j.neuroimage.2023.119972). In the
Methods section there is also a description of how FD and DVARS are
calculated (section 2.2), and how scrubbing can be implemented in a
simultaneous nuisance regression framework (section 2.3.3).
