Scalable image processing techniques for quantitative analysis of volumetric biological images from light-sheet microscopy

Here we describe an image processing pipeline for quantitative analysis of terabyte-scale volumetric images of SHIELD-processed mouse brains imaged with light-sheet microscopy. The pipeline utilizes open-source packages for destriping, stitching, and atlas alignment that are optimized for parallel processing. The destriping step removes stripe artifacts, corrects uneven illumination, and offers over 100x speed improvements compared to previously reported algorithms. The stitching module builds upon Terastitcher to create a single volumetric image quickly from individual image stacks with parallel processing enabled by default. The atlas alignment module provides an interactive web-based interface that automatically calculates an initial alignment to a reference image which can be manually refined. The atlas alignment module also provides summary statistics of fluorescence for each brain region as well as region segmentations for visualization. The expected runtime of our pipeline on a whole mouse brain hemisphere is 1-2 d depending on the available computational resources and the dataset size.


Introduction
Light-sheet fluorescence microscopy (LSFM) is an optical sectioning technique that provides highspeed acquisition of high resolution images. Affordable open-access systems have promoted adoption of LSFM 1 . As a result, LSFM has become commonplace in the study of complex biological systems [2][3][4][5] . However, the high-throughput acquisition offered by LSFM can quickly generate terabytes of image data, posing challenges in data storage, processing, and visualization. These challenges must be addressed in order to perform the quantitative analyses needed to answer the complex biological questions at hand. SHIELD is a tissue transformation technique that preserves endogenous biomolecules for imaging within intact biological systems 6 . SHIELD retains fluorescent protein signals through the clearing process and is compatible with stochastic electrotransport staining, allowing visualization and quantification of fluorescence signals throughout the entire brain 7 . When SHIELD-processed tissues are imaged using LSFM, entire organs such as the mouse brain can be imaged at singlecell resolution in just 2 hours, offering more data than was previously available to answer new biological questions.
Here we present detailed protocols for quantifying fluorescence signals in each brain region of SHIELD-processed mouse brain LSFM datasets. The pipeline is composed of modules for image destriping, stitching, and atlas alignment. Each module can either be used independently or in combination to perform region-based statistical analyses of fluorescence within intact mouse brain samples. The pipeline and all its dependencies have been packaged into a single Docker container, allowing for simple installation and cross-platform use. The ease of deployment offered by Docker makes our image processing pipeline more accessible to researchers without much programming experience. We also provide a dataset of a whole mouse brain hemisphere for users to test our pipeline.

Development of the protocol
In order to analyze large-scale volumetric images acquired using LSFM, research labs typically create their own image processing pipelines 4,[8][9][10] . These image processing pipelines are designed to solve specific problems in applying LSFM to the study of complex biological systems. Realtime cell tracking systems have been reported to study the dynamics of embryogenesis in D. melanogaster 8,9 . The cell tracking pipeline relies on optimized CUDA programming to achieve real-time performance. Several computational pipelines geared toward processing time-lapse images of D. melanogaster assume that each time point image is smaller than the amount of available memory. In contrast, LSFM of whole mammalian organs often generates individual volumetric images that are larger than the amount of available memory.
semi-automatic atlas alignment for segmenting brain regions and quantifying fluorescence (Fig.  1). Our protocols have been tested on images of SHIELD-processed mouse brain hemispheres acquired with an axially-swept light-sheet microscope.

Development of the destriping module
Stripe artifacts are commonplace in images acquired with LSFM due to irregularities in the refractive index (RI) of the sample 3,11 . This RI mismatch can be compensated for using an immersion medium that has a similar RI to that of the sample 12 . However, the material properties of biological tissues, including the RI, are generally not uniform throughout, making some degree of RI mismatch inevitable. RI mismatch usually results in uneven illumination patterns due to optical aberrations that disrupt the incident light.
Current strategies for image destriping are either based on optical filtering or digital filtering 11,[13][14][15] . Optical filtering strategies attempt to compensate for RI mismatch during imaging, effectively removing the stripe artifacts from the source. However, these methods may disrupt the axial resolution of the LSFM system in the process and may not be applicable to large biological samples. In contrast, digital filtering strategies attempt to remove the stripe artifacts after acquisition by exploiting the noise characteristics induced by the optical aberrations. Since digital destriping methods are implemented as image filters, they can be applied more generally to any images with stripe artifacts.
Previous digital destriping methods have included hybrid wavelet-FFT filters, variational removal of stationary noise (VSNR), and multidirectional filters using the contourlet transform (MDSR) [13][14][15] . Although VSNR and MDSR have shown superior destriping performance, they are prohibitively slow for applying to whole-brain datasets. The hybrid wavelet-FFT filter is the fastest destriping method of these, but its implementation requires a MATLAB license to use and is single-threaded.
In order to provide a fast, open-source destriping solution, we implemented a new digital destriping tool called pystripe. Pystripe is a Python implementation of the previously reported hybrid wavelet-FFT destriping method with parallel processing support and other improvements. Pystripe uses open-source tools instead of proprietary software such as MATLAB. As in the hybrid wavelet-FFT approach, the amount of filtering in pystripe can be tuned using a bandwidth parameter. Pystripe also adds support for a dual-band filtering mode where the background and foreground of the images can be filtered with separate bandwidths.

