pybiogsp 1.0.0

Biological Graph Signal Processing for Spatial Data Analysis

PyBioGSP

Biological Graph Signal Processing for Spatial Data Analysis

A Python implementation of Graph Signal Processing (GSP) methods including Spectral Graph Wavelet Transform (SGWT) for analyzing spatial patterns in biological data. Uses PyTorch for accelerated matrix decomposition.

Based on Hammond, Vandergheynst, and Gribonval (2011) "Wavelets on Graphs via Spectral Graph Theory" and biological application in Stephanie, Yao, Yuzhou (2024).

Features

• Multi-scale analysis of spatial signals using Spectral Graph Wavelet Transform
• PyTorch acceleration for fast eigendecomposition and matrix operations
• Multiple kernel families: Mexican Hat, Meyer, and Heat kernels
• Graph Fourier Transform (GFT) and Inverse GFT
• Similarity analysis using energy-normalized weighted similarity in Fourier domain
• Simulation tools for generating test patterns (circles, stripes, checkerboards)
• Visualization functions for SGWT decomposition, kernels, and patterns

Installation

From source

git clone https://github.com/BMEngineeR/PyBioGSP.git
cd PyBioGSP
pip install -e .

With visualization dependencies

pip install -e ".[viz]"

All dependencies (including development tools)

pip install -e ".[all]"

Quick Start

import numpy as np
import pandas as pd
from pybiogsp import SGWT

# Create example spatial data
np.random.seed(42)
n_points = 500
data = pd.DataFrame({
    'x': np.random.rand(n_points) * 100,
    'y': np.random.rand(n_points) * 100,
    'signal1': np.sin(np.random.rand(n_points) * 2 * np.pi),
    'signal2': np.cos(np.random.rand(n_points) * 2 * np.pi),
})

# Initialize SGWT object
sg = SGWT(data, x_col='x', y_col='y', signals=['signal1', 'signal2'])

# Build spectral graph (computes k-NN graph and Laplacian eigendecomposition)
sg.run_spec_graph(k=15, laplacian_type='normalized')

# Run SGWT forward and inverse transforms
sg.run_sgwt()

# Calculate similarity between signals
similarity = sg.run_sgcc('signal1', 'signal2')
print(f"Similarity: {similarity['S']:.4f}")
print(f"Low-freq similarity: {similarity['c_low']:.4f}")
print(f"High-freq similarity: {similarity['c_nonlow']:.4f}")

# Analyze energy distribution
energy_df = sg.energy_analysis('signal1')
print(energy_df)

# Print SGWT object summary
print(sg)

Workflow

The typical BioGSP workflow consists of three main steps:

1. Initialize (SGWT.__init__ or init_sgwt): Create SGWT object with data and parameters
2. Build Graph (run_spec_graph): Construct k-NN graph and compute Laplacian eigendecomposition
3. Run SGWT (run_sgwt): Perform forward and inverse SGWT transforms
4. Analyze (run_sgcc, energy_analysis): Compute similarity and energy distribution

Core Components

SGWT Class

The main class that encapsulates the complete workflow:

from pybiogsp import SGWT

sg = SGWT(
    data,                    # DataFrame with coordinates and signals
    x_col='x',              # X coordinate column name
    y_col='y',              # Y coordinate column name
    signals=['sig1'],       # Signal column names
    J=5,                    # Number of wavelet scales
    scaling_factor=2.0,     # Scale ratio between levels
    kernel_type='heat',     # Kernel family
)

Kernel Types

Three kernel families are supported:

• "heat": Heat kernel (default) - h(t) = exp(-t), g(t) = t * exp(-t)
• "mexican_hat": Mexican Hat kernel - h(t) = exp(-0.5*t²), g(t) = t² * exp(-0.5*t²)
• "meyer": Meyer wavelet - smooth transition functions

Standalone Functions

from pybiogsp import (
    # Core functions
    sgwt_get_kernels,
    compute_sgwt_filters,
    sgwt_forward,
    sgwt_inverse,
    sgwt_auto_scales,
    
    # Utility functions
    cal_laplacian,
    fast_decomposition_lap,
    gft,
    igft,
    cosine_similarity,
    
    # Simulation
    simulate_multiscale,
    simulate_stripe_patterns,
    simulate_checkerboard,
    
    # Visualization
    plot_sgwt_decomposition,
    visualize_sgwt_kernels,
)

Visualization

from pybiogsp import plot_sgwt_decomposition, visualize_sgwt_kernels

# Plot SGWT decomposition
fig = plot_sgwt_decomposition(sg, signal_name='signal1')

# Visualize kernels
result = visualize_sgwt_kernels(
    sg.Graph.eigenvalues,
    scales=sg.Parameters.scales,
    kernel_type='heat',
)

Simulation Functions

Generate test patterns for validation:

from pybiogsp import (
    simulate_multiscale,
    simulate_stripe_patterns,
    simulate_moving_circles,
    simulate_checkerboard,
)

# Concentric circles
patterns = simulate_multiscale(grid_size=60, n_centers=1)

# Stripe patterns
stripes = simulate_stripe_patterns(gap_seq=[10, 20], width_seq=[5, 10])

# Checkerboard
checker = simulate_checkerboard(grid_size=8, tile_size=10)

GPU Acceleration

BioGSP automatically uses the best available device (CUDA > MPS > CPU):

import torch
from pybiogsp.utils import get_device

device = get_device()
print(f"Using device: {device}")

# Force CPU if needed
sg.run_spec_graph(k=15, use_torch=True)  # Uses best available
sg.run_sgwt(use_torch=True)

Applications

BioGSP is designed for:

• Spatial transcriptomics: Analyzing gene expression patterns (Visium, MERFISH, etc.)
• Multiplexed imaging: Cell type distributions (CODEX, IMC, etc.)
• Neuroscience: Brain connectivity and signal analysis
• Developmental biology: Spatial pattern formation
• Pathology: Tumor microenvironment analysis

References

1. Hammond, D. K., Vandergheynst, P., & Gribonval, R. (2011). Wavelets on graphs via spectral graph theory. Applied and Computational Harmonic Analysis, 30(2), 129-150.

2. Stephanie, Yao, Yuzhou (2024). [Biological Application]. bioRxiv. doi:10.1101/2024.12.20.629650

License

GPL-3.0

Author

Yuzhou Chang ([e-mail])