Tissue Mapper Software Installation/Setup
Have Tissue Mapper installed and licensed on your workstation of choice through an MBF Bioscience representative. After launching Tissue Mapper, set an API key to your profile to pull the ontology list from SciCrunch to annotate your organ of choice with the curated SPARC anatomy terms.
See Link for Tissue Mapper guide : ttps://www.mbfbioscience.com/help/tissuemapper/Default.htm
SECTION 1: IMAGE STACK ASSEMBLY IN TISSUE MAPPER
The image stack is assembled from individual block face images (.jpg) taken during the cryosectioning process.
STEP 1.1: Open the Tissue Mapper program, click FILE -> OPEN -> IMAGE STACK
STEP 1.2: Locate the block face images and select all images being used to create the image stack and click Open.
STEP 1.3: A dialog box appears to confirm the order of the images chosen. To rearrange the order, click and drag the corresponding file(s) into place. When done, click OK.
Note: When labeling and saving the block face images always use a multiple-digit numbering system to assure proper ordering, e.g., image_001.jpg, and not image_1.jpg.
STEP 1.4: In the Image Scaling window, the default values will be displayed. Insert the appropriate X, Y and Z scaling values (see link for Tissue Mapper guied above). When done, click on the box at the middle bottom “Create sections for this stack” and click OK. Click ”Override X and Y scaling” to edit the scaling values. In the section ”Source of X and Y Scaling”, the option ”User Specified” should be automatically chosen. Click on the displayed Z value to specify the distance between the images.
STEP 1.5: The Welcome dialog box will prompt you to select the appropriate items from the drop-downs. Click “Begin” when done.
Note: Subject Information: SPECIES, SUBJECT ID, SEX, and AGE are metadata that are stored in the XML annotation file associated with this image stack.
Note: Criteria for anatomic terms:
ORGAN: The organ term list you are interested in annotating with.
SPECIES: The species you are interested in annotating with.
PARCELLATION: The atlas parcellation scheme you are interested in annotating with. If you don't see the correct parcellation, select Species Independent from the drop down menu.
Note: Manually entering information about the tissue sample occurs only once when an empty document is created to annotate the image stack. In the subsequent runs of Tissue Mapper with the generated annotation XML file, the metadata dialog will populate automatically from the annotation information stored in the XML file.
STEP 1.6: At this point, the first image of the image series is visible, as well as the list of images visible in the Image Organizer, and each section is listed in the Serial Section Manager. Save the image stack as a JPX file, before proceeding further. Click FILE -> SAVE AS -> IMAGE STACK>STACK. Select ”MBF JPED2000 stack file (*.jpx,*jpf)” in the ”Save as type:” pull down menu. In the Compression, drag the bar all the way to the right towards Lossless.
Note: Do not click any of the blank white boxes at this time.
STEP 1.7: Create a blank annotation file (XML format) and link it to the JPX image stack. This file will hold all the annotation information, e.g., contours, cell location markings, etc., that is associated with the image stack. Click FILE -> SAVE AS -> DATA FILE in Tissue Mapper, and choose “XML Document File (* .xml)” in the “Save as type:” pull down menu.
Note: There is an alternative approach to create a blank annotation XML file if the Tissue Mapper program was closed after the JPX file was created and saved in Step 1.6 above. Open Tissue Mapper program and simply drag and drop the JPX file into the black display screen, and return to step 1.7 above to create a blank annotation XML file associated with that JPX image stack.
SECTION 2: CONTOURING THE BLOCK FACE IMAGES
STEP 2.1: Drag and drop the annotation XML file into the blank display screen to open the file. Make sure that “Load Images with Data File” check box is selected so that the corresponding image stack is loaded into Tissue Mapper.
STEP 2.2: Select “Begin” in the Welcome Screen that shows the Subject information and the Criteria for the anatomic terms that were entered in Step 1.5 above. This information can also be edited at this step. You should see the image stack loaded into Tissue Mapper with the image of the first section displayed along with the list of serial sections.
STEP 2.3: Select the Trace Tab. Within CONTOURS section of the menu ribbon, click on drop down menu for Contour selection and select the appropriate anatomical term that corresponds to the structure to be contoured.
STEP 2.4: Within the CONTOURS section of the menu ribbon, select “Freehand”. You are now ready to draw a contour on the image shown. The cursor should change to a “+” sign to confirm that you are in the freehand contouring mode. Right-click on the image and select “continuous tracing”. Now you can begin contouring the image.
STEP 2.5: Left-click and drag the mouse (or use stylus on a touch screen) to draw a contour on the image. After completing the line drawing, select “Close” from the CONTOURS section to close the contour. In the EDIT section, click on “Select objects” and click on the contour to visualize the points that make up the contour. Any fine adjustments to the contour can be made at this stage, including adding, moving, and deleting points.
Note: Right-clicking on any of the points will bring up a menu for adjusting the point position and other properties. Right-clicking on the contour line will bring up additional menu for fine-grain adjustments including inserting new points, rotating, shrinking, moving, changing color, etc.
Note: The right-click menu for the contour line is particularly useful for copying the contour and pasting it in the next serial section image to streamline the contouring process across serial sections in the stack.
SECTION 3: ALIGN BLOCK FACE AND SECTION IMAGES TO MARK SAMPLES ON THE BLOCK FACE IMAGE (EXTERNAL TO TISSUE MAPPER)
Note: The above steps use block face images and not the actual sectioned and stained tissue/slide image in the Tissue Mapper software. This necessitates the use of an external program to first align the images of the tissue section and the block face (PowerPoint, for example). Such alignment will allow placement of markers corresponding to the cells of interest on the block face image in the approximate area where the cells of interest are located.
STEP 3.1: Open an image of the sectioned/stained/sampled tissue section using Microsoft PowerPoint.
STEP 3.2: Insert the corresponding block face image into the same PowerPoint slide.
Note: You can use your already contoured block face image of that same section in Tissue Mapper, or use the original block face image that has not been contoured yet.
: Turn down the transparency of the tissue image and overlay it over the block face image to get a best alignment, possibly by adjusting the image sizes. Once you have an appropriate alignment of the images, you can then use the tissue section image as a reference to begin marking the cells of interest on the block face image.
Note: Depending on the tissue type, tissue mounting, and the subsequent dehydration and staining process, one should expect some distortion that needs to be accounted for when aligning the tissue section image with the block face image.
STEP 3.4: With the tissue section aligned over top the block face image to the best of your ability, begin to mark the samples directly onto the images.
IMPORTANT: As stated previously, this will most likely not be an exact match and one should account for any variability. In most cases the block face images will indicate the corresponding structures you see in the stained tissue section to allow for accurate placement.
STEP 3.5: Move the transparent tissue section behind the block face image and snip the now-marked block face image to use as reference for marking these cells in the Tissue Mapper program.
Note: The present protocol involves repeating the process of marking the cells of interest on the block face images, once external to Tissue Mapper software, followed by annotation within the Tissue Mapper. This approach is required as, at present, there is no way to align tissue section images with the block face within the Tissue Mapper program.
SECTION 4: MANUAL MARKING OF SAMPLES ON BLOCK FACE IMAGES WITHIN TISSUE MAPPER
IMPORTANT: The order of placement of markers can be important to streamline downstream annotation to connect with external data sets corresponding to the cells of interest, e.g., molecular data from spatially-tracked single neurons. To associate the markers with external data, e.g., cell/sample identifiers with molecular information, it is important to start with the order of sample identifiers and place the markers in that order. This leads to an annotation XML file in which the XML code lines for the individual markers are in the order of marker placement. Downstream XML processing can be performed to add marker ID information to the XML code lines. This approach is the workaround to the Tissue Mapper limitation that does not allow labeling the individual markers in the user interface, but will display that information, if present, in the XML annotation file.
STEP 4.1: Use the annotated block face image with markers from Step 3.5 as a guide to mark these cells of interest directly in the Tissue Mapper program. In the Markers toolbar, select a marker to represent the cells of interest. Pan and zoom the block face image in the Tissue Mapper to identify the region corresponding to the locations of the cells of interest. Click on the location to place a marker at that location, one marker per cell or feature of interest. Repeat this step until all the cells of interest are marked in the corresponding block face images throughout the stack.
SECTION 5: ALIGNING CONTOURS AND MARKERS
Note: Alignment of the contours has to be done after marker placement in Section 4 above. This is because, the cell location markers are using the tissue context as a reference in Sections 3 and 4 above. Alignment of contours may involve shifting the relative locations of contours across the image stack and hence will lead to erroneous positioning of cell location markers within the contours. This sequencing of marking and contour alignment may not be as critical in cases where the block face image acquisition system is in a stable position relative to the tissue block in the cryostat, minimizing the shift and distortion in the contours across the stack.
STEP 5.1: In the Serial Section Manager, start from the first section and use “Select objects” and click and drag the cursor across the image to select all the contours and markers on the image. IMPORTANT: Do NOT press “select all” in order to do this because doing so will select every contour in the entire stack and moves them all at once in the next step, which is not visible in the user interface and creates an erroneous alignment.
STEP 5.2: In the Serial Section Manager, select the “Show current section” icon. This will display all the contours within the stack and display them on the current section being viewed.
STEP 5.3: Right click on the block face image and select “Move selected objects” to shift all the selected data to be in appropriate alignment with the rest of the contours in the stack. This step can be repeated for any particular section that may be out of alignment with the rest of the stack.
Note: The above steps 5.1 to 5.3 only move the contours and markers and not the actual underlying block face images. This can be seen in the image view of a section whose contours and markers were shifted. In this case, the contours and markers no longer overlay the underlying image (which was likely shifted due to a shift in the position of the image acquisition system). A representative image with shifted contours and markers is shown below.
Note: An alternative approach is to align the images in the first step using Tissue Maker software and then import that image stack into Tissue Mapper approach. That approach entails different software and computational requirements as every image in the series has to be contoured and aligned in order to build a stack, and may be relatively more complicated than the present approach which focuses on contouring a select of images that may be relevant to downstream data analysis and linking with external data sets such as spatially-tracked molecular data from single cells.
SECTION 6: 3D STACK VISUALIZATION OF CONTOURS AND SAMPLE MARKERS
STEP 6.1: Deselect the “eye” icon in the Image Organizer window to hide the images in the 3D view to be constructed. This will allow for a smoother and quicker interaction on regular desktop workstations with limited computational capability. To visualize all the contours and markers in the 3D viewer, press the "3D Visualize" icon in the VIEW section. A separate window will open to show the interactive 3D reconstructed model of the tissue contours along with the markers for the cells and features of interest. The 3D viewer can be used to selectively show, hide, and edit specific contours and markers, change colors of these annotation features, create video clips of the data, and export the 3D representations.