Development of the stitching module
Imaging large samples with LSFM involves acquiring partially overlapping image stacks which can be stitched together into a single image stack. Several open-source stitching packages are available 16,17 . Terastitcher has been widely adopted for stitching large volumetric images acquired with LSFM. However, the Terastitcher merging step executes within a single thread by default, resulting in longer execution times than necessary. It should be noted that the Terastitcher team provides a parallelized version of Terastitcher based on message passing interface (MPI) upon request, but we found implementing our own merging step based on the multiprocessing module in Python to be more straightforward than managing MPI.
To address these shortcomings, we created the TSV (Terastitcher Volume) module, which implements the Terastitcher merging step in Python with support for lossless TIFF compression and parallel processing. TSV uses the stack displacements computed from Terastitcher to create a memory-mapped array representing the entire image volume. Multiple workers use this memory-mapped array to convert individual images into a single stack, providing faster overall execution. Each worker merges images together and then saves the result using lossless TIFF compression, resulting in lower overall dataset sizes.

Development of the atlas alignment module
In order to segment whole-brain LSFM images into different brain regions, the stitched dataset must be registered to a reference atlas, such as the Allen Mouse Brain Atlas (ABA) 18 . The ABA consists of an averaged anatomical reference image of autofluorescence and the corresponding region segmentation image. The ABA also contains tools for registering 3D reconstructions from histological sections to the atlas. However, research labs have resorted to custom atlas alignment methods for LFSM images of intact brain samples 4 .
Elastix is an open-source medical image registration library that is widely used for non-rigid atlas alignment 19 . Elastix performs non-rigid atlas alignment by maximizing the mutual information between source and reference images. Elastix was found to have the highest mutual-information benchmark scores in image registration of cleared brain samples among five freely-available software packages 20 . The global optimization of mutual information is difficult to scale to wholebrain LSFM datasets since the entire dataset cannot be stored in memory. Following previous work on atlas alignment, we address this issue by rescaling the source image to be a similar size compared to the reference atlas, which is a more manageable size. We use the alignment computed from Elastix to generate a set of approximate point correspondences which can manually refined.
To visualize the atlas alignment and edit the approximate point correspondences, we created an interactive web-based registration tool called nuggt (NeUroGlancer Ground Truth). Nuggt is built on an open-source visualization package called Neuroglancer. Nuggt does not modify the underlying Neuroglancer code but rather wraps it into a convenient package for interactive LSFM visualization and atlas alignment. Nuggt displays the source and reference images side-by-side along with the point correspondences overlaid on each image. Using nuggt, the point correspondences can be edited and adjusted to improve the atlas alignment. The source image can also be warped while editing the point correspondences, providing rapid visual feedback of the atlas alignment accuracy.

Development of the Docker image
One of the main challenges in adopting a new computational pipeline is obtaining the dependencies and recreating the runtime environment that was intended by the developers. In order to simplify the installation of our pipeline, we packaged our pipeline and all of its dependencies into a single Docker container by creating a Dockerfile describing our runtime environment. Docker provides a consistent, light-weight virtual Linux environment on all major operating systems, and our container has been successfully tested on Windows, Mac, and Linux. Docker can be installed from the Docker website, and our container can be downloaded from Docker Hub. By containerizing our pipeline and using web-based visualization, our modules can either be run locally or on dedicated image processing servers which can be accessed from other clients.

