Click the link above to open the workflow in GitHub Codespaces.
A demonstration video for this workflow is available at https://youtu.be/vHjdCAZQhfE
For more information on how to use Bwb, click this LINK.
Pre-print: bioRxiv 2025.05.23.655879; DOI
Scripts from the Biodepot spatial proteomics workflow.
Imaging visualization software is QuPath[1], this workflow uses version 0.5.1. In our workflow, QuPath is used to create QuPath projects, view and modify spatial images.
.groovy scripts require Groovy version >=2.4. Additional installation to install QuPath-related packages to Groovy are also required, obtained from QuPath StarDist extension[2] version >=0.5.0.
Jupyter Notebook with Python 3 kernel is required.
Create a codespace for this repository using the link provided at the top of this README or the green "<> Code" button.
Machine type of at least "4-core" (16GB RAM 32 GB) is required to run this workflow.
When you create a codespace, you will see the VS Code interface launching a copy of the repository.
A startup script will run to set up Docker and Bwb. When complete, you will see in the "PORTS" tab a link with port 6080 available.
Open the link on the browser to view Bwb. The spatial proteomics workflow will be automatically opened.
Open the first QuPath widget and press the blue "Start button. QuPath will launch.
NOTE:
It is recommended to name QuPath projects, images, and annotations without any spaces. Use snake_case, kebab-case, or camelCase for names in the workflow. Otherwise, put names in "quotes" when entering names in widget entries. Open QuPath and create a project.
In the project, load an image to analyze. In the "Add images" popup, click "Choose files" to select the .tiff/.qptiff you want to analyze. For our sample image, the image type is "Fluorescence".
When importing an image to QuPath, the image name is the file name with " - resolution #1" appended. You can remove this appended section, or rename the image name for this image, to something else. NOTE: Changing the image name on QuPath does not change the actual file's name.
Set an annotation for the region in the image to segment and cluster. For an easy annotation option, select the circle button on the top-left section of the interface, and draw a circle on a core.
In the annotation's properties, give the annotation a name.
Going forward, keep track of the names of the image and annotations set in QuPath, as these will be used in the next steps. If any of these have spaces in their names, refer to their names "in quotes".
Run the my_stardist.groovy script with its stardist model using the "QuPath_Segmentation" widget. Pixel size resolution from the source image needs to be provided into the script.
### ENVIRONMENT VARIABLES REQUIRED:
# image_to_segment=<image name in QuPath project to segment>
# core_to_segment=<annotation name in QuPath project's image>
# resolution=<image resolution (e.g., 0.5, 0.27)>
QuPath script -p <QuPath project file> my_stardist.groovyOutputs are segmented cells placed on the QuPath project image.
Run the export-all-cell-measurements_240829.groovy script to export the cell segmentation data from the image to a CSV file using the "Export Data" widget. Script modified from Akoya Biosciences version of StarDist segmentation.
Output is stored in the /data/segmentation/ directory, but you can specify another directory if needed.
# Adjust file path to stardist_cell_seg_model.pb in script if needed
### ENVIRONMENT VARIABLES REQUIRED:
# image_to_segment=<image name in QuPath project to segment>
# core_to_segment=<annotation name in QuPath project's image>
QuPath script -p <QuPath project file> export-all-cell-measurements_240829.groovyExpected output file is all-cell-measurements.csv, containing metrics for each segmented cell in the QuPath project's image.
Use the BWBQuPathClustering.ipynb notebook to use the exported segmentation data to perform unsupervised clustering of cell types using the Leiden algorithm and visualizing the clustering results as Uniform Manifold Approximation and Projections (UMAP) and heatmaps. Inside the notebook, adjust the file path to all-cell-measurements.csv. Set QuPath project image's core/annotation name in the code block df = df[df['Parent'] == '<segmented annotation/core name>'] if you do not want cluster all regions/annotations in the image.
Run all cells in the notebook to execute the analysis.
Expected output file is located in the clustering output folder /clustering/leiden_clustering_export.csv (output directory can be changed in the widget entries), containing cell clustering labels and colors for each cell. Additional outputs for the heatmap and UMAP are stored in the cluster_plots/ folder.
Run import_clusters.groovy to import cell clustering data back into QuPath using the "Import_Cluster_Data" widget. Once finished, QuPath can show the cells with colormaps/masks on the image. Source of the script is inspired from an image.sc post from Mike Nelson. Adjustments inside the script could be required to match the equivalent of def folder = new File("/data/clustering_data_export") for leiden_clustering_export.csv.
QuPath script -p <QuPath project file> import_clusters.groovyOutputs are cluster-colored cells on the QuPath project image.
Raw data files associated with the paper "Graphical and Interactive Spatial Proteomics Image Analysis Workflow" are provided on a Zenodo dataset. DOI is also provided above.
The data files are inside a zip file, the contents of the zip file is listed below:
Bwb_SpatialProteomics_TMA_rawfiles/
├─ 240508_VET_QCTMA2_A2_55p_Scan1.qptiff
├─ BWBQuPathClustering.ipynb
├─ clustering_data_export/
│ ├─ leiden_clustering_export.csv
├─ paper_testdata/
│ ├─ classifiers/
│ │ ├─ classes.json
│ ├─ data/
│ │ ├─ 1/
│ │ │ ├─ server.json
│ │ │ ├─ data.qpdata
│ │ │ ├─ summary.json
│ │ │ ├─ thumbnail.jpg
│ ├─ project.qpproj
│ ├─ project.qpproj.backup
├─ testdata_segmentation/
│ ├─ test_image-cell-measurements.csv
There is one spatial proteomics image file named 240508_VET_QCTMA2_A2_55p_Scan1.qptiff. This is a tissue microarray (TMA) stained by high-plex immunohistochemistry. The TMA contains 8 tissue cores, numbered and labeled in the image below as follows:
- Merkel Cell Carcinoma (MCC)
- Tonsil
- Tonsil
- Breast Carcinoma
- Squamous cell carcinoma (lung)
- Hepatocellular carcinoma (HCC - liver)
- Lung carcinoid
- Colon cancer
The remaining files and directories in the dataset were generated from running the workflow on one of the cores. The selected core (#6, HCC) was annotated on QuPath and named "Test Core" in its properties.
The QuPath project folder generated for the TMA image. From the project.qpproj file, the core's segmentation and colored clustering results (generated at the end of the workflow) are shown in the project image.
The output csv file from running export-all-cell-measurements_240829.groovy on the core. Renamed in post-processing from the default all-cell-measurements.csv name, and placed in its own directory.
A copy of the workflow's Jupyter Notebook; this version has cell block outputs when running the cell segmentation on this core inside the notebook. UMAP and heatmap are shown.
The output at the final step of the Jupyter Notebook, containing the cell clustering results for the image core. This file is used in the import_clusters.groovy script.
[1] Bankhead, P. et al. QuPath: Open source software for digital pathology image analysis. Scientific Reports (2017). https://doi.org/10.1038/s41598-017-17204-5
[2] Uwe Schmidt, Martin Weigert, Coleman Broaddus, and Gene Myers. Cell Detection with Star-convex Polygons. International Conference on Medical Image Computing and Computer-Assisted Intervention (MICCAI), Granada, Spain, September 2018.
All graphical workflows are implemented in the Bwb platform. To learn more about the Bwb platform, please refer to https://github.com/BioDepot/BioDepot-workflow-builder
Biodepot training portal: https://biodepot.github.io/training/
- To stop and start your codespace to save resources, check out https://docs.github.com/en/codespaces/developing-in-a-codespace/stopping-and-starting-a-codespace
- To learn more about free storage and compute time per month for GitHub users on Codespaces, please visit https://docs.github.com/en/billing/concepts/product-billing/github-codespaces
- You can change the size of the Biodepot window by right clicking on the background to bring up the "Resize" menu. To learn more about the Bwb desktop environment, please visit https://biodepot.github.io/training/basic_training/desk_env/
- Please note that the image annotation in the demo video is case sensitive.
- If a certain widget in one of the workflow fails, check the widget's console to see the error menssage. If it is the download widget failing, see if one of the links is no longer available, or rerun the widget if the files are partially downloaded but abruptly stopped before completing.
- Basic window manipulation help at https://github.com/BioDepot/BioDepot-workflow-builder?tab=readme-ov-file#basic-window-manipulations