opfython 1.0.12__tar.gz → 2.0.0__tar.gz

opfython-2.0.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: opfython
+Version: 2.0.0
+Summary: Python-Inspired Optimum-Path Forest Classifier
+Author-email: Gustavo Rosa <gustavo.rosa@unesp.br>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+License-File: LICENSE
+Requires-Dist: numba>=0.67.0
+Requires-Dist: numpy>=2.4.4
+Requires-Dist: coverage>=7.10.0 ; extra == "tests"
+Requires-Dist: flake8>=7.3.0 ; extra == "tests"
+Requires-Dist: pytest>=9.0.0 ; extra == "tests"
+Project-URL: Documentation, https://opfython.readthedocs.io
+Project-URL: Homepage, https://github.com/gugarosa/opfython
+Project-URL: Issues, https://github.com/gugarosa/opfython/issues
+Provides-Extra: tests
+Import-Name: opfython
+
+# OPFython
+
+[![PyPI](https://img.shields.io/pypi/v/opfython.svg)](https://pypi.org/project/opfython/)
+[![CI](https://github.com/gugarosa/opfython/actions/workflows/ci.yml/badge.svg)](https://github.com/gugarosa/opfython/actions/workflows/ci.yml)
+[![Documentation](https://readthedocs.org/projects/opfython/badge/?version=latest)](https://opfython.readthedocs.io/)
+[![DOI](https://img.shields.io/badge/DOI-10.1016/j.simpa.2021.100113-006DB9.svg)](https://doi.org/10.1016/j.simpa.2021.100113)
+[![License](https://img.shields.io/github/license/gugarosa/opfython.svg)](LICENSE)
+
+OPFython is a Python implementation of the Optimum-Path Forest family of
+classifiers. It provides supervised, semi-supervised, unsupervised, and
+KNN-supervised models backed by NumPy and Numba.
+
+This implementation follows [LibOPF](https://github.com/jppbsi/LibOPF).
+Please cite the original LibOPF authors as well as OPFython when using it in
+research.
+
+OPFython requires Python 3.11 or newer.
+
+## Installation
+
+```bash
+uv add opfython
+```
+
+## Quick start
+
+```python
+import numpy as np
+
+from opfython.models import SupervisedOPF
+
+X_train = np.asarray([[0.0, 0.0], [0.1, 0.2], [1.0, 1.0], [1.1, 0.9]])
+Y_train = np.asarray([0, 0, 1, 1])
+X_test = np.asarray([[0.05, 0.1], [1.05, 1.0]])
+
+classifier = SupervisedOPF()
+classifier.fit(X_train, Y_train)
+predictions = classifier.predict(X_test)
+```
+
+Labels must be zero-based and sequential. Pre-computed distance matrices can
+be supplied through each classifier's `pre_computed_distance` constructor
+argument.
+
+## Classifiers
+
+| Class | Purpose |
+|---|---|
+| `SupervisedOPF` | Complete-graph supervised classification |
+| `KNNSupervisedOPF` | Supervised classification with learned KNN adjacency |
+| `SemiSupervisedOPF` | Learning from labeled and unlabeled samples |
+| `UnsupervisedOPF` | Density-based clustering and label propagation |
+
+The package also includes 47 distance metrics, random generators, OPF
+evaluation measures, dataset loaders and splitters, package logging and
+exception helpers, and converters for LibOPF binary datasets.
+
+See [the documentation](https://opfython.readthedocs.io/) and the
+[`examples/applications`](examples/applications) directory for complete
+workflows.
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pytest
+uv run pre-commit run --all-files
+uv run --group docs sphinx-build -W -b html docs docs/_build/html
+uv build --no-sources
+```
+
+## Citation
+
+```bibtex
+@article{rosa2021simpa,
+    title = {OPFython: A Python implementation for Optimum-Path Forest},
+    author = {Gustavo H. {de Rosa} and Joao P. Papa},
+    journal = {Software Impacts},
+    pages = {100113},
+    year = {2021},
+    issn = {2665-9638},
+    doi = {https://doi.org/10.1016/j.simpa.2021.100113}
+}
+```
+
+```bibtex
+@misc{rosa2021speedup,
+    title = {Speeding Up OPFython with Numba},
+    author = {Gustavo H. de Rosa and Joao Paulo Papa},
+    year = {2021},
+    eprint = {2106.11828},
+    archivePrefix = {arXiv},
+    primaryClass = {cs.LG}
+}
+```
+
+OPFython is licensed under the Apache License 2.0.
+

opfython-2.0.0/README.md

@@ -0,0 +1,97 @@
+# OPFython
+
+[![PyPI](https://img.shields.io/pypi/v/opfython.svg)](https://pypi.org/project/opfython/)
+[![CI](https://github.com/gugarosa/opfython/actions/workflows/ci.yml/badge.svg)](https://github.com/gugarosa/opfython/actions/workflows/ci.yml)
+[![Documentation](https://readthedocs.org/projects/opfython/badge/?version=latest)](https://opfython.readthedocs.io/)
+[![DOI](https://img.shields.io/badge/DOI-10.1016/j.simpa.2021.100113-006DB9.svg)](https://doi.org/10.1016/j.simpa.2021.100113)
+[![License](https://img.shields.io/github/license/gugarosa/opfython.svg)](LICENSE)
+
+OPFython is a Python implementation of the Optimum-Path Forest family of
+classifiers. It provides supervised, semi-supervised, unsupervised, and
+KNN-supervised models backed by NumPy and Numba.
+
+This implementation follows [LibOPF](https://github.com/jppbsi/LibOPF).
+Please cite the original LibOPF authors as well as OPFython when using it in
+research.
+
+OPFython requires Python 3.11 or newer.
+
+## Installation
+
+```bash
+uv add opfython
+```
+
+## Quick start
+
+```python
+import numpy as np
+
+from opfython.models import SupervisedOPF
+
+X_train = np.asarray([[0.0, 0.0], [0.1, 0.2], [1.0, 1.0], [1.1, 0.9]])
+Y_train = np.asarray([0, 0, 1, 1])
+X_test = np.asarray([[0.05, 0.1], [1.05, 1.0]])
+
+classifier = SupervisedOPF()
+classifier.fit(X_train, Y_train)
+predictions = classifier.predict(X_test)
+```
+
+Labels must be zero-based and sequential. Pre-computed distance matrices can
+be supplied through each classifier's `pre_computed_distance` constructor
+argument.
+
+## Classifiers
+
+| Class | Purpose |
+|---|---|
+| `SupervisedOPF` | Complete-graph supervised classification |
+| `KNNSupervisedOPF` | Supervised classification with learned KNN adjacency |
+| `SemiSupervisedOPF` | Learning from labeled and unlabeled samples |
+| `UnsupervisedOPF` | Density-based clustering and label propagation |
+
+The package also includes 47 distance metrics, random generators, OPF
+evaluation measures, dataset loaders and splitters, package logging and
+exception helpers, and converters for LibOPF binary datasets.
+
+See [the documentation](https://opfython.readthedocs.io/) and the
+[`examples/applications`](examples/applications) directory for complete
+workflows.
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pytest
+uv run pre-commit run --all-files
+uv run --group docs sphinx-build -W -b html docs docs/_build/html
+uv build --no-sources
+```
+
+## Citation
+
+```bibtex
+@article{rosa2021simpa,
+    title = {OPFython: A Python implementation for Optimum-Path Forest},
+    author = {Gustavo H. {de Rosa} and Joao P. Papa},
+    journal = {Software Impacts},
+    pages = {100113},
+    year = {2021},
+    issn = {2665-9638},
+    doi = {https://doi.org/10.1016/j.simpa.2021.100113}
+}
+```
+
+```bibtex
+@misc{rosa2021speedup,
+    title = {Speeding Up OPFython with Numba},
+    author = {Gustavo H. de Rosa and Joao Paulo Papa},
+    year = {2021},
+    eprint = {2106.11828},
+    archivePrefix = {arXiv},
+    primaryClass = {cs.LG}
+}
+```
+
+OPFython is licensed under the Apache License 2.0.

{opfython-1.0.12 → opfython-2.0.0}/opfython/__init__.py

@@ -2,5 +2,4 @@
 of several modules and sub-modules.
 """
 
-
-__version__ = "1.0.12"
+__version__ = "2.0.0"

{opfython-1.0.12 → opfython-2.0.0}/opfython/core/__init__.py

@@ -1,7 +1,6 @@
-"""A core package for all common opfython modules.
-"""
+"""A core package for all common opfython modules."""
 
 from opfython.core.heap import Heap
 from opfython.core.node import Node
-from opfython.core.subgraph import Subgraph
 from opfython.core.opf import OPF
+from opfython.core.subgraph import Subgraph

opfython-2.0.0/opfython/core/heap.py

@@ -0,0 +1,208 @@
+"""Priority queue used by OPF algorithms."""
+
+from typing import List
+
+import opfython.utils.constants as c
+import opfython.utils.exception as e
+
+
+class Heap:
+    """Fixed-size mutable min or max heap."""
+
+    def __init__(self, size: int = 1, policy: str = "min") -> None:
+        self.size = size
+        self.policy = policy
+        self.cost = [c.FLOAT_MAX] * size
+        self.color = [c.WHITE] * size
+        self.p = [-1] * size
+        self.pos = [-1] * size
+        self.last = -1
+
+    @property
+    def size(self) -> int:
+        """Maximum heap size."""
+
+        return self._size
+
+    @size.setter
+    def size(self, size: int) -> None:
+        if not isinstance(size, int):
+            raise e.TypeError("`size` should be an integer")
+        if size < 1:
+            raise e.ValueError("`size` should be > 0")
+        self._size = size
+
+    @property
+    def policy(self) -> str:
+        """Heap ordering policy."""
+
+        return self._policy
+
+    @policy.setter
+    def policy(self, policy: str) -> None:
+        if policy not in ["min", "max"]:
+            raise e.ValueError("`policy` should be `min` or `max`")
+        self._policy = policy
+
+    @property
+    def cost(self) -> List[float]:
+        """Node costs."""
+
+        return self._cost
+
+    @cost.setter
+    def cost(self, cost: List[float]) -> None:
+        if not isinstance(cost, list):
+            raise e.TypeError("`cost` should be a list")
+        self._cost = cost
+
+    @property
+    def color(self) -> List[int]:
+        """Node colors."""
+
+        return self._color
+
+    @color.setter
+    def color(self, color: List[int]) -> None:
+        if not isinstance(color, list):
+            raise e.TypeError("`color` should be a list")
+        self._color = color
+
+    @property
+    def p(self) -> List[int]:
+        """Heap-position to node mapping."""
+
+        return self._p
+
+    @p.setter
+    def p(self, p: List[int]) -> None:
+        if not isinstance(p, list):
+            raise e.TypeError("`p` should be a list")
+        self._p = p
+
+    @property
+    def pos(self) -> List[int]:
+        """Node to heap-position mapping."""
+
+        return self._pos
+
+    @pos.setter
+    def pos(self, pos: List[int]) -> None:
+        if not isinstance(pos, list):
+            raise e.TypeError("`pos` should be a list")
+        self._pos = pos
+
+    @property
+    def last(self) -> int:
+        """Last occupied heap position."""
+
+        return self._last
+
+    @last.setter
+    def last(self, last: int) -> None:
+        if not isinstance(last, int):
+            raise e.TypeError("`last` should be an integer")
+        if last < -1:
+            raise e.ValueError("`last` should be > -1")
+        self._last = last
+
+    def is_full(self) -> bool:
+        """Return whether every heap slot is occupied."""
+
+        return self.last == self.size - 1
+
+    def is_empty(self) -> bool:
+        """Return whether the heap has no nodes."""
+
+        return self.last == -1
+
+    def dad(self, i: int) -> int:
+        """Return a node's parent position."""
+
+        return int((i - 1) / 2)
+
+    def left_son(self, i: int) -> int:
+        """Return a node's left-child position."""
+
+        return 2 * i + 1
+
+    def right_son(self, i: int) -> int:
+        """Return a node's right-child position."""
+
+        return 2 * i + 2
+
+    def _precedes(self, left: int, right: int) -> bool:
+        if self.policy == "min":
+            return self.cost[left] < self.cost[right]
+        return self.cost[left] > self.cost[right]
+
+    def _swap(self, left: int, right: int) -> None:
+        self.p[left], self.p[right] = self.p[right], self.p[left]
+        self.pos[self.p[left]] = left
+        self.pos[self.p[right]] = right
+
+    def go_up(self, i: int) -> None:
+        """Move a node toward the heap root."""
+
+        parent = self.dad(i)
+        while i > 0 and self._precedes(self.p[i], self.p[parent]):
+            self._swap(i, parent)
+            i = parent
+            parent = self.dad(i)
+
+    def go_down(self, i: int) -> None:
+        """Move a node toward the heap leaves."""
+
+        left = self.left_son(i)
+        right = self.right_son(i)
+        target = i
+
+        if left <= self.last and self._precedes(self.p[left], self.p[target]):
+            target = left
+        if right <= self.last and self._precedes(self.p[right], self.p[target]):
+            target = right
+
+        if target != i:
+            self._swap(i, target)
+            self.go_down(target)
+
+    def insert(self, p: int) -> bool:
+        """Insert a node if capacity is available."""
+
+        if self.is_full():
+            return False
+
+        self.last += 1
+        self.p[self.last] = p
+        self.color[p] = c.GRAY
+        self.pos[p] = self.last
+        self.go_up(self.last)
+        return True
+
+    def remove(self) -> int:
+        """Remove and return the next node, or ``False`` when empty."""
+
+        if self.is_empty():
+            return False
+
+        node = self.p[0]
+        self.pos[node] = -1
+        self.color[node] = c.BLACK
+        self.p[0] = self.p[self.last]
+        self.pos[self.p[0]] = 0
+        self.p[self.last] = -1
+        self.last -= 1
+        self.go_down(0)
+        return node
+
+    def update(self, p: int, cost: float) -> None:
+        """Update a node's cost, inserting it when unseen."""
+
+        self.cost[p] = cost
+        if self.color[p] == c.BLACK:
+            pass
+
+        if self.color[p] == c.WHITE:
+            self.insert(p)
+        else:
+            self.go_up(self.pos[p])