Applications of the method
The overall image processing pipeline described in this protocol is designed to calculate fluorescence summary statistics from whole-mouse brain images acquired with LSFM on a perregion basis. Our pipeline has been used to quantify mRuby2 and EGFP fluorescence of virally labeled neurons and presynaptic terminals in SHIELD-processed mouse brain hemispheres 6 . Thus, the overall pipeline may be applied in systems neuroscience to quantify fluorescent reporters in cleared samples from mouse models. However, the individual modules that comprise the overall pipeline can also be used independently.
Pystripe can be applied to any images corrupted with horizontal or vertical stripe artifacts. We restricted pystripe to filtering horizontal or vertical stripes because the illumination beam path in most LSFM systems is aligned with the camera detector. Pystripe can, therefore, also be used with multi-view LSFM systems that rotate the sample rather than change the orientation of the illumination beam path 21 . Pystripe also includes the ability to provide a reference flat-field image for illumination correction of vignetting and other stationary artifacts.
TSV can be used to merge an array of partially overlapping image stacks saved in Terastitcher hierarchal format into a single image stack 17 . The memory-mapped array used for stitching is also useful for retrieving sub-volumes of image data. TSV also includes optional utilities for partitioning the stitched image into smaller, uniformly shaped chunks for custom parallel processing. The stitched images can be stored in Neuroglancer precomputed format and served via HTTP, allowing for efficient visualization of whole-brain LSFM datasets at full resolution either locally or over the web.
Nuggt has been used to register SHIELD-processed mouse brain hemisphere datasets to the ABA. Our alignment protocol can be used to register a pair of 3D volumes with mutual information between them and a gradient of mutual information in the initial overlap that can be followed to modify the alignment. In our experience, images that have 90% overlap and rotations of a few degrees can be aligned using this method. The automatic alignment can be refined by adding manually-placed correspondences. The atlas alignment module also provides utilities for calculating image statistics for each brain region given the aligned atlas segmentation.

Comparison with other methods
Many standard solutions exist for similar tasks addressed in our image processing pipeline. In this section, we compare the methods used in our protocol to existing methods in the context of whole brain LSFM image analysis.

Destriping
The previously reported digital destriping algorithm MDSR has achieved state of the art destriping performance on LSFM images 15 . MDSR relies on the contourlet transform to perform energy compaction of striping artifacts in arbitrary orientations, whereas pystripe uses the discrete wavelet transform to remove either horizontal or vertical striping artifacts.
When comparing the resulting images from MDSR and pystripe, similar filtering performances are observed from both methods on our test images (Fig. 2a). This suggests that the contourlet transform does not drastically improve energy compaction of the stripe artifacts compared to the discrete wavelet transform when the stripes are oriented horizontally. When comparing the average execution speed for destriping using MDSR and pystripe on a single core, MDSR takes over 30 min per frame, while pystripe takes only 5 seconds (Fig. 2b). Using multiple cores, the destriping frame rate for pystripe increases linearly with the number of cores, reaching 8 frames per second with 48 cores (Fig. 2c, Supplementary Video 1).
Pystripe also allows the user to provide an optional reference image for flat-field correction. Ideally, the reference flat would be calculated retroactively from the imaging data, but in practice a single flat for each channel of a particular imaging system still provides significant improvement. The example dataset includes a reference flat for illumination correction during the destriping step. By performing the illumination correction in pystripe, reading and writing the whole dataset multiple times can be avoided.

Stitching
Building on Terastitcher, TSV allows fast merging of stacks saved in Terastitcher hierarchal format. TSV obtains similar stitching quality as Terastitcher since it uses the same stack displacements and blending functions. Using TSV, a whole mouse hemisphere dataset was stitched with and without illumination correction and destriping using pystripe (Fig. 3a). Moderate vignetting effects were visible in the stitched original images at the intersections between adjacent stacks. These tiling artifacts were effectively reduced using flat-field correction in pystripe. Together, pystripe and TSV generate volumetric images that are ready for quantification by removing shadow and tiling artifacts before stitching (Fig. 3b, Supplementary Video 2). When comparing the stitching speed of TSV using multiple cores, the stitching frame rate increases linearly, reaching 2.6 frames per second with 48 cores (Fig. 3c).

Atlas Alignment
Our hybrid automated atlas alignment method with manual refinement differs from wholly automated methods in that the alignment can be improved to the desired degree of accuracy via addition and modification of correspondences between the two volumes to be aligned (Fig. 4a). Tools for manual refinement are generally not used in combination with Elastix because integrating the transformations across multiple registration tools can be challenging. To the best of our knowledge, there are no web-based tools for interactive atlas alignment currently available.
After aligning a source autofluorescence or nuclear stain image to the reference image, other channels can be aligned to the atlas using the same calculated alignment. For example, neuropeptide Y (NPY) and somatostatin (SST) expression are included with syto 16 in separate channels of the provided example data (Fig. 4b). Using the alignment calculated by registering the syto 16 channel and the reference from the ABA, the mean fluorescence intensity of NPY and SST in each brain region can be calculated (Fig. 4c).

