First install wholebrain

To use SMART, wholebrain must first be installed. If your machine is running Windows or Linux, the most updated instructions were written by Matias Andina and can be found at this site.

If you are running on Mac OSX, the most updated instructions to install Wholebrain can be found here

The original wholebrain installation instructions are somewhat outdated. However I highly recommend reading through all the documentation and watching the tutorials for Wholebrain on the original [website] (www.wholebrainsoftware.org) before using this package.

SMART is easily installed from github using the devtools package:

pipeline schematic

# Load devtools
library(devtools) 
 
# Install SMART
devtools::install_github("sgoldenlab/SMART@main") 

# Load SMART
library(SMART)

# Pull up package descriptions and list of functions
?SMART

Docker with wholebrain & SMART pre-installed

An alternative to the above instructions using a Wholebrain + SMART Docker image is recommended for those that are having serious installation issues. Docker is a platform for software virtualization and can deliver software in packages called containers. Read more about Docker on their documentation website.

The docker can also be used to trial the functions that are available with these two packages. Because the docker image is a “snapshot” of the version of wholebrain and SMART at the time of the image creation, any updates to these packages will not be included in the image.

Please note that we still favor installing wholebrain and SMART directly to your computer if possiible. The docker requires X-Forwarding to render certain graphical user interfaces onto the host computer. This results in a slower overall interactive experience.

Windows Docker Instructions

The steps below were tested on a PC running Windows 10 Enterprise, Intel(R) Core(TM) i9-10900 CPU. with 64 GB of installed RAM.

  1. Install Docker for Windows (4.3.2 was tested). Click here. Run the ‘Docker Desktop Installer.exe’ file and accept the defaults, including ’Enable Hyper-V Windows Features” or “Install required Windows components for WSL-2.”

  2. Launch the Docker Desktop application and click yes if there is a pop-up stating the WSL-2 installation is incomplete. Follow the instructions to install the Linux kernel and click “restart” on the Docker Deskstop pop-up to restart the computer and finish the installation.

  3. Open up a terminal as an administrator. Pull the wholebrain-SMART docker image from DockerHub with the command:

Docker pull mjin1812/wholebrain_smart

  1. Install vcxsrv. Click here. This is a Windows X-Server and is used for displaying graphical information communicated from the running docker container. Click on the installer and accept all defaults.

  2. Open the X server (vcxsrv) by clicking on the XLaunch shortcut or searchin for XLaunch in the windows search bar. Hit next and accept the defaults until you reach the “Extra settings” window. MAKE SURE to check the box next to “Disable access control” to allow accepting connections from all clients.

  3. Open a terminal as an administrator and type the following command:

ipconfig

Look for your IPv4 Address for your network adaptor and write it down.

  1. Enter command below to launch your Docker container. Copy and paste your IPv4 address in the correct position.
docker run -it --rm -e DISPLAY=<IPv4 address>:0.0 -v /tmp/.X11-unix:/tmp/.X11-unix -e DISABLE_AUTH=true -e ROOT=true -p 8787:8787 mjin1812/wholebrain_smart

For example, if my IPv4 address is 10.20.230.51 the following command will launch my docker container.

docker run -it --rm -e DISPLAY=10.20.230.51:0.0 -v /tmp/.X11-unix:/tmp/.X11-unix -e DISABLE_AUTH=true -e ROOT=true -v C:/Users/jinmich/Documents/my_project:/home/rstudio/my_project -p 8787:8787 mjin1812/wholebrain_smart

In the above command, I also included the -v flag to map data from my folder on my host computer, “C:/Users/jinmich/Documents/my_project” to a folder accessible from my Docker container “/home/rstudio/my_project.” Processing of any data within mapped drive using the docker container should access the data using the docker path.

  1. Open up a web browser and navigate to localhost:8787.If you would like to use a different port, change the argument after the -p flag in the command used to run the docker container. An RStudio interface should appear in the window.

You can type the command below to check that wholebrain is working.

library(wholebrain) 
filename<-system.file('sample_tiles/rabiesEGFP.tif', package='wholebrain') 
seg<-segment(filename)

At this point, the docker container is running and users can feel free to follow along with the pipeline tutorial.

Note: when entering paths into the container running RStudio, absolute paths take linux conventions and start with the root path ‘/home’, so make sure to include the first forward slash.

  1. When you are done using the docker container to run Wholebrain or SMART in a given session, navigate to the terminal. CTRL + C will stop running the container. You can check that there are no running containers by typing docker container ls.

  2. Kill the X server with the terminal command:

taskkill /f /im vcxsrv.exe

YouTube tutorial of Windows Docker Instructions Click here!

Technical considerations and recommendations:

  1. SMART and wholebrain should be installed on a computer with at least 16 GB of RAM. 8GB of RAM may be too low and crash R for some of the pipeline processes.
  2. The user-experience of this pipeline would be improved with a dual monitor setup, so that any graphics window popups may occur on one monitor, while the command-line interface is visible on the other.