Metadata-Version: 2.4
Name: pnmf
Version: 0.1.0
Summary: Probabilistic Non-negative Matrix Factorization with Projected Gradients
Home-page: https://github.com/luisdiaz1997/Probabilistic-NMF
Author: Luis Chumpitaz Diaz
Author-email: Luis Chumpitaz Diaz <luisdiaz1997@example.com>
License: GPL-2.0-only
Project-URL: Homepage, https://github.com/luisdiaz1997/Probabilistic-NMF
Project-URL: Repository, https://github.com/luisdiaz1997/Probabilistic-NMF
Project-URL: Issues, https://github.com/luisdiaz1997/Probabilistic-NMF/issues
Keywords: nmf,non-negative matrix factorization,probabilistic,machine learning,pytorch
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=1.9.0
Requires-Dist: numpy>=1.19.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# PNMF: Probabilistic Non-negative Matrix Factorization

A PyTorch-based implementation of Probabilistic NMF with projected gradient optimization, compatible with scikit-learn's API.

## Installation

```bash
pip install pnmf
```

For development installation:

```bash
git clone https://github.com/luisdiaz1997/Probabilistic-NMF.git
cd Probabilistic-NMF
pip install -e .
```

## Quick Start

```python
from PNMF import PNMF
import numpy as np

# Create some sample data
X = np.random.rand(100, 50)

# Initialize and fit the model
model = PNMF(n_components=5, init='random', random_state=42)
W = model.fit_transform(X)  # Transformed data: (100, 5)
H = model.components_       # Components: (5, 50)

# Reconstruct the data
X_reconstructed = model.inverse_transform(W)
```

## Model

PNMF uses a Poisson likelihood for the observed data:

- y<sub>ij</sub> ~ Poisson(λ<sub>ij</sub>)
- λ<sub>ij</sub> = Σ<sub>l</sub> W<sub>jl</sub> exp(F<sub>il</sub>)
- F<sub>il</sub> ~ N(0, σ²)

where **W** ≥ 0 are the loadings and **F** are the latent factors (variational inference with Gaussian prior).

## Features

- **Probabilistic NMF**: Uses Poisson factorization for count data
- **Projected Gradients**: Three modes for enforcing non-negativity:
  - `softplus`: Uses softplus transformation
  - `exp`: Uses exponential transformation
  - `projected`: Uses projected gradient descent (default)
- **sklearn-compatible API**: Works seamlessly with scikit-learn workflows
- **GPU Support**: Automatic CUDA detection and utilization

## API Reference

### `PNMF(n_components=2, init='random', init_mode='projected', max_iter=200, tol=1e-4, learning_rate=0.01, random_state=None, verbose=False, device='auto')`

Parameters:
- `n_components`: Number of latent components (default: 2)
- `init`: Initialization method - 'random' or 'custom' (default: 'random')
- `init_mode`: Non-negativity enforcement - 'softplus', 'exp', or 'projected' (default: 'projected')
- `max_iter`: Maximum number of iterations (default: 200)
- `tol`: Tolerance for convergence (default: 1e-4)
- `learning_rate`: Learning rate for gradient descent (default: 0.01)
- `random_state`: Random seed for reproducibility (default: None)
- `verbose`: Whether to print progress messages (default: False)
- `device`: Device to use - 'cpu', 'cuda', or 'auto' (default: 'auto')

Methods:
- `fit(X, y=None, W=None, H=None)`: Fit the model to data X
- `transform(X)`: Transform X using the fitted model
- `fit_transform(X, **kwargs)`: Fit the model and transform X
- `inverse_transform(H)`: Transform data back to original space

## License

GNU General Public License v2.0

## Author

Luis Chumpitaz Diaz

## Acknowledgments

This implementation borrows code from [GPzoo](https://github.com/luisdiaz1997/GPzoo).
