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.5  # smoothness of the kernel density estimation (KDE)
n_components = 20  # number of principal components, depends on the data complexity

# 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_components (to set the number of prinicpal components that will be used).

2. Fit the ovrlpy Model

Fit the ovrlpy model to generate the signal integrity map.

# Fit the ovrlpy model to the spatial data
dataset = ovrlpy.Ovrlp(
    coordinate_df,
    KDE_bandwidth=kde_bandwidth,
    n_components=n_components,
    n_workers=4,  # number of threads to use for processing
)
dataset.analyse()

3. Visualize the Model Fit

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

fig = ovrlpy.plot_pseudocells(dataset)

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.

fig = ovrlpy.plot_signal_integrity(dataset, signal_threshold=4)

5. Detect and Visualize Overlaps (Doublets)

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

# Detect doublet events (overlapping signals) in the dataset
doublets = dataset.detect_doublets(
    min_signal=4,  # threshold for signal strength
    integrity_sigma=1,  # controls the coherence of the signals
)

doublets.head()

6. 3D Visualization of a Doublet Event

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

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

# Coordinates of the doublet event
x, y = doublets["x", "y"].row(doublet_to_show)

# Plot the doublet event with 3D visualization
fig = ovrlpy.plot_region_of_interest(dataset, x, y, window_size=window_size)

This visualization shows a top/bottom/side representation of the spatial overlap event, giving more insight into the structure and coherence of the signals.