Metadata-Version: 2.4
Name: pybiogsp
Version: 2.1.3
Summary: Biological Graph Signal Processing for Spatial Data Analysis
Home-page: https://github.com/BMEngineeR/PyBioGSP
Author: Yuzhou Chang
Author-email: Yuzhou Chang <yuzhou.chang@osumc.edu>
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/BMEngineeR/PyBioGSP
Project-URL: Documentation, https://pybiogsp.readthedocs.io
Project-URL: Source, https://github.com/BMEngineeR/PyBioGSP
Project-URL: Issues, https://github.com/BMEngineeR/PyBioGSP/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: torch>=1.9.0
Requires-Dist: scikit-learn>=0.24.0
Requires-Dist: tqdm>=4.60.0
Provides-Extra: viz
Requires-Dist: matplotlib>=3.4.0; extra == "viz"
Requires-Dist: seaborn>=0.11.0; extra == "viz"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0.0; extra == "docs"
Requires-Dist: furo>=2024.1.29; extra == "docs"
Requires-Dist: myst-parser>=2.0.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=2.0.0; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0.0; extra == "dev"
Requires-Dist: black>=21.0.0; extra == "dev"
Requires-Dist: flake8>=3.9.0; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

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

```bash
pip install pybiogsp
```

### From source (development)

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

## Quick Start

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

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

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

[![Documentation](https://readthedocs.org/projects/pybiogsp/badge/?version=latest)](https://pybiogsp.readthedocs.io/en/latest/) [![PyPI](https://img.shields.io/pypi/v/pybiogsp)](https://pypi.org/project/pybiogsp/)

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

## Copilot Agent Skill

This repo includes a [VS Code Copilot agent skill](https://code.visualstudio.com/docs/copilot/copilot-customization) 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 (yuzhou.chang@osumc.edu)