Experimental design
All software modules are available from Github at http://www.github.com/chunglabmit/shield-2018 as well as from Docker hub at https://hub.docker.com/r/chunglabmit/shield-2018. We also provide example LSFM images of a SHIELD-processed mouse hemisphere dataset, which is available http://leviathan-chunglab.mit.edu/nature-protocols-2019. In order to adapt our image processing pipeline to other experimental situations, users should first complete our protocol using the provided example dataset. This dataset includes raw LSFM images as well as our intermediate results for users to compare and checkpoint their results throughout the pipeline. We also include a downsampled version of the full example dataset for users that would like to try our protocol on more modest computational hardware.
Young adult (2-4 months; median age 3 months) C57BL/6 mice were housed in a 12 h light/dark cycle with unrestricted access to food and water. To generate the example dataset, a single mouse brain was SHIELD-processed and stained with syto 16 and antibodies targeting NPY and SST using stochastic electrotransport 7 . The mouse brain sample was cut along the mid-sagittal plane and includes the olfactory bulb and the cerebellum. The stained hemisphere was then incubated in a RI-matching solution and imaged using a custom axially-swept LSFM system equipped with a 3.6x/0.2 objective (Special Optics). The resulting voxel width and depth are 1.8 µm and 2.0 µm, respectively. Although only one animal was involved in preparing the example dataset, our image processing protocol has been tested on over 15 intact mouse brain hemispheres from separate animals. All experimental protocols were approved by the MIT Institutional Animal Care and Use Committee and the Division of Comparative Medicine and were in accordance with guidelines from the National Institute of Health. All experiments using mice were conducted in strict adherence to the ethical regulations of MIT Institutional Animal Care and Use Committee and the Division of Comparative Medicine.
Our protocols have been developed for images of SHIELD-processed mouse brain tissues sectioned along the midsagittal plane with or without the olfactory bulb and cerebellum excised. The images must be acquired in a geometry that allows a transformation of axes (flipping, transposition) and cropping that bring the images into rough alignment with the atlas. In our experience, acquisition of either autofluorescence or a nuclear stain such as syto 16 provides enough mutual information for alignment with the reference volume for the ABA. Images were processed using only the techniques described in the protocol, and figures were prepared using linear lookup tables with adjustment of the minimum and maximum display range.

Expertise needed to implement the protocol
Some minimal computer skills are needed to install Docker and navigate using the command line. If you are unfamiliar with Docker, important introductory information about Docker can be found at https://docs.docker.com/get-started/. Our protocol relies on several Docker features for volume sharing and network access, so a basic understanding of Docker is a prerequisite. Since Docker and most of our software is used from the command line, a basic understanding of how to use a terminal on the host operating system is also required.

Limitations
Our overall image processing pipeline currently has been tested for analyzing mouse brain hemisphere datasets using the ABA autofluorescence reference volume. Therefore, we cannot guarantee that our overall pipeline will work in all cases for other species and atlases.
As previously mentioned, pystripe cannot remove striping artifacts that are not horizontally or vertically oriented within raw images. When processing images with very bright signals, the hybrid wavelet-FFT filter may introduce some ringing artifacts to the destriped images. The dual-band mode can mitigate these ringing artifacts, but in some cases, these artifacts may be undesirable. The user can elect to reduce the filter bandwidth or skip the destriping step in such cases.
When analyzing mouse brain hemispheres, severe tissue deformation due to improper sample preparation or handling may result in poor atlas alignment since the initial non-rigid alignment may not converge to a global optimum in such cases. Our atlas alignment protocol can be applied to mouse brain hemispheres with the olfactory bulb and cerebellum excised; however, this excision must be mirrored in the anatomical reference volume. This involves cropping the anatomical reference volume to match the source image, which is somewhat ad hoc. We provide reference volumes from the ABA for use in our Docker container along with reference volumes with the olfactory bulb, cerebellum, or both excised.
Processing whole-brain LSFM datasets is computationally expensive. We provide minimum system requirements that are recommended for processing our example mouse hemisphere dataset. However, we also provide a downsampled version of the original dataset for users without immediate access to computer hardware that meet the minimum system requirements.

