User Guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 18

Download
Open PDF In Browser	View PDF

User Guide
for the streamlined, less biased, but still manual
registration of fluorescent tracks to the
Allen mouse brain Reference Atlas
Software by Nick Steinmetz & Philip Shamash in the laboratory of Kenneth Harris & Matteo Carandini at UCL

Table of Contents
1. Data & code to have on hand (2)
2. Pre-processing (3)
3. Navigate to the correct slice in the reference atlas (6)
4. Transform and overlay histology to match reference (8)
5. Select dye track locations (11)
6. Visualize Probe Track (13)
7. FAQ (18)

1

1. Data & code to have on hand
 Imaged slides of brain slices with fluorescent track(s)

 Microns per pixel of these images
 Prior knowledge of the number, entry point, and insertion
depths of all probes is highly recommended
 Have MATLAB installed (R2017 used for all testing),
preferably on a Windows computer
 Have a (computer) mouse with a scroll wheel
 Get the code at github.com/cortex-lab/allenCCF and add this
folder with subfolders to your MATLAB Path
 Additionally, download the reference atlas data at
http://data.cortexlab.net/allenCCF/ and suporting code at
https://github.com/kwikteam/npy-matlab

2

2. Pre-processing
Go from an unprocessed image of many brain slices, to a folder of nice-looking,
properly oriented, and ordered brain slice images (skip if you already have this)

 Open ProcessHistology.m
 Enter the folder containing the histology slide images, the
folder the processed slice images should be saved to, the
name of the histology slide images in anatomical order, and
a few other parameters
o If your images are downsampled to the correct size (10 microns
per pixel), set use_already_downsampled_image = true

 Run this cell to initialize parameters
 Run the following cell to downsample and adjust the large
histology images (downsampling very large images may take
a minute); Instructions should appear on adjusting the image
o Scrolling shifts the max or min pixel intensity saturation
points; space bar shifts between control of the max vs.
the min; ‘c’ shifts to the next color channel; arrows
move to the next image; etc.

3

Before (above) and After (below) preprocessing

 When done with all slides, run the following cell (‘CROP AND
SAVE SLICES’). More instructions will appear in the console.
o Select a slice image by clicking and dragging around it; try to go in
order, either anterior to posterior or posterior to anterior
o The slices needn’t be perfect; they will be after the next, and last,
pre-processing step. Cropping too big is ok.

4

o Do so for each desired slice on the slide – for now, the most
important is to crop the entire slice (and press ‘space’ to move to
the next histology slide)

 Finally, run the last cell in ProcessHistology.m
o Instructions appear. Most important: scroll to get the slice
oriented straight, press ‘f’ to reflect the slice horizontally (so all
slices are in the same orientation – a necessary step for the
following steps), press ‘c’ to crop the image further (necessary if
the image is larger than 800 x 1140), and left/right arrows to save
and navigate between slices

Before (left)
After (right)

 Done! Now you should have the large images saved in your
designated ‘save_folder’, as well as a subfolder in there called
‘processed’ containing the processed slices, in order.

5

3. Navigate to the appropriate slice in the
Allen reference atlas
With the folder of processed images, find each corresponding slice in the
reference atlas; or search the atlas without the slice images in a simpler GUI

 Open the file AlignHistologyToProbe.m and enter the folder
with the ordered, processed slices.
o if you did not process the images through the above process, you
may still need a similar naming convention (Name of Animal_slide
number.slice number.tif) – e.g. ‘Richards_2.12.tif’
o You will need to first download the reference atlas structural
volume, annotation volume, and annotation data. This can be
done on http://data.cortexlab.net/allenCCF/
 Download the structure tree ending in ‘2017.csv’
o You must also download and add to your path the following
repository: https://github.com/kwikteam/npy-matlab
o Enter the file paths of the annotation volume in the line starting
‘av = …’; of the structural volume in the line starting ‘tv = …’; and
of the annotation data in the line starting ‘st = …’
o Run the file. The first time, it will take a while to load the
reference brain data.

 Note that the simpler function allenAtlasBroswer(…) can be
