# 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

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

### With visualization dependencies

```bash
pip install -e ".[viz]"
```

### All dependencies (including development tools)

```bash
pip install -e ".[all]"
```

## Quick Start

```python
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:

```python
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

```python
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

```python
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:

```python
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):

```python
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 (yuzhou.chang@osumc.edu)