Example Data
All Example data is available from our laboratory servers (http://leviathanchunglab.mit.edu/nature-protocols-2019), including: • Raw data, comprising the raw LSFM images and a flat reference image from the provided mouse brain dataset. • Destriped data, comprising the destriped LSFM images from the provided dataset.
• Stitched data, comprising the stitched destriped LSFM images from the provided dataset.
• Alignment data, containing the mean fluorescence in each region and intermediate results obtained during atlas alignment. • Downsampled data, comprising our whole brain raw data downsampled and zipped for testing our pipeline on more modest computer hardware.

Computer Equipment
• For benchmarks, the computational pipeline was deployed on a workstation (TWS-1686525, Exxact) running Ubuntu 16.04 LTS on a 1 TB solid-state drive (Samsung) with two 24-core processors (Intel Xeon Platinum 8168), 768 GB of ECC memory, and a single 16 GB NVIDIA GPU (Tesla P100). • Recommended minimum system requirements for processing the full-resolution example LSFM dataset. A computer with enough hard drive space to store the raw image data as well as the intermediate processing results is required. Our total example data is approximately 3 TB, suggesting that at least 4 TB of extra space is required. We recommend the following minimum system requirements in This command will download our software including all of the dependencies as well as commonly used resources needed for atlas alignment with the ABA. Note that we refer to the computer that is running Docker as the "host" and an instance of our Docker image as the "container". 1. Create a folder named "data" to contain all of the example data on your machine and note its full path. 2. Start the Docker container with the data folder mounted by entering the following command into the command line:

Downloading full resolution example data
docker run -it -v path_to_data:/data chunglabmit/shield-2018 where "path_to_data" should be replaced with the full path to the data folder on the host. The command prompt should indicate that you are now the root user inside a running Docker container (as opposed to your usual username on the host). We refer to the command prompt inside a running container as the "Docker terminal window".
3. Download the example data needed for a particular stage in the protocol by entering the following command(s) into the Docker terminal window. The data should begin to appear in the data folder that was created. Note that each download may take several hours.

Container setup
i) Download the raw data (see 'Downloading full resolution example data' in the MATERIALS section) or move pre-existing raw data to a new folder called "data" and make note of the folder path on the host. Skip this step if using the downsampled example data.
CRITICAL STEP Pystripe only accepts TIFF and RAW file formats. If using the fullresolution example data, the data folder should be created on a device with at least 4 TB of available space.

? TROUBLESHOOTING
ii) Inspect the raw images using FIJI. ? TROUBLESHOOTING iii) Open a terminal and start the Docker container with the data folder from the host mounted inside the container using the following command: docker run -it -v path_to_data:/data chunglabmit/shield-2018 where "path_to_data" should be replaced with the full path of the data folder on the host. Note that the command prompt will change to the root user indicating that the prompt is now running interactively from within the container.

CRITICAL STEP
The semantics for mounting a volume to share data with the container are to specify a source path on the host and a target path inside the container. The syntax for expressing this at the command line is "-v path_on_host:path_in_container". Note that path_in_container is a Unix-style path since the container is a Linux virtual machine.
CRITICAL STEP Add quotes around the full path if it contains any spaces. ? TROUBLESHOOTING iv) Verify that the data folder is mounted correctly by running the following command from within the Docker terminal window.

ls /data
This command should list the contents of the shared data folder mounted in the container at the root path. ? TROUBLESHOOTING Destriping raw images from whole-brain LSFM v) Run the following command to get the latest version of pystripe: git -C /shield-2018/pystripe pull Inspect the help message from pystripe by entering the following command from within the container.

pystripe --help
Instructions for using pystripe from the command line should print. Note from the instructions that an input folder and filter bandwidth are required and that pystripe will default to using all CPU cores available to the container.
vi) Destripe the raw data one channel at a time by entering the following commands within the Docker terminal window for each channel: pystripe -i /data/raw_data/channel -o /data/destriped_data/channel -s1 sigma1 -s2 sigma2 -w wavelet -c compression -x crossover -f flat.tif -d dark where "channel" represents the name of the folder containing images of the current channel, "sigma1" and "sigma2" represent the dual-band filter bandwidths in pixels (higher gives more filtering), "wavelet" is the mother wavelet name, "compression" is the amount of lossless TIFF compression, and "crossover" is the intensity range used to switch between filter bands. The arguments "flat" and "dark" are optional inputs for applying illumination correction. Including illumination correction in pystripe removes the need to load the images into memory multiple times.
If using the full-resolution example data, then enter the following command.
pystripe -i /data/raw_data/Ex_0_Em_0 -o /data/destriped_data/Ex_0_Em_0 -s1 32 -s2 32 -w db10 -c 3 -x 10 --flat flat_downsampled.tif --dark 100 A progress bar showing the destriping progress for that channel will appear, and the destriped images will appear in the data folder, which is also available from the host machine.
Inspect some of the resulting destriped images and the corresponding raw images in FIJI. Note that pystripe maintains the raw data folder structure in its output.

vii) Repeat steps A) vi-vii for all other channels.
viii) Shutdown the Docker container by typing "exit" in the Docker terminal window. The terminal will return to its original state before entering the Docker container.
CRITICAL STEP Since Docker creates new containers each time they are started, no files inside the Docker container will be saved when restarting the container except for files in shared folders on the host, such as the mounted data folder.

PAUSE POINT
The destriped data folder can be archived for processing at a later date.

