Running

Warning

GitHub uses cookies to provide services and site functionality. For more information, see the GitHub General Privacy Statement.

Overview

Heatmapper can run in three different situations, all with their own advantages and disadvantages to consider. The first two methods run within your web browser, a WebAssembly, client-side version, and a PyShiny, server-side version. These are the recommended version to use, and the application will automatically select an appropriate version depending on which sub-project is being loaded, and what the capabilities of the client system and browser.

Heatmapper can also be run as a standalone application, but requires more setup to correctly install dependencies.

WebAssembly

WebAssembly is a web technology that allows for websites to be run as native machine code on the client browser. Heatmapper uses the Pyodide Python Distribution via ShinyLive to run its applications in this manner. WebAssembly brings considerable benefit over the traditional server-side model:

1. Applications are run on the client computer. This brings many benefits:
   1. There is no contention for server resources. All processing is done on the client computer, so if many users are accessing Heatmapper, it won’t affect the speed of your instance of the application once its been fetched from the server.
   2. “Uploaded” files do not need to be actually uploaded to a server, but are instead retrieved from the local disk by the browser. This saves not only bandwidth, but also time.
2. Speed: WebAssembly is a binary format, and programs can run at near-native speeds. Running the WebAssembly version of Heatmapper locally is typically faster than running the Python source directly.
3. Ease of Use: WebAssembly is still run within the browser, which means the client doesn’t need to install dependencies or anything besides a browser.
4. Security: WebAssembly is executed within the browser, which brings numerous security benefits.

There are also some disadvantages of WebAssembly that should be noted:

1. Initial Loading Time: To run Heatmapper with WebAssembly, the browser will need to fetch the source files, initialize an environment to run it, and setup any dependencies that the program needs. This results in a loading period, which—depending on processing and network speed—can take a few seconds. Fortunately, these can be remedied through caching, so reloading the application or opening another one will usually take less time.
2. A client-side application does all the processing on the client computer. For computationally expensive tasks or large input files, this can exhaust your system resources.

Heatmapper will automatically determine if your system can run WebAssembly, and will serve you the WebAssembly version by default. If the URL of the project is at https://heatmapper2.ca, you’re running Heatmapper in WebAssembly.

Server-Side PyShiny

If your system lacks the capabilities to run Heatmapper in WebAssembly, or the application doesn’t support running within that environment, there is also an instance of Heatmapper hosted as a typical server-side application; this setup is identical to how the old Heatmapper was deployed. This is a compatibility version, so it’s recommended to use the WebAssembly version unless you either lack the minimum requirements, or do not have the system resources to run the application client-side.

Heatmapper is hosted Here, and you can access each heatmap application with the following table:

Heatmap	Works in WebAssembly?	URL
Expression	Yes	http://server.heatmapper2.ca/expression
Pairwise	Yes	http://server.heatmapper2.ca/pairwise
Image	Yes	http://server.heatmapper2.ca/image
Geomap	Yes	http://server.heatmapper2.ca/geomap
Geocoordinate	Yes	http://server.heatmapper2.ca/geocoordinate
3D	Partially	http://server.heatmapper2.ca/3d
Spatial	No	http://server.heatmapper2.ca/spatial
Spectral	Yes	http://server.heatmapper2.ca/spectral

As with WebAssembly, there are both advantages and disadvantages of this approach. Some advantages include:

1. Computation is off-loaded to the server. This means the connecting computer does not need to process any data, so the server can be faster so long as its not congested. Additionally, there is no wait-time when connecting to the site besides network latency.
2. Compatibility: Almost every system will be able to use the Server version of Heatmapper.

However, there are some significant disadvantages as well:

1. Because the server’s resources are being shared by all connected users, Heatmapper’s performance and response speed can be variable. If resources are strained too heavily, WebAssembly will likely be faster even on slow computers.
2. Files need to be uploaded to the server before they can be processed. For large files, this can lead to a significant delay.
3. Congestion, maintenance, or updates to the server can lead to downtime; for WebAssembly, which essentially downloads your own version of Heatmapper to be run for your computer, this is not a concern.

Client-Side PyShiny

Finally, Heatmapper can be run as any regular Python application on your local computer. This combines the best of both worlds, with a local program without worry of server-congestion, and with near-universal compatibility. However, this approach requires setup of Python and Heatmapper’s Dependencies, which are outlined in this section. For most users, this is not a recommended way of running Heatmapper.

Firstly, you’ll need to download Python. Heatmapper is programmed with Python 3.11. Some libraries used by Heatmapper may not be compatible with older Python versions, and Python 3.12 is not currently supported.

It’s highly recommended to setup a virtual environment (or venv), as this will ensure pip is available, and prevent cluttering/conflicting with any system packages. To setup a virtual environment with python:

python -m venv [path]

Where [path] is the path where the virtual environment should be created. Note that depending on your system, python may be named python3, so you may need to change the command accordingly. Once the environment has been created, you’ll need to activate is so that pip and python are linked to the virtual environment’s version:

# Unix
source [path_to_venv]/bin/activate

# Windows
[path_to_venv]\Scripts\activate

To exit from the virtual environment, simply run deactivate. From here, we can now setup the required dependencies for Heatmapper. Each application has slightly different dependencies, so you can decide what needs to be installed depending on your use-case. The Common row contains dependencies across all the applications:

Setup	Dependencies
Common	pip install shiny shinylive matplotlib scipy pandas openpyxl
Expression	-
Pairwise	pip install biopython
Image	-
Geomap	pip install folium branca certifi xyzservices
Geocoordinate	pip install folium branca certifi xyzservices scipy
3D	pip install pyvista trame vtk trame-vtk meshio pywebview trame-vuetify nest_asyncio py3Dmol
Spatial	pip install squidpy anndata scanpy scikit-misc
Spectral	pip install pymzml

Next, you’ll need to download Heatmapper from GitHub. You can either download it from https://github.com/WishartLab/heatmapper2, clicking on the Code button, and then Download ZIP, or through git:

git clone https://github.com/WishartLab/heatmapper2.git

Finally, navigate into the heatmapper2 folder. If you want to deploy all the applications, and are running UNIX/MacOS, you can simply chmod +x deploy.sh and run ./deploy.sh This will deploy each application, starting at Port 8000 and incrementing based on their order in the Navigation Bar. Opening a browser, you can point to http://localhost:8000 to access the application (Note, the Navigation Bar within the application will point to the hosted version.)

If you’re using Windows, or only want to run a few applications, you’ll need to navigate into heatmapper2/{project}. You can either run the application as Python, or as a WebAssembly server:

• For Python: enter the src directory and run shiny run -p [port], where port is the port to open on the local computer. If omitted, it defaults to 8000.
• For WebAssembly. simply run python -m http.server --directory site --bind localhost [port] with the desired port.

Some of Spatial’s example files are stored using Git’s LFS extension. To fetch those, you’ll need to download the repository through the git command mentioned above, and install the extension from here. Then, run the following commands from the heatmapper2 directory:

git lfs install
git lfs checkout

The files should then be populated with their content.