SMARTR

0 Prior steps to get started

SMARTR stands for simple multi-ensemble atlas registration and statistical testing in R. It is also a self-referential play on a previous package developed as an extension to wholebrain called SMART.SMARTR interfaces with some functions from both of these packages underneath the hood.

SMARTR encapsulates the process of registration and performs downstream analysis. Prior to this, the imaging data must be pre-processed and cells are separately segmented in ImageJ/FIJI. We have a separate, in-depth article on our imaging and pre-processing approach, parameters, and segmentation process. We provide links to an example image to run though the pre-processing and segmentation. There is also a separate in-depth tutorial article for SMARTR using this example image. This page provides installation instructions and a broad explanation of the central package organization around data objects

Imaging, segmentation, and pre-processing pipeline

1 Installation

1.1 Install RStudio and R

We recommend installing R version 3.6. You can use R version 4.1+ if you only want access to analysis and visualization capabilities.

1.2 Install wholebrain

Installing wholebrain can be finicky. The most updated instructions on installing wholebrain for Windows is found here. For Macs, the instructions can be found here. We strongly recommend using a Windows setup, as this package has been used mostly in Windows.

If wholebrain is not installed, only the analysis and visualization functions may work.

1.3 Install SMARTR

To to download the package from github using the devtools package, we need to use the install_github() function.There are also some dependencies on the tidyverse packages so we will install that too. Install the package with the code below:

# Install from CRAN
install.packages("tidyverse")`

# If you intend on using wholebrain for mapping, run the code below.
require(remotes)
install_version("ggpraph", version = "2.1.0", repos = "http://cran.us.r-project.org")

# Install ggpattern package (optional but useful package for plotting) 
devtools::install_github("coolbutuseless/ggpattern")

# Set the devtools install options for just 64-bit architecture. This is important.
options(devtools.install.args = "--no-multiarch")   

# Install package
devtools::install_github("mjin1812/SMARTR@main")

We can now load the package!

# Load SMARTR
library(SMARTR)

You can pull up the package description with the code below:

?SMARTR
#> No documentation for 'SMARTR' in specified packages and libraries:
#> you could try '??SMARTR'

Tip: From now on, get in the habit of using the ? operator to pull up the help page about a package, object, function, or piece of data

2 Introduction to SMARTR

2.1 OOP in R

It’s helpful to get a sense of a how the structure of data is handled and bundled together in this pipeline. Data is stored in S3 data type objects called slice, mouse, and experiment. The data in these objects will be manipulated by a special type of function called a generic function (this is analogous to an object method in python). Generic functions allow you to pass objects of different classes to the same function, and it can recognize and perform different operations on objects depending on their class. If this is all confusing to you, don’t worry at all! This is much more information than you actually need to know to use this pipeline. It’s just helpful to better understand the architecture of the package.

To get an excellent brief overview of what object oriented programming (OOP) is and it’s advantages over procedural programming, check out this excellent YouTube video!

2.2 Slice objects

A slice object will contain all the data related to registration, segmentation for each channel, and cell counts for a particular image.

It will also contain metadata about your images, such as what the slice no. is, which brain atlas AP coordinate matches best with the given image, and what the path to the image used for registration is. These metadata are stored as the object’s attributes.

Run the code below to used the ? operator to pull up the documentation for a slice object. This will pull up a help page description of all the slice object attributes.

?SMARTR::slice

Tip: Usage of the :: or double colons here means that R specifically looks for a function, object, or help page in SMARTR package. This isn’t necessary if you load the package, but it can sometimes help avoid ambiguity if there are identical names for things in other loaded packages.

2.3 Mouse objects

A mouse object is an object that will store multiple slice objects (and therefore all the information in it), and will eventually store the combined cell data and the region cell counts normalized by volume. Like a slice, it will also contain “metadata” about your mouse stored as string attributes. Now, try pulling up the help page yourself for the mouse object to see all attributes you can store!

2.4 Experiment object

An experiment object will primarily store the processed information from multiple mouse objects. Some experimental attributes will autopopulate based on mouse attributes. For example, if multiple mice are added to an experiment with the drug attribute values ketamine or saline, the experiment attribute drug_groups will be a vector with the values ketamine and saline.

Hierarchical object organization in the package