Container setup
i) Download the destriped data (see 'Downloading full resolution example data' in the MATERIALS section) or use the destriped data from the previous step. If using the downsampled data, complete part A and use the resulting destriped data for part B.
CRITICAL STEP TSV only accepts TIFF and RAW file formats saved in Terastitcher hierarchical format. If using the full resolution example data, the data folder should be on a device with at least 4 TB of available space.
ii) Open a terminal and start the Docker container with the data folder from the host mounted inside the container using the following command: docker run -it -v path_to_data:/data chunglabmit/shield-2018 where "path_to_data" should be replaced with the full path of the data folder on the host. Note that the command prompt will change to the root user indicating that the prompt is now running interactively from within the container.

CRITICAL STEP
The semantics for mounting a volume to share data with the container are to specify a source path on the host and a target path inside the container. The syntax for expressing this at the command line is "-v path_on_host:path_in_container". Note that path_in_container is a Unix-style path since the container is a Linux virtual machine.
CRITICAL STEP Add quotes around the full path if it contains any spaces.

Stitching images from whole-brain LSFM
iii) Run the following command to get the latest version of TSV: git -C /shield-2018/tsv pull iv) Use Terastitcher to create a stitching project file based on a single channel by entering the following command in the Docker terminal window.
viii) Inspect the stitched images in FIJI. TSV generates TIFF images which can be imported directly into FIJI.
ix) If there are no more channels to stitched, then proceed to part C of the protocol. If there are more channels to be stitched, then the following command will stitch other channels using the displacements calculated from the master channel: tsv-convert-2D-tif --xml-path /data/destriped_data/channel_master/xml_displproj.xml -output-pattern /data/stitched_data/channel/"{z:04d}.tiff" --compression compression -ignore-z-offsets --input /data/destriped_data/channel Where "channel_master" represents the folder name of the channel used for calculating stack displacements, "channel" represents folder of images from another channel to be stitched using the previously computed displacements, and the other arguments are as described before. Repeat this command for all other channels to be stitched.

PAUSE POINT
The stitched data folder can be archived for processing at a later date.

Container setup and Neuroglancer basics
i) Download the stitched data (see 'Downloading full resolution example data' in the MATERIALS section) or use the stitched data from the previous step. If using the downsampled data, complete part B and use the resulting stitched data for part C.
ii) For Linux users, open a terminal and start the Docker container with the data folder from the host mounted inside the container using the following command: iii) The following files are included in the "/allen-mouse-brain-atlas" folder inside the Docker container: • autofluorescence_25_half_sagittal.tif -a 3D image of the autofluorescence channel for the mid-sagittal sectioning of the Allen Mouse Brain atlas reference (to be used in place of "/reference/reference.tiff"). • annotation_25_half_sagittal.tif -a 3D segmentation of the Allen Mouse Brain reference (to be used in place of "/reference/segmentation.tiff"). • coords_25_half_sagittal.json -the coordinates of key points on the reference (to be used in place of "/reference/points.json") • AllBrainRegions.csv -a mapping of region ID numbers in the segmentation to names of regions.
iv) Open the URL in your browser to see the Neuroglancer user interface. The browser should display four panels. The top left one is the XY view, the top right is the XZ view, the bottom right one is the YZ view, and the bottom left one is a 3D view. The current cursor position in image coordinates is displayed at the top of the Neuroglancer user interface. A list of keyboard shortcuts is available if you type "h" while using Neuroglancer.

? TROUBLESHOOTING
In Neuroglancer, you can move the stack by pressing the left mouse button with the cursor in any of the three orthogonal view panels and dragging. You can scroll through the depth of the stack by turning the mouse wheel, and you can zoom in and out by pressing the "ctrl" key and turning the mouse wheel. Each layer in Neuroglancer listed along the top of the user interface can be hidden by clicking the layer name. Segmentation layers can used to highlight specific brain regions by double-clicking regions in any view panel.
v) Exit the nuggt-display application by holding "ctrl" and pressing "C" in the Docker terminal window.

