# Read imaging data

`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.

    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.

    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,

    volume[128, , ]

Plotting the anatomical slices:

    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

    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:

    merged <- merge(geometry, measurement, time_series)
    print(merged)

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

    # plot the first column in measurements section
    plot(merged, name = list("measurements", 1))

Plot the normalized time-series data

    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`

    trk <- read_streamlines(trk_file, half_voxel_offset = TRUE)
    tck <- read_streamlines(tck_file)
    tt <- read_streamlines(tt_file)

To obtain the streamline data

    message("Total number of streamlines: ", length(trk))

    head(trk[[1]]$coords)

To preview the streamline data

    pal <- colorRampPalette(c("navy", "grey", "red"))
    plot(trk, col = pal(length(trk)))

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

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