neuroim2/README.Rmd at master · bbuchsbaum/neuroim2 · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
---
title: "neuroim2"
output:
  md_document:
    variant: gfm
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, message = FALSE, warning = FALSE)
```

# neuroim2
<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/neuroim2)](https://cran.r-project.org/package=neuroim2)
[![CRAN downloads](https://cranlogs.r-pkg.org/badges/grand-total/neuroim2)](https://cran.r-project.org/package=neuroim2)
[![R-CMD-check](https://github.com/bbuchsbaum/neuroim2/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/bbuchsbaum/neuroim2/actions/workflows/R-CMD-check.yaml)
[![pkgdown](https://github.com/bbuchsbaum/neuroim2/actions/workflows/pkgdown.yaml/badge.svg)](https://bbuchsbaum.github.io/neuroim2/)
[![codecov](https://codecov.io/gh/bbuchsbaum/neuroim2/branch/master/graph/badge.svg)](https://app.codecov.io/gh/bbuchsbaum/neuroim2)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
<!-- badges: end -->

Data structures and I/O for volumetric brain imaging with a focus on fMRI. This is the successor to [`neuroim`](https://github.com/bbuchsbaum/neuroim) with improved S4 classes, sparse/dense 3D–4D representations, and fast resampling/filtering.

**Website:** https://bbuchsbaum.github.io/neuroim2/
**CRAN:** https://cran.r-project.org/package=neuroim2

## Key Features

- **NIfTI / AFNI support** — read and write `.nii`, `.nii.gz`, and AFNI `.BRIK`/`.HEAD` files
- **S4 class hierarchy** — `NeuroVol` (3D volumes) and `NeuroVec` (4D time-series) with dense, sparse, memory-mapped, and clustered variants
- **Coordinate systems** — full affine-aware transforms between voxel, grid, and world coordinates
- **Searchlights & ROIs** — spherical, cuboid, and random searchlight iterators plus flexible ROI construction
- **Spatial filtering** — Gaussian blur, guided filter, bilateral filter, and connected-component labelling
- **Resampling** — volume-to-volume resampling with configurable interpolation
- **Visualization** — slice montages, orthographic views, and overlay plotting via ggplot2

## Installation

### CRAN

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

### R-universe (daily builds)

```r
install.packages("neuroim2",
  repos = c("https://bbuchsbaum.r-universe.dev", "https://cloud.r-project.org"))
```

### Development version (GitHub)

```r
# install.packages("remotes")
remotes::install_github("bbuchsbaum/neuroim2")
```

## Usage

Read a NIFTI image and perform simple operations:

```{r}
library(neuroim2)
fname <- system.file("extdata", "global_mask_v4.nii", package="neuroim2")
vol <- read_vol(fname)

v1 <- vol[1,1,1]
vol2 <- vol + vol
all(vol == (vol2 - vol))
```

Create a 4D image from volumes:

```{r}
vec <- vec_from_vols(list(vol, vol, vol2))
series1 <- vec[1,1,1,]
length(series1)
```

## Vignettes

Browse the full set of [articles](https://bbuchsbaum.github.io/neuroim2/articles/index.html) on the pkgdown site:

| Getting Started | Analysis Workflows | Advanced |
|---|---|---|
| [Overview](https://bbuchsbaum.github.io/neuroim2/articles/Overview.html) | [Analysis Workflows](https://bbuchsbaum.github.io/neuroim2/articles/AnalysisWorkflows.html) | [Image Volumes](https://bbuchsbaum.github.io/neuroim2/articles/ImageVolumes.html) |
| [Choosing Backends](https://bbuchsbaum.github.io/neuroim2/articles/ChoosingBackends.html) | [Slice Visualization](https://bbuchsbaum.github.io/neuroim2/articles/slice-visualization.html) | [NeuroVector](https://bbuchsbaum.github.io/neuroim2/articles/NeuroVector.html) |
| [Coordinate Systems](https://bbuchsbaum.github.io/neuroim2/articles/coordinate-systems.html) | [Cookbook](https://bbuchsbaum.github.io/neuroim2/articles/Cookbook.html) | [Regions of Interest](https://bbuchsbaum.github.io/neuroim2/articles/regionOfInterest.html) |
| [Volumes & Vectors](https://bbuchsbaum.github.io/neuroim2/articles/VolumesAndVectors.html) | [Smoothing](https://bbuchsbaum.github.io/neuroim2/articles/Smoothing.html) | [Clustered NeuroVec](https://bbuchsbaum.github.io/neuroim2/articles/clustered-neurovec.html) |
| [Resampling](https://bbuchsbaum.github.io/neuroim2/articles/Resampling.html) | | [Pipelines](https://bbuchsbaum.github.io/neuroim2/articles/pipelines.html) |