---
title: "Read imaging data"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Read imaging data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE, echo = FALSE, results='hide'}
if(identical(Sys.getenv("IEEGIO_PKGDOWN", unset = ""), "")) {
  knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    eval = FALSE
  )
} else {
  options("rgl.useNULL" = TRUE)
  library(ieegio)
  library(rgl)
  knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>"
  )
  rgl::setupKnitr(autoprint = FALSE)
  cache_dir <- tools::R_user_dir("ieegio", "cache")
  dir.create(cache_dir, showWarnings = FALSE, recursive = TRUE)
  cache_dir <- normalizePath(cache_dir, mustWork = TRUE)
  options("ieegio.extract_path", cache_dir)
}

```

`ieegio` supports reading from and writing to multiple imaging formats:

* Volume: `NIfTI` & `FreeSurfer MGH/MGZ`
* Surface: `GIfTI` & `FreeSurfer` geometry, annotation, curvature/measurement, `w` format
* Streamlines: `TRK`, `TCK`, `TT` (read-only), `VTK`, `VTP`, ...

To start, please load `ieegio`. This vignette uses sample data which requires extra download.


```{r sample}
library(ieegio)

# volume file
nifti_file <- ieegio_sample_data("brain.demosubject.nii.gz")

# geometry
geom_file <- ieegio_sample_data(
  "gifti/icosahedron3d/geometry.gii")

# measurements
shape_file <- ieegio_sample_data(
  "gifti/icosahedron3d/rand.gii"
)

# time series
ts_file <- ieegio_sample_data(
  "gifti/icosahedron3d/ts.gii")

# streamlines
trk_file <- ieegio_sample_data(
  "streamlines/CNVII_R.trk")

tck_file <- ieegio_sample_data(
  "streamlines/CNVII_R.tck")

tt_file <- ieegio_sample_data(
  "streamlines/CNVII_R.tt")
```


## Volume files

`ieegio::read_volume` and `ieegio::write_volume` provides high-level interfaces for reading and writing volume data such as `MRI`, `CT`. `fMRI`, etc.

Each volume data (`NIfTI`, `MGH`, ...) contains a `header`, a `data`, and a `transforms` list.

```{r read_volume}
volume <- read_volume(nifti_file)
volume
```

The transforms contain transforms from volume (column, row, slice) index to other coordinate systems. The most commonly used one is `vox2ras`, which is a `4x4` matrix mapping the voxels to scanner (usually `T1-weighted`) `RAS` (right-anterior-superior) system.

Accessing the image values via `[` operator. For example,

``` r
volume[128, , ]
```

Plotting the anatomical slices:

```{r plot_volume, fig.width=8, fig.height=3, out.width="95%"}
par(mfrow = c(1, 3), mar = c(0, 0, 3.1, 0))

ras_position <- c(-50, -10, 15)

ras_str <- paste(sprintf("%.0f", ras_position), collapse = ",")

for(which in c("coronal", "axial", "sagittal")) {
  plot(x = volume, position = ras_position, crosshair_gap = 10,
       crosshair_lty = 2, zoom = 3, which = which,
       main = sprintf("%s T1RAS=[%s]", which, ras_str))
}

```

## Surface files

Reading surface file using `read_surface` supports multiple data types


```{r read_surface}
library(ieegio)
# geometry
geometry <- read_surface(geom_file)

# measurements
measurement <- read_surface(shape_file)

# time series
time_series <- read_surface(ts_file)
```

You can merge them to a single object, making an object with multiple embedding data-sets:

```{r merge}
merged <- merge(geometry, measurement, time_series)
print(merged)
```

Plot the surfaces in `3D` viewer, colored by shape measurement

```{r plot_surface, webgl = TRUE, out.width="70%", fig.width = 7}
# plot the first column in measurements section
plot(merged, name = list("measurements", 1))
```

Plot the normalized time-series data

```{r time_series, webgl = TRUE, out.width="100%", fig.width = 7}
ts_demean <- apply(
  merged$time_series$value,
  MARGIN = 1L,
  FUN = function(x) {
    x - mean(x)
  }
)
merged$time_series$value <- t(ts_demean)
plot(
  merged, name = "time_series",
  col = c(
    "#053061", "#2166ac", "#4393c3",
    "#92c5de", "#d1e5f0", "#ffffff",
    "#fddbc7", "#f4a582", "#d6604d",
    "#b2182b", "#67001f"
  )
)
```

# Streamline files

Reading streamlines via universal entry function `read_streamlines`

```{r read_streamlines, results='hide'}
trk <- read_streamlines(trk_file, half_voxel_offset = TRUE)
tck <- read_streamlines(tck_file)
tt <- read_streamlines(tt_file)
```

To obtain the streamline data

```{r streamline_subset}
message("Total number of streamlines: ", length(trk))

head(trk[[1]]$coords)
```

To preview the streamline data

```{r streamline_plot, out.width="100%", fig.width = 9, fig.height=3}
pal <- colorRampPalette(c("navy", "grey", "red"))
plot(trk, col = pal(length(trk)))
```


To write the streamlines, for example, write `tck` file to `trk` file:

```{r streamline_write}
# Create a temporary file
tfile <- tempfile(fileext = ".trk")
write_streamlines(x = tck, con = tfile)
```

```{r streamline_cleanup, echo = FALSE, results='hide'}
if(file.exists(tfile)) {
  unlink(tfile)
}
```

```{r teardown, echo=FALSE, results='hide'}
cache_dir <- tools::R_user_dir("ieegio", "cache")
if(file.exists(cache_dir)) {
  unlink(cache_dir, recursive = TRUE, force = TRUE)
}
```