Skip to content


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation

Mistic: image tSNE visualizer

This is a Python tool using the Bokeh library to view multiple multiplex images simultaneously. The code has been tested on 7-panel Vectra TIFF, 32- & 64-panel CODEX TIFF, 16-panel CODEX QPTIFF, 4-panel CyCIF TIFF, and 44-panel t-CyCIF TIFF images.

Mistic is published at Patterns (2022).

Mistic's GUI with user inputs is shown below:

Figure description: A sample Mistic GUI with user inputs is shown. A. User-input panel where imaging technique choice, stack montage option or markers can be selected, images borders can be added, new or pre-defined image display coordinates can be chosen, and a theme for the canvases can be selected. B. Static canvas showing the image t-SNE colored and arranged as per user inputs. C. Live canvas showing the corresponding t-SNE scatter plot where each image is represented as a dot. The live canvas has tabs for displaying additional information per image. Metadata for each image can be obtained by hovering over each dot.

Features of Mistic

  • Two canvases:
    • still canvas with the image tSNE rendering
    • live canvases with tSNE scatter plots for image metadata rendering
  • Dropdown option to select the imaging technique: Vectra, CyCIF, t-CyCIF, or CODEX
  • Option to choose between Stack montage view or multiple multiplexed images by selecting the markers to be visualised at once
  • Option to place a border around each image based on image metadata
  • Option to use a pre-defined tSNE or generate a new set of tSNE co-ordinates
  • Option to shuffle images with the tSNE co-ordinates
  • Option to render multiple tSNE scatter plots based on image metadata
  • Hover functionality available on the tSNE scatter plot to get more information of each image
  • Save, zoom, etc each of the Bokeh canvases


  • Open a command prompt (or the Terminal application):
    • Download pip. Type:
      • curl -o
      • python3 and wait for the installation to complete
      • Verify the pip installation by typing pip --version
    • pip install mistic

Setting up Mistic

  • Download this code repository or Open Terminal and use git clone

    $ git clone

  • In the Mistic folder, navigate to /user_inputs folder to upload input files:

    • Mistic_code/code/user_inputs/
    • Use the /figures folder to upload the multiplexed images
    • Use the /metadata folder to
      • Upload the imaging markers of interest as Markers_ids.csv and markers.csv.
        • Example files are provided in the subfolders: Vectra, CyCIF, t-CyCIF and CODEX
        • Move the files from the relevant subfolder into the /metadata folder
        • Note: For the Stack Montage option, only the markers.csv file is required
      • Optional uploads:
        • Upload image tSNE co-ordinates as X_imagetSNE.csv
          • If no user-generated tSNE co-ordinates are provided, Mistic will generate a set of t-SNE coordinates to render the images
        • Upload image metadata such as
          • Cluster labels as Cluster_categories.csv
            • If cluster labels are not provided, Mistic will cluster the images using a Bayesian mixture model.
          • Patient_ids as Patient_ids.csv
          • Treatments as Treatment_catgories.csv
          • Patient response as Response_categories.csv
          • If any of these are unavailable, Mistic will use either the randomly-generated or user-provided tSNE points without any color coding i.e. dots are colored in gray.
          • Sample metadata files are provided for reference in separate subfolders for each imaging technique (Vectra, CyCIF, t-CyCIF and CODEX) in the /metadata folder
          • If using the sample metadata, move the files from the relevant subfolder into the /metadata folder

Run Mistic

  • Open a command prompt (or the Terminal application), change to the directory containing /code and type:

    • bash
    • This runs a bokeh server locally and will automatically open the interactive dashboard in your browser at http://localhost:5098/image_tSNE_GUI
    • Enter the imaging format, montage or multiplexed views and other user options on the GUI and click Run.
  • Examples for running Mistic:

  • If you get an error: Cannot start Bokeh server, port 5098 is already in use, then at the Terminal, issue:

    • ps -ef | grep 5098
    • You should see a line similar to the one below on the Terminal: 55525 12519 11678 0 1:22AM ttys004 0:57.81 /opt/anaconda3/bin/python /opt/anaconda3/bin/bokeh serve --port 5098 --show image_tSNE_GUI where the 2nd term is the process id. Here this is '12519'.
    • Use this process id to kill the process: kill -9 12519

Additional information