Metadata-Version: 2.4
Name: wnetalign
Version: 1.0.0
Summary: Python implementation of spectral alignment using Wasserstein metric
Author-Email: Michał Startek <michal.startek@mimuw.edu.pl>
Maintainer-Email: Michał Startek <michal.startek@mimuw.edu.pl>
License-Expression: MIT
License-File: LICENCE
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Development Status :: 5 - Production/Stable
Project-URL: Homepage, https://github.com/michalsta/wnetalign
Project-URL: Repository, https://github.com/michalsta/wnetalign.git
Requires-Python: >=3.9
Requires-Dist: pylmcf
Requires-Dist: wnet>=1.2.0
Requires-Dist: numpy
Provides-Extra: extras
Requires-Dist: pyopenms; extra == "extras"
Provides-Extra: pytest
Requires-Dist: pytest; extra == "pytest"
Requires-Dist: pandas; extra == "pytest"
Requires-Dist: numpy; extra == "pytest"
Description-Content-Type: text/markdown

# WNetAlign

WNetAlign is a tool for MS (Mass Spectrometry) or NMR (Nuclear Magnetic Resonance) spectral alignment using Truncated Wasserstein Metric-based methods. It offers algorithms and utilities for comparing and mapping spectral features between datasets, leveraging advanced optimal transport techniques and spectral topology.

## Features

- Truncated Wasserstein metric-based spectral alignment
- Algorithms for spectral feature comparison and mapping
- Utilities for preprocessing and visualization

## Installation

```bash
pip install wnetalign
```

## Usage

```python
import numpy as np
from wnetalign import Spectrum, WNetAligner
from wnet.distances import DistanceMetric

# positions shape: (dim, num_peaks); intensities shape: (num_peaks,)
S1 = Spectrum(positions=np.array([[1.0, 2.5, 4.0]]), intensities=np.array([1.0, 3.0, 2.0]))
S2 = Spectrum(positions=np.array([[1.1, 2.4, 4.2]]), intensities=np.array([1.0, 2.5, 2.5]))

S1 = S1.normalized()
S2 = S2.normalized()

aligner = WNetAligner(
    empirical_spectrum=S1,
    theoretical_spectra=[S2],
    distance=DistanceMetric.L2,
    max_distance=0.5,
    trash_cost=0.9,
)
aligner.set_point([1])

print("Total cost:", aligner.total_cost())
flows = aligner.flows()[0]        # Flow(empirical_peak_idx, theoretical_peak_idx, flow)
emp_ids, theo_ids = aligner.consensus()  # greedy 1-to-1 pairs
```

For more complete examples see the `tutorials` directory.

## Tutorials

Tutorials showing how to apply `wnetalign` to NMR data can be found in `tutorials/nmr`, while an example of LC-MS alignment can be found in `tutorials/lcms`.

## Results from publication

To reproduce the results and figures from the paper *"WNetAlign: Fast and Accurate Spectra Alignment Using Truncated Wasserstein Distance and Network Simplex"* use the scripts and notebooks provided in the `publication/nmr` folder for NMR data; for an LC-MS alignment example see `tutorials/lcms`.

#### 2D NMR data

The 2D 15N-1H HSQC spectra are available in `publication/nmr/2D/15N_HSQC_GB1_reduced` folder.

* `NMR_2D_original.ipynb` - plotting data distribution, chain alignment of the series of 15N-1H HSQC spectra measured in different temperatures
* `NMR_2D_simulated.ipynb` - simulating synthetic temperature series, validation of alignment procedure using standard and extended metrics, heatmaps
* `NMR_2D_seeds.ipynb` - performing alignments for the synthetic temperature series with different random seeds

#### 4D NMR data

The 4D CCNOESY spectrum of 2LX7 pdb structure can be found in the `publication/nmr/4D/2LX7`.

* `NMR_4D.ipynb` - simulating the replicate of the 4D 2LX7 CCNOESY spectrum and validating the alignment between the original spectrum and the replicate with standard and extended performance metrics

#### 7D NMR data

The hypothetical 7D NMR spectra can be found in `publication/nmr/7D/NMR_7D`.

* `NMR_7D.ipynb` - simulating the replicates of the 17 hypothetical 7D NMR spectra and validating the alignments between the original hypothetical spectra and the replicates with extended performance metrics

## Citation

If you use this software, please cite:

Król J, Bochenek M, Jopa S, Kazimierczuk K, Gambin A, Startek MP (2026).
WNetAlign: fast and accurate spectra alignment using truncated Wasserstein distance and network simplex.
*Briefings in Bioinformatics*, 27(3), bbag247.
https://doi.org/10.1093/bib/bbag247

```bibtex
@article{krol2026wnetalign,
  title   = {WNetAlign: fast and accurate spectra alignment using truncated Wasserstein distance and network simplex},
  author  = {Kr{\'o}l, Justyna and Bochenek, Maria and Jopa, Sylwia and Kazimierczuk, Krzysztof and Gambin, Anna and Startek, Micha{\l} Piotr},
  journal = {Briefings in Bioinformatics},
  volume  = {27},
  number  = {3},
  pages   = {bbag247},
  year    = {2026},
  doi     = {10.1093/bib/bbag247}
}
```

## License

This project is licensed under the MIT License.
