Polyfacet

Simplex-structured matrix factorization and polyhedral facet extraction in Python.

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:

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

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

For development from a checkout, use uv:

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

Quick start

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

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.

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
• Algorithms and FPI extension point
• Bundled datasets and attribution
• Scenarios and persistence
• Evaluation workflows
• Examples
• Notebooks
• Troubleshooting

License and citation

Polyfacet is distributed under the MIT License. For academic use, cite the software using CITATION.cff and cite the original publication for every algorithm used.