Metadata-Version: 2.4
Name: polyfacet
Version: 1.0.0
Summary: Algorithms for simplex-structured matrix factorization and polyhedral facet extraction.
Author: Dmitry Beresnev, Valentin Leplat, Nicolas Gillis
Author-email: Dmitry Beresnev <d.beresnev.work@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: cvxpy>=1.6
Requires-Dist: loguru>=0.7
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: optuna>=4.0
Requires-Dist: plotly>=5.24
Requires-Dist: pulp[highs]>=2.8
Requires-Dist: scikit-learn>=1.4
Requires-Dist: scipy>=1.11
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/crogs-foundation/polyfacet
Project-URL: Repository, https://github.com/crogs-foundation/polyfacet
Project-URL: Issues, https://github.com/crogs-foundation/polyfacet/issues
Description-Content-Type: text/markdown

# Polyfacet

<p align="center"><img src="https://raw.githubusercontent.com/crogs-foundation/polyfacet/main/polyfacet-logo.svg" alt="Polyfacet logo" width="260"></p>

<p align="center">Simplex-structured matrix factorization and polyhedral facet extraction in Python.</p>

Polyfacet provides FPI and non-FPI algorithms through one Python API, with
reproducible synthetic scenarios and parameter grids, bundled hyperspectral
reference datasets, typed multi-scenario evaluation, metrics, visualizations,
examples, and notebooks.

## Install

Polyfacet requires Python 3.11 or newer:

```bash
# From an existing uv project, add the latest published Polyfacet release.
uv add polyfacet
```

If you are starting a new application, initialize its uv project first:

```bash
uv init my-polyfacet-project
cd my-polyfacet-project
uv add polyfacet
```

For development from a checkout, use [uv](https://docs.astral.sh/uv/):

```bash
git clone https://github.com/crogs-foundation/polyfacet.git
cd polyfacet
uv sync --group dev
```

## Quick start

```python
from polyfacet.algorithms import SOFPI
from polyfacet.data import Scenario

scenario = Scenario(rank=3, seed=7)
result = SOFPI().run(scenario.data.X, target_dim=scenario.rank, rank_X=scenario.data.r)

print(result.W.shape)  # (n_features, rank)
print(result.H.shape)  # (rank, n_samples)
```

Input matrices use `X.shape == (n_features, n_samples)`: each column is one
sample.

For repeatable research grids, `polyfacet.data.Scenario` and `ScenarioMatrix`
support facet/interior point distributions, purity, SNR, deterministic trials,
lossless save/load, and stored projections for true/estimated vertex figures.

`polyfacet.evaluation.evaluate` accepts algorithm factories, scenarios, and
metric callables. It isolates failures and produces typed summaries plus
reloadable JSON/NPZ estimates without requiring pandas.

## Algorithms

| Family                      | Methods                                 |
| --------------------------- | --------------------------------------- |
| Facet-based                 | `GFPI`, `EMFPI`, `MBFPI`, `SOFPI`       |
| Other factorization methods | `SNPA`, `HyperCSI`, `MinVolNMF`, `MVIE` |

Each method implements `run(X, target_dim=..., rank_X=...)` and returns factors
`W` and `H`. Supply the known signal rank for noisy data instead of relying on
its usually larger numerical rank. Polyfacet does not make comparative performance claims; use the included
workflows to inspect the methods on data relevant to your work.

Researchers can compose the general `FPI` algorithm with a custom
`FacetExtractor` from `polyfacet.extractors`. Runnable methods remain under
`polyfacet.algorithms`; no generic separation API is exposed.

## Data and examples

The wheel bundles Samson, Jasper Ridge, and Moffett Field. Samson and Jasper
Ridge include reference factors; Moffett is a qualitative real-data example.

```python
from polyfacet.datasets import load_moffett

scene = load_moffett(rank=3)
print(scene.name, scene.X.shape)
```

The repository includes an all-method Moffett notebook. It continues after an
individual method fails and does not calculate ground-truth metrics because
the bundled Moffett scene has no reference factors.

## Documentation

- [Getting started](https://github.com/crogs-foundation/polyfacet/blob/main/docs/getting-started.md)
- [Algorithms and FPI extension point](https://github.com/crogs-foundation/polyfacet/blob/main/docs/algorithms.md)
- [Bundled datasets and attribution](https://github.com/crogs-foundation/polyfacet/blob/main/docs/datasets.md)
- [Scenarios and persistence](https://github.com/crogs-foundation/polyfacet/blob/main/docs/scenarios.md)
- [Evaluation workflows](https://github.com/crogs-foundation/polyfacet/blob/main/docs/evaluation.md)
- [Examples](https://github.com/crogs-foundation/polyfacet/blob/main/examples/README.md)
- [Notebooks](https://github.com/crogs-foundation/polyfacet/blob/main/notebooks/README.md)
- [Troubleshooting](https://github.com/crogs-foundation/polyfacet/blob/main/docs/troubleshooting.md)

## License and citation

Polyfacet is distributed under the [MIT License](https://github.com/crogs-foundation/polyfacet/blob/main/LICENSE).
For academic use, cite the software using
[CITATION.cff](https://github.com/crogs-foundation/polyfacet/blob/main/CITATION.cff)
and cite the original publication for every algorithm used.
