Metadata-Version: 2.1
Name: topapprox
Version: 0.2.1
Summary: Persistent-homology-based filtering for arrays and graph signals.
Keywords: persistent homology,topological data analysis,signal processing,pybind11
Author: Junyan Chu, Sebastían Elías Graiff Zurita
Author-Email: Matias de Jong van Lier <matias.vanlier@gmail.com>, Shizuo Kaji <shizuo.kaji@gmail.com>
License: MIT License
         
         Copyright (c) 2024 mvlier
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Project-URL: Homepage, https://github.com/mvlier/topapprox
Project-URL: Repository, https://github.com/mvlier/topapprox
Project-URL: Issues, https://github.com/mvlier/topapprox/issues
Requires-Python: >=3.10
Requires-Dist: numpy>=1.26
Provides-Extra: plot
Requires-Dist: matplotlib>=3.8; extra == "plot"
Requires-Dist: networkx>=3.2; extra == "plot"
Provides-Extra: numba
Requires-Dist: numba>=0.60; python_version < "3.14" and extra == "numba"
Provides-Extra: test
Requires-Dist: pytest>=8.2; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: cibuildwheel>=2.21; extra == "dev"
Requires-Dist: matplotlib>=3.8; extra == "dev"
Requires-Dist: networkx>=3.2; extra == "dev"
Requires-Dist: numba>=0.60; python_version < "3.14" and extra == "dev"
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: ruff>=0.6.9; extra == "dev"
Description-Content-Type: text/markdown

# topapprox

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Authors**:
[Matias de Jong van Lier](https://sites.google.com/view/matiasvanlier), [Junyan Chu](https://sites.google.com/view/junyan-chu/), Sebastían Elías Graiff Zurita, [Shizuo Kaji](https://www.skaji.org/)

`topapprox` is a Python package for persistent-homology-based filtering of scalar signals on:

- 1D, 2D, and 3D arrays
- graphs with faces

Low-persistence filtering removes topological features that are small relative to a chosen threshold `epsilon`.

In practice:

1. Build the persistence diagram of the input signal.
2. Identify features whose persistence is smaller than `epsilon`.
3. Modify the signal so those low-persistence features disappear, while the more significant ones remain.

This makes the filter useful for denoising and simplification: small oscillations, shallow basins, and weak cycles are removed, while large-scale structure is preserved. For array signals, the filtered output remains within `epsilon` in the `L^inf` norm of the original input.

## Installation

From PyPI:

```bash
pip install topapprox
```

From source:

```bash
python -m pip install -e ".[dev]"
```

## Quick Start

```python
import numpy as np
import topapprox as ta
from topapprox.persistence import get_PD_gwf

img = np.array([[0, 5, 3], [5, 6, 4], [2, 5, 1]], dtype=float)

image_filter = ta.ImageFilter(img, method="python")
filtered_h0 = image_filter.low_pers_filter(1.5)

dual_filter = ta.ImageFilter(img, dual=True, method="python")
filtered_h1 = dual_filter.low_pers_filter(1.5)

faces = [[0, 1, 2, 3]]
holes = [[0, 1, 2, 3]]
signal = np.array([0.0, 1.0, 0.5, 0.2])

graph_filter = ta.GraphFilter(method="python")
graph_filter.compute_gwf(F=faces, H=holes, signal=signal)
pd0, pd1 = graph_filter.get_diagram()

persistence_filter = ta.PersistenceFilter().load_signal(img)
filtered_01 = persistence_filter.low_pers_filter(1.5, iteration_order="01", method="python")

pd0_fn, pd1_fn = get_PD_gwf(faces, holes, signal, method="python")
```

## Documentation & Examples

- [Interactive Tutorial](notebook/Interactive_Tutorial_topapprox.ipynb)
- [BHT Basin Visualization](notebook/BHT_Basin_Visualization.ipynb)
- [Reproducing Paper Examples](notebook/Reproducing_paper_examples.ipynb)
- [Notebook/API migration memo](docs/migration.md)
- [Original paper on arXiv](https://arxiv.org/abs/2408.14109)

## Development

Run the full test suite:

```bash
python -m pytest -q
```

Build distributions locally:

```bash
python -m build --wheel --sdist
```

Binary wheels are built with `cibuildwheel`, and the native extension is compiled through `scikit-build-core` + CMake.

## Citation

If you use this package in your work, please cite:

> Matias de Jong van Lier, Sebastían Elías Graiff Zurita, Shizuo Kaji.
> Topological filtering of a signal over a network (2024).
> [arXiv:2408.14109](https://arxiv.org/abs/2408.14109)

```bibtex
@article{vanlier2024topological,
  title={Topological filtering of a signal over a network},
  author={de Jong van Lier, Matias and Graiff Zurita, Sebastían Elías and Kaji, Shizuo},
  journal={arXiv preprint arXiv:2408.14109},
  year={2024}
}
```

## Migration Notes

The refactor intentionally simplified the public surface and build system. If you are adapting older notebooks, see [docs/migration.md](docs/migration.md).