used to find slices in the reference atlas, without any
accompanying GUI that uses the histology images
(Slice Viewer). It is not compatible, however, with sections 4 -6.
 Basic instructions appear.
o On the Slice Viewer, press ‘left’ or ‘right’ to switch slices.
o On the Atlas Viewer, scroll to move through coronal slices. Press
‘up’ to make scrolling now adjust the angle of the slice, along the
dorsal-ventral axis or press ‘right’ to make scrolling now adjust the
angle of the slice, along the medial-lateral axis. Using these
features, navigate to the approximately correct slice as seen in the
Slice Viewer
6

7

4. Transform and overlay histology to
match reference
We’ve found a similar slice in the reference atlas, but room for error remains –
transform and overlay the slice with the reference to get even more exact

 When you’re done exploring the brain regions on this slice with
the mouse pointer, or by pressing ‘o’ to highlight regions (and
pressing ‘o’ again to turn that off for this next bit), press ‘t’ on
the Atlas Viewer to initialize a transform
 Also press ‘t’ with the Slice Viewer figure selected, so that both
figures are in transform mode.
 Select salient points on one figure, and then the corresponding
point on the other. 10-20 points should do, depending on the
slice.
o You can always add more points later
o Press ‘d’ to erase the current transform and start over

8

 Press ‘h’ to transform and overlay the histology, and thereafter
switch between 3 viewing modes. This also saves the
transform.
o Press ‘a’ to toggle region annotation outlines. Now you can slightly
alter the reference outlines position (using the scroll bar and
arrow keys as before) and/or alter the transformation by clicking
more points in both figures and pressing ‘h’ again



Press ‘h’ 3 times to return to present view
While pressing ‘h’ saves the transform, after changing the atlas
position or angle, you can press ‘x’ to save that change
After pressing ‘h’ and ‘a’;
Arrow shows a minor
improvement made by
adding 2 points to the
transform and modifying
the angle of the slice in
the reference atlas

After improving the fit

9

 To move on to the next slice, use the left/right arrows on the
Slice Viewer.
 Then, you can press ‘h’ to get to reference move, scroll to the
slice in the atlas corresponding to your new histology, and
repeat the process.
 However, there is a more streamlined way to move between
slices on the Atlas Viewer: press ‘left’, and then you can scroll
between the slices you’ve transformed! If a slice is not yet
transformed, it will take you to the reference view so that you
can do so.
o It is not necessary to transform every slice, if for example two
slices show redundant information about the probe
 Or, to bring up a particular transform that has been saved,

navigate to that slice in the Slice Viewer and press ‘l’ after
selecting the Atlas Viewer

10

5. Select dye track locations
Localize the dye track(s) in the histology

 Navigate through transformed slices on the Atlas Viewer by
pressing ‘left’ and then scrolling. Press ‘a’ to see the region
boundaries

 Press ‘p’ to toggle probe point mode. Now you can click points
on the figure corresponding to the probe track.
 Press ‘n’ to add a probe (up to 11 probes), and press ‘p’ to
toggle between them (check the console to see which probe
has been selected)
 Press ‘d’ to delete the most recent probe point from the
currently active probe.
 Press ‘s’ to save the probe points for probe visualization
 Press ‘l’ twice (once loads a transform) to load saved probe
points (or ‘w’ to launch probe view mode – see below)

11

 Pressing ‘p’ will also bring up a third window: the Transformed
Slice & Probe Point Viewer. Pressing left and right will move
through the slice images (transformed, if applicable)
o This allows you to see surrounding slices with their probe points,
to help determine which probe a particular fluorescent track
belongs to

12

6. Visualize Probe Track
See the fruits of your labour

 Load saved probe points by pressing ‘l’ twice, and toggle
