Quickstart

This quickstart guide will walk you through the basic steps of using ovrlpy to create a signal integrity map from a imaging-based spatial transcriptomics dataset. Follow the steps below to get started.

1. Set Up Parameters and Load Your Data

Start by defining the key parameters for the analysis and loading your spatial transcriptomics data. The dataset should contain a x, y, and z columns (in um) and a gene column. Functions to read the data in the correct format are available for common file formats (such as output from Xenium, Vizgen, and CosMx).

import pandas as pd
import ovrlpy

# Define analysis parameters for ovrlpy
kde_bandwidth = 2  # The smoothness of the kernel density estimation (KDE)
n_expected_celltypes = 20  # Number of expected cell types in the data

# Load your spatial transcriptomics data from a CSV file
coordinate_df = pd.read_csv('path/to/coordinate_file.csv')

In this step, we load the dataset and configure the model parameters, such as kde_bandwidth (to control smoothness) and n_expected_celltypes (to set the expected number of cell types).

2. Fit the ovrlpy Model

Fit the ovrlpy model to generate the signal integrity map.

# Fit the ovrlpy model to the spatial data
integrity, signal, visualizer = ovrlpy.run(
    df=coordinate_df,
    KDE_bandwidth=kde_bandwidth,
    n_expected_celltypes=n_expected_celltypes
)

This function generates:

integrity: The signal integrity map.
signal: The signal map representing the strength of spatial expression signals.
visualizer: A visualizer object that helps to plot and explore the results.

3. Visualize the Model Fit

Once the model is fitted, you can visualize how well it matches your spatial data.

# Use the visualizer object to plot the fitted signal map
visualizer.plot_fit()

This plot gives you a visual representation of the models fit to the spatial transcriptomics data.

4. Plot the Signal Integrity Map

Now, plot the signal integrity map using a threshold to highlight areas with strong signal coherence.

# Plot the signal integrity map with a signal threshold
fig, ax = ovrlpy.plot_signal_integrity(integrity, signal, signal_threshold=4.0)

5. Detect and Visualize Overlaps (Doublets)

Identify overlapping signals (doublets) in the tissue and visualize them.

# Detect doublet events (overlapping signals) in the dataset
doublet_df = ovrlpy.detect_doublets(
    integrity,
    signal,
    signal_cutoff=4,  # Threshold for signal strength
    integrity_sigma=1  # Controls the coherence of the signals
)

# Display the detected doublets
doublet_df.head()

6. 3D Visualization of a Doublet Event

Visualize a specific overlap event (doublet) in 3D to see how it looks in the tissue.

# Parameters for 3D visualization
window_size = 60  # Size of the visualization window around the doublet
doublet_to_show = 0  # Index of the doublet to visualize

# Get the coordinates of the doublet event
x, y = doublet_df.loc[doublet_to_show, ["x", "y"]]

# Plot the doublet event with 3D visualization
_ = ovrlpy.plot_region_of_interest(
   x, y,
   coordinate_df,
   visualizer,
   signal_integrity,
   signal_strength,
   window_size=window_size,
)

This visualization shows a 3D representation of the spatial overlap event, giving more insight into the structure and coherence of the signals.