Create a points file for a custom reference atlas
This step is optional if you are aligning a sagittal image of a mouse brain hemisphere to the Allen Mouse Brain Atlas (which is the case when using the example data). If you are using the example data, proceed to step C xii.
vi) Locate either a 3D TIFF file of the reference image (e.g. "path_to_reference/reference.tiff") or a folder of 2D TIFF files named in strict ascending alphabetical order (e.g. "path_to_reference/images/img_0000.tiff") on the host.
CRITICAL STEP You must prepare an accompanying segmentation of this reference (e.g. "path_to_reference/segmentation.tiff") where each pixel of the segmentation has a value corresponding to the region in which the pixel lies. You must also have a mapping of region number to the region's name in a format similar to the file "/allen-mouse-brainatlas/AllBrainRegions.csv".
vii) Open a terminal and start the Docker container with the reference image(s) mounted using the following command: where "path_to_reference" and "path_to_data" represent the full paths of the directories containing the reference image(s) and the images to be aligned to the reference on the host. The "--network host" argument should only be included by Linux users.
CRITICAL STEP Add quotes around the full path if it contains any spaces.
viii) If you have a 3D reference TIFF file, type the following command into the Docker terminal window: nuggt --port 8999 --image /reference/reference.tiff --output /reference/points.json where "reference.tiff" should be replaced with the name of your reference image. If you have a folder of 2D TIFF files, type: nuggt --port 8999 --image "/reference/images/*.tiff" --output /reference/points.json CRITICAL STEP Use "*.tif" instead of "*.tiff" if that is the extension of your image files.
ix) The nuggt application will display a line similar to "Editing viewer: http://127.0.0.1:8999/v/..." in the Docker terminal window. Windows and Mac users should replace the container ID in the URL with "localhost". Open the URL in your browser to see the Neuroglancer user interface.
x) Add fiducial points by placing the cursor where you want the point to be, holding the "shift" key and pressing "A". You can delete a point by placing the cursor over it, holding the shift key and pressing "D". You should annotate the image using easily identifiable locations like the dentate gyrus as well as the perimeter of the image (see Supplementary Fig. 1).

? TROUBLESHOOTING
xi) Hold the "shift" key and press "S" to save the annotations. Bring up the Docker terminal window again, hold "ctrl" and press "C" to exit from the nuggt application.
PAUSE POINT The points.json file can be saved and reused for future atlas alignment tasks using the same reference image(s).

Perform automatic alignment
xii) Determine whether the images to be aligned with the reference atlas needs to be flipped or rotated by inspecting the stitched and reference images.
If aligning to the provided sagittal mouse brain atlas, each z-plane of the stitched images should be approximately a sagittal section with the olfactory bulb at the top of the image and the cortex to the right (see Supplementary Fig. 1). The z-plane corresponding to the medial sagittal section should be the last image in the stack (the one that is the last in alphabetical order if 2D planes are used). If the cortex is at the left, you will need to "flip-X". If the olfactory bulb is at the bottom, you will need to "flip-Y". If the medial sagittal section is at Z = 0, then you will need to "flip-Z". Note that "flipping" in this case means reversing the index of an image dimension, which corresponds to a reflection of the image in that dimension. ? TROUBLESHOOTING If aligning the example data to the provided mouse brain atlas, then the Ex_0_Em_0 channel (containing syto 16 nuclear stain) should be used for atlas alignment and flipped in the X and Z dimensions (see Supplementary Fig. 2).
xiii) Determine whether the channel to be aligned with the reference atlas needs to be cropped.
Typically, the reference image extends to the left, right, top and bottom with no background margins, but the stitched images to be aligned have a margin to the left, right, top or bottom. If these margins are large, they will prevent the automatic alignment from succeeding; thus, the image to be aligned must be cropped to match when performing the automated alignment. Note the X-start and X-end, Y-start and Y-end, and Z-start and Z-end (if whole planes need to be cropped) coordinates of the image after cropping using FIJI to examine the images.
CRITICAL STEP These cropping coordinates apply to the image before flipping.
CRITICAL STEP If using the example data, make sure that Ex_0_Em_0, the syto 16 channel, is rescaled and used for atlas alignment.
xv) Align the rescaled image to the reference using Elastix. If using a custom reference image in the same example scenario presented in step C xiv, then the following command would be used: sitk-align --moving-file /data/downsampled_flip-x_flip-z_clip-y-0-9100.tiff --fixed-file /reference/reference.tiff --fixed-point-file /reference/points.json --xyz --alignment-point-file /data/alignment.json CRITICAL STEP Substitute the name of your reference image for "reference.tiff" above and substitute the name you used as the --moving-file in step (C)(xiii) for "downsampled.tiff" above.

? TROUBLESHOOTING
Refine the alignment manually xvi) Use nuggt-align to manually refine the automatic alignment. If using a custom reference image in the same example scenario presented in step C xiv, then the following command would be used: CRITICAL STEP Substitute the name of your reference image for "reference.tiff" above and substitute the name you used as the --moving-file in step (C)(xiii) for "downsampled.tiff" above.
If aligning the full resolution example data to the provided reference atlas, then enter the following command in the Docker terminal window: nuggt-align --port 8999 [--ip-address 0.0.0.0] --reference-image /allen-mouse-brainatlas/autofluorescence_25_half_sagittal.tif --moving-image downsampled_flip-x_flip-z_clip-y-0-9800.tiff --points /data/alignment.json If aligning the downsampled example data to the provided reference atlas, then enter the following command in the Docker terminal window: nuggt-align --port 8999 [--ip-address 0.0.0.0] --reference-image /allen-mouse-brainatlas/autofluorescence_25_half_sagittal.tif --moving-image /data/downsampled_flip-x_flip-z_clip-y-0-1225.tiff --points /data/alignment.json xvii) There are two links that are displayed by nuggt-align in the Docker terminal window. One is the link to a Neuroglancer webpage displaying the reference image and one is a link to the image that is to be aligned. Copy each of the links and open them in separate windows in your web browser. Windows and Mac users should change the container ID in the URL to "localhost" (see step C iii).

