tutorial_R.Rmd

---
title: "subcortexVisualizationR tutorial"
output: 
  github_document:
    html_preview: false
date: "2026-01-29"
---

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

## Load required packages

```{r}
library(subcortexVisualizationR)
library(tidyverse)
```

## Example data just to show the different regions

First, let's create a simple dataframe with the left hemisphere cortical regions, assigning a different value to each region for visual clarity. 
Note that all data passed to `plot_subcortical_data` needs to follow the same three-column structure as shown below: `region` (the name of the subcortical region with the same nomenclature as shown), `value` (the value to be plotted in the subcortex map), and `Hemisphere` (either 'L', 'R', or 'both').

```{r}
# Set seed for reproducibility

example_subcortex_data = data.frame(region = c("accumbens", "amygdala", 
                                               "caudate", "hippocampus", 
                                               "pallidum", "putamen", 
                                               "thalamus"),
                                    value = 1:7,
                                    Hemisphere = "L")

example_subcortex_data
```

Now, we can plot this data with the `plasma` colormap as an example in the left cortex. Note the following arguments:  

* `subcortex_data`: The three-column data.frame shown above
* `atlas`: The name of the atlas to plot
* `line_thickness`: How thick the lines around each subcortical region should be drawn, in mm (default is 0.5)
* `line_color`: What color the lines around each subcortical region should be (default is 'black')
* `hemisphere`: Which hemisphere ('L' or 'R') the `subcortex_data` is from; can also be 'both' (default is 'L')
* `fill_title`: Name to add to legend
* `cmap`: Name of colormap (e.g., 'plasma' or 'viridis') or a `matplotlib.colors.Colormap` (default is 'viridis')
* `vmin`: Min fill value; this is optional, and you would only want to use this to manually constrain the fill range to match another figure
* `vmax`: Max fill value; this is optional, and you would only want to use this to manually constrain the fill range to match another figure

```{r}
plot_subcortical_data(subcortex_data=example_subcortex_data, atlas = 'aseg',
                      line_thickness=0.5, line_color='black',
                          hemisphere='L', fill_title = "aseg region index", cmap='plasma', 
                          vmin=NA, vmax=NA)
```

If we wanted to plot this with the `inferno` color palette instead, just swap out the `cmap` argument values:

```{r}
plot_subcortical_data(subcortex_data=example_subcortex_data, atlas = 'aseg', 
                      hemisphere='L', fill_title = "aseg region index", cmap='inferno')
```

By default, `plot_subcortical_data` will plot the index values of each region, so we actually don't need to pass in a dataframe for this visualization purpose.
Here, we can plot the region indices for the Melbourne Subcortex S1 atlas in the right hemisphere without passing in any data:

```{r}
plot_subcortical_data(atlas = 'Melbourne_S1', hemisphere='R', 
                      fill_title = "Melbourne Subcortex S1 atlas region", 
                      cmap='viridis')
```

To plot both hemispheres using gray lines at thickness 1.0, we can set the `hemisphere` argument to 'both' and adjust the `line_thickness` and `line_color` arguments accordingly:

```{r}
plot_subcortical_data(atlas = 'Melbourne_S1', hemisphere='both', 
                      line_color='gray', line_thickness=1,
                      fill_title = "Melbourne Subcortex S1 atlas region", cmap='viridis')
```

We can also use the S2 level of granularity from the Melbourne Subcortex (Tian 2020) Atlas:

```{r}
plot_subcortical_data(atlas = 'Melbourne_S2', hemisphere='both', 
                      fill_title = "Melbourne Subcortex S2 atlas", cmap=rainbow)
```

Lastly, let's view the atlas for (1) [AICHA subcortex](https://www.sciencedirect.com/science/article/abs/pii/S0165027015002678); (2) [Brainnetome subcortex](https://pmc.ncbi.nlm.nih.gov/articles/PMC4961028/); and (3) [SUIT cerebellum](https://doi.org/10.1016/j.neuroimage.2006.05.056):

```{r}
# AICHA
plot_subcortical_data(atlas = 'AICHA', hemisphere='both', 
                      fill_title = "AICHA subcortex atlas", cmap=rainbow)
```

```{r}
# Brainnetome
plot_subcortical_data(atlas = 'Brainnetome', hemisphere='both', 
                      fill_title = "Brainnetome subcortex atlas", cmap=rainbow)
```

```{r}
# SUIT cerebellum
plot_subcortical_data(atlas = 'SUIT_cerebellar_lobule', hemisphere='both', 
                      fill_title = "SUIT cerebellum atlas", cmap=rainbow)
```

## Simulating and visualizing continuous data

```{r}
set.seed(127)



example_continuous_data_L <- data.frame(region = c("accumbens", "amygdala", 
                                                "caudate", "hippocampus", 
                                                "pallidum", "putamen", 
                                                "thalamus"),
                                       Hemisphere = 'L',
                                    value = rnorm(7))

example_continuous_data_R <- data.frame(region = c("accumbens", "amygdala", 
                                                "caudate", "hippocampus", 
                                                "pallidum", "putamen", 
                                                "thalamus"),
                                       Hemisphere = 'R',
                                    value = rnorm(7))


example_continuous_data <- rbind(example_continuous_data_L, example_continuous_data_R)


# See what the left hemisphere data, randomly sampled from a normal distribution, looks like
example_continuous_data
```

Plot the left hemisphere:

```{r}
plot_subcortical_data(subcortex_data=example_continuous_data_L, atlas = 'aseg',
                      hemisphere='L', fill_title = "Normal distribution sample, aseg atlas", 
                      cmap='viridis')
```

Right hemisphere:

```{r}
plot_subcortical_data(subcortex_data=example_continuous_data_R, atlas = 'aseg',
                      hemisphere='R', fill_title = "Normal distribution sample, aseg atlas", 
                      cmap='viridis')
```

Both hemispheres together:

```{r}
plot_subcortical_data(subcortex_data=example_continuous_data, atlas = 'aseg', 
                      hemisphere='both', fill_title = "Normal distribution sample, aseg atlas", 
                      cmap='viridis')
```

You can pass in a custom colormap too! For example, if you want to fill in with a gradient ranging from white to purple:

```{r}
plot_subcortical_data(subcortex_data=example_continuous_data, atlas = 'aseg', 
                      hemisphere='both', fill_title = "Normal distribution sample", 
                      cmap=c('white', '#76167D'))
```

Since this data has positive and negative values, 

Since this data has positive and negative values, we can pass in a color palette from blue (negative) to white (0) to red (positive). 
`plot_subcortical_data` takes an argument `midpoint` that specifies the center point for the color palette.
Setting this to 0 here enforces the center value to be white.
Without setting vmin/vmax explicitly, the color range will be defined symmetrically around `midpoint` to capture the full range of the data.

```{r}
plot_subcortical_data(subcortex_data=example_continuous_data, atlas = 'aseg',  
                      hemisphere='both', fill_title = "Normal distribution sample", 
                      cmap=c("blue", "white", "red"), midpoint=0)
```