pybiogsp 2.1.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 PyPI (recommended)

pip install pybiogsp

From source (development)

git clone https://github.com/BMEngineeR/PyBioGSP.git
cd PyBioGSP
pip install -e ".[viz]"  # includes matplotlib & seaborn

Quick Start

from pybiogsp import SGWT

# 1. Initialize with a DataFrame containing X, Y coordinates and signal columns
sg = SGWT(data=df, x_col="X", y_col="Y",
          signals=["signal_1", "signal_2"],
          J=3, scaling_factor=5, kernel_type="heat")

# 2. Build graph (k-NN -> Laplacian)
sg.build_graph(k=12, laplacian_type="normalized", verbose=False)

# 3. Forward & inverse SGWT (eigendecomposition + wavelet transform)
sg.run_sgwt(method="eigen", use_batch=True, verbose=False, use_torch=True, length_eigenvalue=900)

# 4a. Compare two signals in wavelet domain
result = sg.run_sgcc("signal_1", "signal_2", return_parts=True)
print(f"Overall similarity:  {result['S']:.4f}")
print(f"Low-freq similarity: {result['c_low']:.4f}")
print(f"High-freq similarity:{result['c_nonlow']:.4f}")

# 4b. Or compute all-pairs SGCC matrix at once (matrix multiplication, no loop)
sgcc_df = sg.run_sgcc_matrix()
print(sgcc_df)

# 4c. Or compare specific signal pairs efficiently (vectorized, no loop)
pairs_df = sg.run_sgcc_pairs([("signal_1", "signal_2")])
print(pairs_df)

# 5. Energy analysis
energy_df = sg.energy_analysis("signal_1")
print(energy_df)

Workflow

SGWT(data) -> build_graph() -> run_sgwt(method=...) -> run_sgcc() / energy_analysis()

Step	Method	What it does
1	SGWT(data, ...)	Initialize with DataFrame, coordinates, signals, kernel parameters
2	build_graph(k, laplacian_type, ...)	Build k-NN graph -> Laplacian
3	run_sgwt(method=..., ...)	Spectral prep + forward SGWT + inverse (reconstruction)
4a	run_sgcc(signal1, signal2, ...)	Energy-weighted cosine similarity -> c_low, c_nonlow, S
4a'	run_sgcc_matrix()	All-pairs SGCC matrix via matrix multiplication (no loop needed)
4a''	run_sgcc_pairs(pairs)	Vectorized SGCC for specific signal pairs (no loop needed)
4b	energy_analysis(signal_name)	Per-scale energy distribution

API Overview

SGWT Class — Main Entry Point

from pybiogsp import SGWT

sg = SGWT(
    data,                    # DataFrame with coordinates and signals
    x_col="X", y_col="Y",   # Coordinate column names
    signals=["sig1"],        # Signal columns (None = auto-detect)
    J=5,                     # Number of wavelet scales
    scaling_factor=2.0,      # Ratio between consecutive scales
    kernel_type="heat",      # "heat" | "mexican_hat" | "meyer"
)

sg.build_graph(k=25, laplacian_type="normalized")
sg.run_sgwt(method="eigen", use_batch=True, use_torch=True)
result = sg.run_sgcc("sig1", "sig2", return_parts=True)   # -> {c_low, c_nonlow, S, ...}
sgcc_df = sg.run_sgcc_matrix()                              # -> p×p DataFrame of all-pairs S
pairs_df = sg.run_sgcc_pairs([("sig1", "sig2")])            # -> DataFrame (K rows)
energy = sg.energy_analysis("sig1")                        # -> DataFrame

PyBioGSP

Biological Graph Signal Processing for Spatial Data Analysis

A Python implementation of Graph Signal Processing (GSP) methods ...

Copilot Agent Skill

This repo includes a VS Code Copilot agent skill at .github/skills/pybiogsp-analysis/ that provides Copilot with full PyBioGSP workflow knowledge — parameter meanings, result interpretation, troubleshooting, and batch analysis patterns. When using Copilot in this workspace, it can guide you through the SGWT pipeline end-to-end.

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])