BoReMi

Bokeh-based jupyter-interface for Registering spatio-molecular data to related Microscopy images.

Play with the example data by clicking on the binder badge below!
No need for installation/ setup!

Publication

We are excited to share that BoReMi has been published in PLOS Computational Biology! Please access the paper for a deeper look into its development, methodologies, and the ways it can support your research in spatial image analysis. We hope it is helpful and inspiring!

Example Data Sources

• Sample HE images (Repository Folder):

  1. Mouse brain H&E images

• Sample DAPI image (Repository Folder):

  1. Vizgen MERFISH mouse brain DAPI image

• Sample Spatio-molecular data (Repository Folder):

  1. Vizgen MERFISH mouse brain coordinates

  2. Vizgen MERFISH mouse brain annotations

Reference Registration Parameters to recreate HE/DAPI registrations from the Binder

• Repository Folder

Reference Analyses Notebooks

• Repository Folder

Computational Requirements

BoReMi has modest resource requirements: On a Surface Pro 7 tablet (Intel Core i5-1035G4, 16GB memory) it runs smoothly and opens the Merfish mouse brain dataset with ~83,000 cells (subsampled to ~10,000 cells for visualisation) and images with ~100 MP in about two minutes for PNG images and in about 1 minute for JPEG images. Downsampling the number of displayed data points to ~10,000, while all data points are being processed, ensures lag-free interaction even with modest computational resources.

Quick Start Guide: Setting up BoReMi on a Cluster or a Local Environment

1. Notebooks: To set up BoReMi, two notebooks are provided in the BoReMi directory on the repository's main page: GUI.ipynb and Functions.ipynb.

   • GUI.ipynb serves as a graphical user interface.
   • Functions.ipynb contains all the necessary functions.

2. Obtaining the notebooks: There are two methods to obtain the notebooks.

   • Direct Download: Click on "Code" at the upper right corner of this repository and select "Download ZIP". Move the downloaded .zip file to the desired directory on your local machine/cluster and unpack it.
   • Git Clone: Use the command git clone https://github.com/jaspreetishar/BoReMi.git to clone the repository and extract the notebooks onto your local machine/cluster.

3. Required Libraries/Packages/Extensions: Ensure you install the necessary libraries, packages, and extensions specified in the environment.yml file located on the repository's main page using the following guidelines.

   • Navigate to the Project Directory

     • First, navigate to the root directory of the project. For example:

       cd path/to/BoReMi

       Replace path/to/BoReMi with the actual path to the cloned repository.

   • Create a New Virtual Environment and Install Dependencies

     • To avoid conflicts with existing versions of the required libraries/packages/extensions, it is recommended to create a new virtual environment. For instance, you can use Conda to create this environment and install all the dependencies specified in the environment.yml file using the following set of commands:

       conda env create -f environment.yml
       conda activate boremi_env
       python -m ipykernel install --user --name=boremi_env

     The third command will allow you to select the boremi_env kernel when running Jupyter Lab.

   • Update Regularly

     • Periodically check for updates to the environment.yml file and update your virtual environment accordingly to stay compatible with the latest features and fixes:

       conda env update -f environment.yml

   By following these steps, you will ensure that BoReMi runs smoothly without any library conflicts, improving user experience.

4. Accessing the GUI: To use BoReMi, open the GUI.ipynb file by typing the following in the terminal or an Anaconda command prompt:

   jupyter-lab path/to/BoReMi/BoReMi/GUI.ipynb

   Replace path/to/BoReMi/BoReMi/GUI.ipynb with the actual path to the GUI.ipynb file present in the BoReMi directory of the cloned repository.

5. BoReMi Usage: Follow the provided guidelines and instructions inside GUI.ipynb. Begin using the tool and explore its functionalities.

6. Exit: To exit the virtual environment, type the following in the terminal or an Anaconda command prompt:

   conda deactivate