between the probe of interest by pressing ‘p’
 Press ‘w’ to toggle probe viewer mode for the currently
selected probe (will load probe 1 if none is selected or loaded).
o This will show a best fit line, the slice that this line lies along, all
the clicked probe points (with proximity from the best fit indicated
by brightness)
o Feel free to press ‘o’ to see the probe intersects, or to scroll and
explore nearby slices

 …
o Clicking on or around the probe track will find the point in the
histology images closest to the clicked point, and display it in the
Transformed Slice & Probe Point Viewer window

13

 Open displayProbeTrack.m and enter some parameters
o processed_images_folder and probe_save_name_suffix should be
the same is those used in AlignHistologyToProbe
o probes_to_analyze: a list of the probes you would like to analyze
found in the file set by the two aforementioned variables. ‘all’ will
analyze all saved probes; [1, 5] will analyze the 1stand 5th probes
o probe_lengths is a list of the known insertion depths of all probes
saved in this file (if you are not analyzing some probes, you can set
their depths to 0). Setting it as one number sets all probes to that
depth.
o active_probe_lengths is the distance from the bottom tip of the
electrode that contains recording sites
o probe_radius is the range in microns around the best fit line
corresponding to the probe that will be queried to estimate a
confidence metric (distance from best fit line to nearest different
brain region – see plot below)
o show_parent_category will also include a confidence metric for
2nd-order parent regions (e.g. prelimbic area vs. prelimbic area
layer 6a) – this feature is slow.
o probe_past_tip_to_plot: how far past the estimated tip of the
probe should be plotted? (see plot below)
o scaling_factor: set the scaling between the probe length that you
know from the insertion depth and the depth in the reference
atlas brain. 1.0-1.2 is a reasonable range. Aligning the
electrophysiology to known landmarks (e.g. white matter) can also
help to estimate this value. Set this variable to ‘false’ to use the
most ventral clicked point as the expected electrode tip, and to
then derive the scaling factor automatically.
o show_region_table: output and show a borders_table with data
on the regions displayed in the plot (see below): their upper and
lower borders in microns from the surface, acronym, name, area
index as represented in the downloaded annotation volume
 see all abbreviations and hierarchical region structure is the
downloaded csv file ‘structure_tree_safe_2017.csv’
14

example parameters for a brain with 11 probe tracks

Example table output from probe 4 (the dark green probe below)

15

All probes overview output (Brain View), using scaling_factor = 1.1

Same data, using scaling_factor = false (get probe scaling from histology)

16

Probe 4 (dark green track
in Brain View above)

Region abbreviations,
as defined in
borders_table and
the downloaded .csv
file

Start of active
recording sites
on the probe

Plot starts at brain surface

Confidence in parent region
(here, somatosensory cortex)
shown in dark gray

show_parent_category
set to false for this plot

Here, probe tip was
calculated by the insertion
depth and scaling factor
Distance to the
nearest brain region
in um along the plane
17
orthogonal to the
probe, as a measure
of confidence

Here, 300 um
past probe tip
plotted (distances
are in reference
atlas space)

7. FAQ
Frequently asked questions

 There’s a bug or error – what should I do?
o Close all the figures and re-start the file

 That doesn’t work – what should I do?
o Feel free to raise an issue at

github.com/philshams/allenCCF
 Is there a tool to know how I should orient my probe, before

I do the recording?
o Andrew Peters crafted one called allen_atlas_probe.m,
using the same reference data as above (arrays called
tv, av, and st). This file can be found in the repository.

18



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Page Count                      : 18
Language                        : en-GB
Tagged PDF                      : Yes
Author                          : Experiment
Creator                         : Microsoft® Word 2016
Create Date                     : 2018:07:23 16:09:22+01:00
Modify Date                     : 2018:07:23 16:09:22+01:00
Producer                        : Microsoft® Word 2016

EXIF Metadata provided by EXIF.tools