Spatial Biology Image Analysis Pipeline

Overview

This repository contains the code for a Spatial Biology Image-Analysis Tool designed to process multiplex fluorescence microscopy images with the goal of studying tumor biology. The tool is specifically focused on analyzing tumor invasion fronts, immune infiltration, and cellular interactions within the tumor microenvironment at single-cell resolution.

The tool integrates high-plex fluorescence imaging techniques with advanced computational methods, including deep learning-based models and spatial analysis metrics. This pipeline helps researchers explore the spatial heterogeneity of tumors, identify molecular gradients, and understand the complex relationships between different cell populations in the tissue.

The methodology incorporates a modular Python pipeline, along with pre- and post-processing steps, to analyze a wide range of cellular markers. This tool is particularly useful for multiplexed immunofluorescence data generated by cyclic staining technologies such as MACSima™.

Context and Motivation

Cancer is a highly complex and dynamic disease, characterized by intricate interactions between tumor cells and their surrounding microenvironment. Traditional histological methods, like Hematoxylin and Eosin (H&E) staining, provide valuable information about tumor architecture but fall short when it comes to molecular-level understanding. Modern multiplex fluorescence microscopy offers a solution by allowing simultaneous imaging of dozens of cellular markers within a single tissue section, preserving spatial relationships and offering detailed insights into tumor biology.

This pipeline is designed to address the challenges of spatial biology in oncology, specifically focusing on tumor invasion fronts, which are critical regions for studying tumor progression, immune evasion, and therapy resistance.

The tool is built around two key objectives:

1. Spatial Tumor Analysis: The pipeline processes multiplex fluorescence microscopy images to map cellular interactions, immune infiltration, and tumor heterogeneity using a range of spatial analysis metrics.
2. Tumor Invasion Front Detection: A deep-learning-based model is employed to automatically detect and analyze tumor invasion fronts in H&E-stained tissue sections, providing valuable insights into tumor-stroma interactions.

This integrated framework, combining multiplex fluorescence imaging and deep learning, offers a scalable and reproducible approach for understanding the complex biology of cancer.

Repository Structure

The repository is organized as follows:

• ./analysis/: Core image analysis scripts for processing multiplex fluorescence data, including segmentation, intensity extraction, spatial analysis, and tumor front detection.

  • intensity.py: Functions to extract fluorescence intensities and compute marker positivity.
  • positivity.py: Utilities for handling marker positivity classification.
  • spatial.py: Functions to compute spatial metrics, including distances between cells and Voronoi tessellation.
  • subpopulations.py: Scripts for analyzing immune cell populations and tumor microenvironment interactions.

• ./config.py: Configuration file where you can define paths, channels, marker labels, and other parameters. You can modify these parameters according to your specific dataset and experimental setup.

• ./data/: Directory to store the image files you wish to analyze. This directory should contain your multi-channel OME-TIFF or TIFF files.

• ./results/: Directory where the results of the analysis will be saved, including CSV files with quantitative data, distance metrics, and visualizations.

• ./notebooks/: Jupyter Notebooks that guide you through the analysis pipeline with detailed explanations. These notebooks include steps to load your data, run the analysis, and visualize the results.

Getting Started

To use this tool, follow the steps below:

1. Clone the Repository

Clone the repository to your local machine using the following command:

git clone https://github.com/yourusername/spatial-biology-image-analysis.git
cd spatial-biology-image-analysis

2. Set Up the Environment

Create a virtual environment and install the required dependencies:

python -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts�ctivate`
pip install -r requirements.txt

3. Modify Configuration Parameters

Open config.py and modify the following parameters according to your dataset:

• Data paths: Ensure that the paths to your input data (./data/) and output directories (./results/) are correctly set.
• Markers: You can adjust the list of channels and their corresponding biomarkers in the configuration.
• Segmentation settings: Modify the settings for image segmentation and mask creation (e.g., for cytokeratin (CK) or NGFR) based on your specific experimental setup.

4. Run the Analysis

Navigate to the notebooks/ directory and open the appropriate Jupyter notebook. The notebooks are designed to walk you through the analysis process.

Example usage (run in a Jupyter notebook or Python script):

# Load your image data
image_data = load_images('./data')

# Perform segmentation and analysis
segmented_cells = segment_cells(image_data)
intensity_data = extract_intensity(segmented_cells)

# Perform spatial analysis and tumor front detection
spatial_analysis = compute_spatial_metrics(segmented_cells)
tumor_fronts = detect_tumor_invasion_fronts(image_data)

5. Visualize the Results

After running the analysis, you can visualize the results using the provided functions for plotting and overlaying the data on the tissue images.

Example (using the visualization module):

# Visualize segmentation and spatial metrics
plot_segmentation_overlay(segmented_cells, image_data)
plot_spatial_distribution(spatial_analysis)

6. Save and Export Results

The results will be saved in the ./results/ directory, where you will find CSV files containing cell counts, distances, and other analysis metrics. You can also export visualizations as image files for publication or further analysis.

Key Considerations

• Data Quality: Ensure that your input images are properly calibrated and that each channel is correctly aligned. If you're using cyclic multiplexing (e.g., MACSima™), make sure the images are properly deconvoluted.
• Marker Thresholding: Adaptive thresholds for marker positivity (e.g., NGFR, Ki-67) are based on the dataset you are working with. Adjust these values in config.py if necessary.
• Deep Learning Model: The deep learning model for tumor invasion front detection is based on a U-Net architecture. You may need to retrain the model or fine-tune it for specific tumor types or staining protocols.

Results and Outputs

• CSV Files: Quantitative results including intensity data, binary positivity calls, and spatial metrics for each Region of Interest (ROI).
• Visualizations: Overlay images showing marker intensities, cell counts, and tumor-stroma boundaries.
• Tumor Invasion Fronts: Automated detection of tumor invasion fronts in H&E-stained tissue images.

Citation

If you use this tool in your research, please cite the following publication:

Daniel Anchuela. Design and Implementation of a Spatial Biology Image‑Analysis Tool for Multiplex Microscopy. (2025).

---

Updates and Contributions

Feel free to contribute to this repository. If you encounter bugs or have suggestions for improvement, please open an issue or submit a pull request.