pmf-acls 0.1.0__tar.gz

pmf_acls-0.1.0/.gitignore

@@ -0,0 +1,59 @@
+# Virtual environment
+.venv/
+venv/
+ENV/
+env/
+
+.claude 
+
+testrun/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+*.cover
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Jupyter
+.ipynb_checkpoints/
+
+# OS
+.DS_Store
+Thumbs.db
+.Rproj.user
+
+.claude/
+examples/NMF_testing/
+NMF_testing.7z
+
+# Benchmark outputs
+nmf_compare/results/*.csv
+nmf_compare/results/*.png
+nmf_compare/results/compare_factors/
+
+# Generated outputs at root (legacy)
+*.csv
+*.png
+.~lock.*
+tmpclaude-*
+testrun_me2/

pmf_acls-0.1.0/CLAUDE.md

@@ -0,0 +1,40 @@
+# PMF Monorepo
+
+Two projects in one repo:
+
+## pmf_acls/ — PMF Solver Package
+A Python implementation of Positive Matrix Factorization with five solver backends (ACLS, LS-NMF, Newton, Bayesian NMF, Bayesian LDA), featuring per-element uncertainty weighting.
+
+## nmf_compare/ — NMF/PMF Benchmarking Framework
+Benchmark harness comparing multiple NMF/PMF solvers (pmf_acls, ESAT, scikit-learn NMF) on synthetic data with configurable noise models and matrix sizes.
+
+## Layout
+
+```
+pmf_acls/          # Solver package (installable)
+nmf_compare/       # Benchmarking scripts and results
+scripts/           # Ad-hoc / one-off analysis scripts
+examples/          # Usage examples for pmf_acls
+docs/              # Literature reviews, specs, notes
+reference/         # PMF2/ME2 reference binaries
+```
+
+## Running Tests
+
+```bash
+pytest pmf_acls/tests/ -v
+```
+
+## Running Benchmarks
+
+```bash
+python nmf_compare/benchmark_simulation.py --noise-sweep --solvers PMF_ACLS --reps 3 --seeds 5
+python nmf_compare/benchmark_simulation.py --size-sweep --solvers PMF_ACLS ESAT_LSNMF --reps 3 --seeds 5
+```
+
+## Conventions
+- Package imports: `from pmf_acls import pmf, pmf_bayes, pmf_lda`
+- Algorithms via `pmf()`: 'acls' (default), 'ls-nmf', 'newton', 'bayes'
+- LDA is standalone: `pmf_lda(X, sigma, p)`
+- Benchmark outputs go to `nmf_compare/results/`
+- NumPy/SciPy only for the solver (no heavy deps)

pmf_acls-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jerritt Collord
+
+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.

pmf_acls-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include LICENSE
+include README.md
+include pyproject.toml
+
+recursive-include pmf_acls *.py py.typed
+recursive-exclude pmf_acls CLAUDE.md
+
+global-exclude *.pyc __pycache__
+prune docs
+prune examples
+prune nmf_compare
+prune reference
+prune scripts
+prune .claude

pmf_acls-0.1.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: pmf-acls
+Version: 0.1.0
+Summary: Experimental Positive Matrix Factorization (PMF) routines
+Author: Jerritt Collord
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Provides-Extra: jax
+Requires-Dist: jax>=0.4.0; extra == "jax"
+Requires-Dist: jaxlib>=0.4.0; extra == "jax"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+# pmf_acls — Positive Matrix Factorization
+
+A Python implementation of Positive Matrix Factorization (PMF) for environmental data analysis, featuring five solver backends with per-element uncertainty weighting.
+
+Minimizes the uncertainty-weighted Q objective:
+
+```
+Q = Σᵢⱼ [(xᵢⱼ - Σₖ fᵢₖ gₖⱼ) / σᵢⱼ]²
+```
+
+where F is (m, p) — factor profiles (variables × factors) and G is (p, n) — factor contributions (factors × observations).
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from pmf_acls import pmf
+
+# X = data matrix (m variables × n observations)
+# sigma = per-element uncertainties (same shape)
+result = pmf(X, sigma, p=3)  # ACLS algorithm (default)
+print(f"Converged: {result.converged}, Q: {result.Q:.4f}")
+
+F = result.F  # (m, p) factor profiles
+G = result.G  # (p, n) factor contributions
+```
+
+## Algorithms
+
+The unified `pmf()` entry point supports four algorithms via `algorithm=`. A fifth (LDA) is available as a standalone function.
+
+### ACLS (default) — `algorithm='acls'`
+
+Alternating Constrained Least Squares (Langville et al. 2014). Solves weighted k × k normal equations per column/row. Fast and robust.
+
+```python
+result = pmf(X, sigma, p=3, algorithm='acls')
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `lambda_W` | 0.0 | Tikhonov regularization on F |
+| `lambda_H` | 0.0 | Tikhonov regularization on G |
+| `fpeak` | 0.0 | FPEAK rotational parameter |
+| `max_iter` | 1000 | Maximum iterations |
+| `conv_tol` | 0.005 | Relative change in Q for convergence |
+
+### LS-NMF — `algorithm='ls-nmf'`
+
+Weighted multiplicative updates (Wang et al. 2006). Matches ESAT's LS-NMF for direct comparison.
+
+```python
+result = pmf(X, sigma, p=3, algorithm='ls-nmf')
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `max_iter` | 1000 | Maximum iterations |
+| `conv_tol` | 0.005 | Relative change in Q for convergence |
+
+### Newton — `algorithm='newton'`
+
+Newton-based method (Lu & Wu 2005). Solves large (mp+np) × (mp+np) systems. Supports multi-phase iteration control and outlier reweighting.
+
+```python
+result = pmf(X, sigma, p=3, algorithm='newton')
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `mode` | 'full' | 'basic', 'regularized', or 'full' |
+| `alpha, beta, gamma, delta` | 'auto' | Strength coefficients for penalties |
+| `solver` | 'numpy' | Backend: 'numpy', 'jax', or 'jax_sparse' |
+| `enable_reweighting` | True | Iterative outlier reweighting |
+| `outlier_threshold` | 4.0 | Outlier detection threshold (× sigma) |
+| `enable_step_control` | True | Step length control |
+| `max_step_halving` | 3 | Max step halving attempts |
+| `enable_initial_accel` | True | Initial NNLS acceleration |
+| `accel_iterations` | 10 | Iterations with acceleration |
+| `enable_multiphase` | True | PMF2-style multi-phase iteration |
+| `phase_config` | None | Custom phase config (list of dicts) |
+
+### Bayesian NMF — `algorithm='bayes'`
+
+Gibbs sampling with heteroscedastic Gaussian noise and exponential priors (Schmidt et al. 2009). Via `pmf()`, returns `PMFResult` with posterior means. For full Bayesian output (posterior samples, Geweke diagnostics, credible intervals), call `pmf_bayes()` directly.
+
+```python
+# Via unified interface (returns PMFResult)
+result = pmf(X, sigma, p=3, algorithm='bayes')
+
+# Direct call (returns BayesNMFResult with full posterior)
+from pmf_acls import pmf_bayes
+result = pmf_bayes(X, sigma, p=3, n_samples=1000, n_burnin=500)
+result.F_std   # posterior standard deviations
+result.Q_samples  # Q trace for convergence diagnostics
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `n_samples` | 1000 | Posterior samples to collect |
+| `n_burnin` | 500 | Burn-in sweeps to discard |
+| `n_thin` | 1 | Thinning factor |
+| `lambda_G` | 1.0 | Exponential rate prior on G (contributions) |
+| `lambda_F` | 1.0 | Exponential rate prior on F (profiles) |
+| `learn_hyperparams` | True | Conjugate Gamma updates for lambda |
+| `hyperparam_shape` | 1.0 | Shape (a) of Gamma(a, b) hyperprior |
+| `hyperparam_rate` | 0.1 | Rate (b) of Gamma(a, b) hyperprior |
+| `warm_start` | True | Initialize from short ACLS run |
+| `store_samples` | False | Keep full F/G posterior sample arrays |
+| `sampler` | 'icdf' | Truncated-normal method: 'icdf' (fast) or 'scipy' |
+| `ard` | False | Automatic Relevance Determination for factor pruning |
+| `ard_threshold` | 0.01 | Relative contribution threshold for active factors |
+
+Convergence is assessed via the Geweke z-score on the Q trace (|z| < 2 → converged). Factor columns of F are normalized to unit L1 after each sweep.
+
+#### Automatic Relevance Determination (ARD)
+
+ARD enables automatic factor number selection. Over-specify p (e.g., request 8 factors when you expect 3-5) and the model prunes unnecessary factors by driving their prior rates large:
+
+```python
+result = pmf_bayes(X, sigma, p=8, ard=True, hyperparam_shape=0.5)
+print(f"Active factors: {result.effective_p} / 8")
+print(f"Active mask: {result.active_factors}")
+# Per-factor rates: large values = pruned factors
+print(f"lambda_F per factor: {result.ard_lambda_F}")
+```
+
+- `hyperparam_shape < 1` (e.g., 0.5) promotes aggressive pruning
+- `hyperparam_shape = 1.0` (default) provides moderate pruning
+- `ard_threshold` controls the relative contribution cutoff for "active"
+
+### Bayesian LDA — `pmf_lda()` (standalone)
+
+Dirichlet-Gaussian source apportionment via Metropolis-within-Gibbs. F columns are simplex-constrained (proper compositional profiles summing to 1); G rows have exponential priors. Not available through `pmf()` — use `pmf_lda()` directly.
+
+```python
+from pmf_acls import pmf_lda
+result = pmf_lda(X, sigma, p=3, n_samples=1000, n_burnin=500)
+result.mh_acceptance_rate  # target: 0.1–0.5
+result.kl_samples  # KL divergence trace
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `n_samples` | 1000 | Posterior samples to collect |
+| `n_burnin` | 500 | Burn-in sweeps to discard |
+| `n_thin` | 1 | Thinning factor |
+| `alpha` | 1.0 | Symmetric Dirichlet concentration (fixed) |
+| `lambda_G` | 1.0 | Exponential rate prior on G (contributions) |
+| `learn_hyperparams` | True | Conjugate Gamma updates for lambda_G |
+| `hyperparam_shape` | 1.0 | Shape (a) of Gamma(a, b) hyperprior |
+| `hyperparam_rate` | 0.1 | Rate (b) of Gamma(a, b) hyperprior |
+| `mh_step_size` | 1.0 | MH proposal scale (tune for acceptance 0.1–0.5) |
+| `store_samples` | False | Keep full posterior sample arrays |
+| `sampler` | 'icdf' | Truncated-normal method for G updates |
+
+Key difference from Bayesian NMF: F columns have a joint Dirichlet prior enforcing the simplex constraint by construction (not post-hoc normalization). `alpha < 1` promotes sparse profiles; `alpha > 1` smooths toward uniform. Convergence is assessed via Geweke z-score on the KL divergence trace.
+
+### Common Parameters (all algorithms)
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `X` | required | Data matrix, shape (m, n) |
+| `sigma` | required | Per-element uncertainties, shape (m, n) |
+| `p` | required | Number of factors |
+| `F_init, G_init` | None | Initial factor matrices |
+| `init_method` | 'random' | 'random', 'random_acol', or 'svd_centroid' |
+| `random_seed` | None | Seed for reproducibility |
+| `verbose` | False | Print progress |
+
+## Bayesian Diagnostics
+
+The `bayes_diagnostics` module provides MCMC convergence diagnostics and model comparison tools for the Bayesian solvers.
+
+### Effective Sample Size (ESS)
+
+Estimates the number of effectively independent samples in a correlated MCMC trace. Low ESS suggests increasing `n_samples` or `n_thin`.
+
+```python
+from pmf_acls import effective_sample_size
+
+result = pmf_bayes(X, sigma, p=3, n_samples=2000, n_burnin=500)
+ess = effective_sample_size(result.Q_samples)
+print(f"ESS: {ess:.0f} / {len(result.Q_samples)} samples")
+```
+
+### Gelman-Rubin Rhat (multi-chain convergence)
+
+Compares between-chain and within-chain variance across independent runs. Rhat < 1.05 indicates convergence.
+
+```python
+from pmf_acls import gelman_rubin
+
+results = [pmf_bayes(X, sigma, p=3, random_seed=s) for s in range(4)]
+rhat = gelman_rubin(*[r.Q_samples for r in results])
+print(f"Rhat: {rhat:.3f}")  # target: < 1.05
+```
+
+### WAIC (model comparison)
+
+Widely Applicable Information Criterion for comparing models with different p. Lower WAIC is better. Requires `store_samples=True`.
+
+```python
+from pmf_acls import compute_waic
+
+waic_scores = {}
+for p in [2, 3, 4, 5]:
+    result = pmf_bayes(X, sigma, p, store_samples=True, n_samples=500)
+    w = compute_waic(X, sigma, result.F_samples, result.G_samples)
+    waic_scores[p] = w["waic"]
+    print(f"p={p}: WAIC={w['waic']:.1f}  p_waic={w['p_waic']:.1f}  SE={w['se']:.1f}")
+
+best_p = min(waic_scores, key=waic_scores.get)
+print(f"Best number of factors: {best_p}")
+```
+
+## Data Preparation
+
+```python
+from pmf_acls import prepare_data
+
+X_clean, sigma = prepare_data(
+    X_raw,
+    detection_limit=detection_limits,
+    missing_method='median',
+    bdl_replacement='half_dl',
+    uncertainty_method='poisson',
+)
+result = pmf(X_clean, sigma, p=3)
+```
+
+## Factor Selection
+
+```python
+from pmf_acls import select_factors
+
+selection = select_factors(X, sigma, p_range=(2, 6), n_runs=10)
+print(f"Recommended: {selection.best_p} factors")
+```
+
+## Uncertainty Estimation
+
+```python
+from pmf_acls import bootstrap_uncertainty, displacement_test
+
+# Bootstrap
+uncertainty = bootstrap_uncertainty(X, sigma, p=3, n_bootstrap=100)
+
+# Displacement (DISP)
+disp = displacement_test(X, sigma, result)
+```
+
+## Tests
+
+```bash
+pytest pmf_acls/tests/ -v
+```
+
+## Dependencies
+
+- numpy >= 1.20.0
+- scipy >= 1.7.0
+
+### Optional
+
+- JAX >= 0.4.0 (GPU acceleration for Newton solver)
+
+## References
+
+- Lu, J. & Wu, L. (2005). Technical details and programming guide for a general two-way PMF algorithm.
+- Langville, A. N. et al. (2014). Algorithms, Initializations, and Convergence for the NMF.
+- Wang, G. et al. (2006). LS-NMF: A modified non-negative matrix factorization algorithm utilizing uncertainty estimates.
+- Schmidt, M. N. et al. (2009). Bayesian non-negative matrix factorization.
+- Cemgil, A. T. (2009). Bayesian inference for nonnegative matrix factorisation models.
+- Blei, D. M. et al. (2003). Latent Dirichlet Allocation.

pmf_acls-0.1.0/README.md

@@ -0,0 +1,23 @@
+# PMF Monorepo
+
+Two projects in one repo:
+
+- **pmf_acls/** — A Python Positive Matrix Factorization solver with multiple algorithm backends and per-element uncertainty weighting. See [pmf_acls/README.md](pmf_acls/README.md).
+- **nmf_compare/** — Benchmark harness comparing NMF/PMF solvers on synthetic data. See [nmf_compare/README.md](nmf_compare/README.md).
+
+## Layout
+
+```
+pmf_acls/          # Solver package (installable)
+nmf_compare/       # Benchmarking scripts and results
+scripts/           # Ad-hoc / one-off analysis scripts
+examples/          # Usage examples for pmf_acls
+docs/              # Literature reviews, specs, notes
+reference/         # PMF2/ME2 reference binaries
+```
+
+## Running Tests
+
+```bash
+pytest pmf_acls/tests/ -v
+```