TissUUmaps: interactive visualization of large-scale spatial gene expression and tissue morphology data

Abstract Motivation Visual assessment of scanned tissue samples and associated molecular markers, such as gene expression, requires easy interactive inspection at multiple resolutions. This requires smart handling of image pyramids and efficient distribution of different types of data across several levels of detail. Results We present TissUUmaps, enabling fast visualization and exploration of millions of data points overlaying a tissue sample. TissUUmaps can be used both as a web service or locally in any computer, and regions of interest as well as local statistics can be extracted and shared among users. Availability and implementation TissUUmaps is available on github at github.com/wahlby-lab/TissUUmaps. Several demos and video tutorials are available at http://tissuumaps.research.it.uu.se/howto.html. Supplementary information Supplementary data are available at Bioinformatics online.


Available demos
TissUUmaps can be used to display many different kinds of point data. We have set up several demos where different tissue and gene expression and properties can be explored.
In situ sequencing in breast cancer slide

For setting up a local TissUUmaps viewer
More detailed information on how to clone and setup your own viewer locally can be found at our github repositor y

Converting images to tiled formats
Since we don't want to use external servers to serve our images, you can convert them to an open pyramidal format where we can see individual tiles and OpenSeadragon can easily load the correct tile for you. It is called Deep Zoom Image.
This image summarizes the process of converting a whole slide image into a DZI. As long as OpenSlide can open the format, then the program VIPS will be able to convert it to a DZI.
VIPS is a super powerful image processing library. It offers a specific command to convert an image to DZI. For example:

Pointing TissUUmaps to your image data
Once you have your tiled DZI image in the computer where you will use TissUUmaps, you can clone this repository. In the HTML file example.html you just need to tell TissUUmaps where your image is. To do this, check the last script tag in the HTML and change the value of tmapp.fixed_file < script > document . getElementById ( "project_title" ).innerText = "Project title" ; $ ( document ). ready ( function () { tmapp.fixed_file = "path/to/mySlide.dzi" ; tmapp. registerActions (); tmapp. init (); }); </ script >

Additional information for those curious
TissUUmaps is composed of HTML and javascript files, the files that you can see in the github repo. When in your own computer, you can right-click on the example.html file and tell it to open with a browser, like chrome, firefox or safari. Your browser will use all the other files to create the TissUUmaps interface and to be able to load, process and display your data.

For setting up TissUUmaps as a service
Web applications that can be accessed from the internet are set up in servers. The servers receive requests, process them and then return to you with your web page.
The internet as we know it runs in its majority on Apache servers. The setup of a web server is out of the scope of this documentation but we suggest the official Apache documentation at https://httpd.apache.org/docs/trunk/getting-started.html Basically a web server is a program that takes a folder in a computer and makes it available to the internet. Once you set up a server, you just need to put the same files as in our previous section so that they can be served.
For example, our server is located at a place called tissuumaps.research.it.uu.se and then we want to serve you our demos, so we created a folder demo where we place copies of example.html that can be served to you.
There are other servers, like NGINX and http.sever in python language that could be used for smaller scale servers, but for safety we recommend Apache.
Cloud services like Amazon Web Services offer the possibility of having your own server in the cloud so that you don't need to set up a physical computer.

TissUUmaps API
Everything that can be done in pure HTML and javascript can be done to extend the functionality of TissUUmaps. However, to make things easier and organized. We have created special utility modules where the core functionality is programmed and additional functions can be found to interact with the interface and with the data itself. Documentation for all the modules can be found here: https://wahlby-lab.github.io/TissUUmaps/docs/ The modules are: dataUtils overlayUtils regionUtils

CPDataUtils markerUtils HTMLElementUtils interfaceUtils OSDViewerUtils
As their names suggest, dataUtils contains functions for dealing with common data interactions. regionUtils deals with functions related to regions.
In order to use the utility modules, we use the developer tools console that exist natively in browsers.

Examples
Changing layer transparency/opacity Everything we draw on TissUUmaps is in a layer, we refer to it as a D3 node.
The overlayUtils module contains all the D3 nodes that are created in the overlay To see the available overlays you can write overlayUtils._d3nodes and press enter, you will see all the existing D3 nodes.
overlayUtils has the function setLayerOpacity which asks for a name and the desired opacity ranging from 0.0 to 1. For example let's say we want all the markers to be 0.5 so that we see what is underneath. (another way to do this is simply by changing the marker size) The following image shows all the nodes in the view. The node that contains the gene expression is called ISS_markers_svgnode . So we tell overlayUtils to change its opacity.
You may also notice nodes starting with the letters "Gr" these nodes contain the markers for specific genes, for example GrISSATCCC contains the markers for the gene with barcode ATCCC. If you want, you can also change the opacity of genes independently.

More examples
We will continuously create scripts and snippets to show our users all the capabilities TissUUmaps can offer to adapt to each need. Be sure to check https://tissuumaps.research.it.uu.se/howto.html to have the latest scripting examples.