FUSION++ Notebook Tutorial

To streamline user experience and broaden accessibility, FUSION++ now integrates a fully managed JupyterHub environment as a core component of its open-source offering. This pre-configured deployment removes the technical barriers to entry, enabling a diverse range of users—from students and computational biologists to clinical and translational researchers—to instantly launch interactive notebooks with full FUSION++ functionality, eliminating the need for complex manual installation or environment configuration.

This integrated environment does not only simplify onboarding but fundamentally accelerates the journey from visual observation to biological discovery. By empowering users to answer the critical questions of “what does it look like,” “what is it doing biologically,” and “where is it happening spatially,” FUSION++ enables the extraction of high-resolution insights across diverse computational settings. As we move toward FUSION 2.0, this ecosystem will continue to evolve, incorporating agentic AI for molecular discovery and expanding support for single-cell spatial omics, further cementing its role as a cross-disciplinary tool for the global research community.

This repository contains a beginner-friendly Jupyter demo notebook for running the FUSION++ pipeline.

Getting Started With The Notebook:

UF HPC - HiPerGator

Use this option if you are working on the University of Florida's HiPerGator environment.

Steps:

1. Open the FUSION++ demo notebook (fusion_demo.ipynb) in the HiPerGator Jupyter environment.
2. Select the FUSION kernel.
3. Go through Table of Contents and Getting Started.
4. Run Initial Setup and Authentication.
5. The notebook is ready!

HuBMAP Workspace

Use this option if you are working inside a HuBMAP Workspace.

HuBMAP Workspaces provide a browser-based JupyterLab environment where users can explore HuBMAP data and run notebooks.

Steps:

1. Open the HuBMAP Consortium Website - portal.hubmapconsortium.org.
2. Open the Data Portal and login to your account.
3. Open My Workspaces and select the Create New button.
4. Configure the workspace by giving it a name.
5. Select the environment JupyterLab (FUSION).
6. Scroll through the Templates and select FUSION++.
7. Click Launch Workspace.
8. Open FUSION_tutorial.ipynb.
9. Run command import fusion.
10. Confirm that a new folder named fusion_demo_notebooks is downloaded.
11. Open fusion_demo_notebooks folder and then open fusion_demo.ipynb.
12. Go through Table of Contents and Getting Started.
13. Run Initial Setup and Authentication.
14. The notebook is ready.

Recommended Workflow

The general workflow of the notebook is:

Initial Setup & Authentication
        ↓
Data Management
(Download / Upload / Prepare Data)
        ↓
Run Analysis Jobs
        ↓
Visualization

Exercises

These exercises are designed to help users practice the complete FUSION++ notebook workflow.

Exercise 1: Access the Workspace and Open the Notebook

Goal: Access either the HuBMAP Workspace or HiPerGator environment, open the FUSION++ notebook, and confirm that FUSION++ is ready to use.

Tasks:

1. Access one of the supported workspace environments (HuBMAP/HiperGator).
2. Set up and open the FUSION++ notebook using the instructions above.
3. Select the correct notebook kernel if required.
4. Run the initial setup and authentication cells.
5. Confirm that FUSION++ imports successfully.

Expected outcome: The notebook opens successfully and the initial setup cells run without errors.

---

Exercise 2: Import Data and Run the Complete Visium Pipeline

Goal: Use data from HuBMAP or FUSION and run the complete Visium pipeline in the notebook.

Tasks:

1. Select a dataset from either HuBMAP or FUSION.
2. Import and prepare the selected data inside the notebook workspace.
3. Run the Data Management section.
4. Run the complete Visium analysis workflow.
5. Confirm that the expected output files and folders are generated.

Expected outcome: The selected dataset is processed successfully, and the pipeline generates output files for visualization and downstream analysis.

---

Exercise 3: Create Custom Plots and Interpret Pipeline Outputs

Goal: Use the pipeline outputs to create your own plots and identify interesting patterns or insights.

Tasks:

1. Locate the output files generated by the pipeline.
2. Use the outputs to create custom plots using the generated results.
3. Add appropriate titles, labels, and legends.
4. Write a short interpretation for each plot.
5. Summarize at least two interesting insights from the results.

Expected outcome: Custom plots are created from the pipeline outputs, and the user provides a brief interpretation of the observed results.