xviii)
Refine the locations of each of the fiducial points in the image. This is done by selecting the reference image browser window (e.g. by clicking in it), holding down the "shift" key and typing "N". A red point will appear in both the reference and moving image browsers. You should adjust the point in the moving image browser to correspond with its location in the reference image if it is placed incorrectly. This is done by holding down the "ctrl" key and clicking on the location in the reference image where the point should be. The point can be readjusted multiple times until you are satisfied with the location. After this is done, hold the shift key down and type, "D" (for "done") and hold the shift key down and type "N" to move to the next fiducial point. Repeat the adjustment procedure until all of the fiducial points have been adjusted. ? TROUBLESHOOTING xix) Hold the shift key down and press "S" to save the adjusted alignment.
CRITICAL STEP The location of the refined fiducial points are not saved automatically. The refined atlas alignment progress will be lost if the adjusted alignment points are not saved.
xx) Hold the shift key down and type "W" to warp the image to be aligned to the reference image.
CRITICAL STEP Wait for the message, "Warping complete", to be displayed before doing anything further.
xxi) Add additional points to refine the warping further. Add a point to the reference image by holding the "ctrl" key down and pressing the mouse button while hovering over the location of a discrepancy. Focus the alignment image to this location by holding down the "shift" key and pressing "T" (for "translate"). In the alignment image Neuroglancer webpage, adjust the location of the point by holding down the "ctrl" key and pressing the left mouse button, then hold the shift key down and press "D" (for "Done").
CRITICAL STEP Adding duplicate points in the same location will cause the warping to fail. To avoid this problem, it is helpful to warp the moving image after adding each point to verify that the warping is successful. ? TROUBLESHOOTING

xxii)
Hold the shift key down and press "S" to save the adjusted alignment.
CRITICAL STEP The location of the refined fiducial points are not saved automatically. The refined atlas alignment progress will be lost if the adjusted alignment points are not saved.

xxiii)
In the Docker terminal window, hold down the "ctrl" key and press "C" to exit the nuggt-align program.

xxv)
Use the rescaled alignment file to compute fluorescence statistics of each channel for all brain regions. If using a custom reference image, then enter the following command into the Docker terminal window: calculate-intensity-in-regions --input "/data/stitched_data/channel/*.tiff" --alignment /data/rescaled-alignment.json --reference-segmentation /reference/segmentation.tiff -brain-regions-csv /reference/brain-regions.csv --output /data/results-level-7.csv --level 7 where "channel" represents the folder of the current channel to be analyzed.
CRITICAL STEP the "--level" argument picks the granularity of the segmentation description from 7 (finest granularity) to 1 (coarsest granularity). You can specify multiple levels to be calculated at the same time at little additional computational cost.

Timing
For processing the full resolution example data:  Manually edit the appearance of the "alignment" layer by holding ctrl and clicking the layer name. The shader used for that layer will appear to the right and include a line that is similar to the following: emitRGB(vec3(0, b * toNormalized(…), 0)); Increasing the constant multiplier "b" will make the alignment layer brighter. Cxxi The border of the source image is not aligned with the reference The default amount of allocated shared memory in the Docker container is too low.

Anticipated Results
Upon successful completion of our image processing pipeline, our protocol will yield corrected and stitched multichannel volumetric images of a whole mouse brain hemisphere as well as an alignment with a provided atlas for brain region segmentation. The atlas alignment is used to create spreadsheets in CSV format containing the volume, total fluorescence, and mean fluorescence of each brain region and each channel. These results can be used to create visualizations summarizing the fluorescence in each brain region (Fig. 4c). The reported regions volumes are in voxel units, so the physical volumes will depend on the voxel dimensions used during imaging. Overall image processing pipeline for whole brain analysis. Raw images from LSFM of a SHIELD-processed mouse hemisphere are destriped and corrected for uneven illumination. Destriped images are then stitched into a multichannel volumetric image, which is resampled to match a reference atlas. Point correspondences from an automatic alignment procedure are manually refined to obtain a region segmentation for the full-resolution, stitched image. The region segmentation is then used to quantify mean fluorescence in each brain region.