Metadata-Version: 2.4
Name: dictlearn
Version: 1.0.0
Summary: Dictionary learning and sparse coding toolbox: K-SVD family, kernel and discriminative dictionary learning, classification and anomaly detection
Author-email: Paul Irofti <paul@irofti.net>, Denis Ilie-Ablachim <denis.ilie_ablachim@upb.ro>, Bogdan Dumitrescu <bogdan.dumitrescu@upb.ro>
License-Expression: ISC
Project-URL: Homepage, https://gitlab.com/unibuc/graphomaly/dictionary-learning
Project-URL: Documentation, https://unibuc.gitlab.io/graphomaly/dictionary-learning/
Project-URL: Source, https://gitlab.com/unibuc/graphomaly/dictionary-learning
Keywords: dictionary learning,sparse coding,sparse representations,K-SVD,OMP,anomaly detection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.6
Provides-Extra: numba
Requires-Dist: numba>=0.59; extra == "numba"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: build; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Requires-Dist: sphinx-gallery; extra == "docs"
Requires-Dist: numpydoc; extra == "docs"
Requires-Dist: matplotlib; extra == "docs"
Dynamic: license-file

# dictlearn: Dictionary Learning Toolbox

[![PyPI](https://img.shields.io/pypi/v/dictlearn)](https://pypi.org/project/dictlearn/)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)

Dictionary learning and sparse representations in Python, with a
scikit-learn compatible API.

- **Dictionary learning**: K-SVD, approximate K-SVD (with and without
  updated error), SGK, NSGK, MOD and Sparsenet updates, with independent
  options for parallel atom updates, regularization and coherence
  reduction; dictionary learning with an l1 penalty (APrU); online and
  mini-batch learning with `partial_fit` (Mairal et al., OCDDL, RLSDL);
  kernel dictionary learning; non-negative dictionary learning;
  dictionaries with cone atoms and with Gaussian atoms.
- **Sparse coding**: Batch-OMP in the Gram domain (optionally
  JIT-compiled with numba), ISTA/FISTA, IHT, CoSaMP, SOMP, non-negative
  OMP, DSC-entmax, and delegates to scikit-learn's LARS, Lasso and
  elastic net. One registry serves the linear and the kernel estimators
  and accepts user-defined coders through `register_coder`.
- **Classification** (`dictlearn.classification`): sparse
  representation-based classification (SRC), discriminative K-SVD,
  label-consistent K-SVD and dictionary pair learning (DPL), each with a
  kernel counterpart.
- **Anomaly detection** (`dictlearn.anomaly`): reconstruction-error
  outlier detection on top of any of the dictionary learning estimators.

The package accompanies the book

> B. Dumitrescu and P. Irofti, *Dictionary Learning Algorithms and
> Applications*, Springer, 2018, doi:10.1007/978-3-319-78674-2

and implements the later work of the authors. Development was
supported in part by the [Graphomaly research
grant](http://graphomaly.upb.ro/). Documentation:
<https://unibuc.gitlab.io/graphomaly/dictionary-learning/>.

## Installation

```bash
pip install dictlearn            # core (NumPy, SciPy, scikit-learn)
pip install dictlearn[numba]     # + JIT-compiled sparse coding
```

Requires Python 3.10 or newer and scikit-learn 1.6 or newer.

## Quick start

```python
from dictlearn import DictionaryLearning
from sklearn.datasets import make_sparse_coded_signal

X, _, _ = make_sparse_coded_signal(
    n_samples=500, n_components=128, n_features=64,
    n_nonzero_coefs=8, random_state=0,
)

dl = DictionaryLearning(
    n_components=128,
    fit_algorithm="aksvd",       # sparsenet | ksvd | aksvd | uaksvd | sgk | nsgk | mod | apru
    n_nonzero_coefs=8,
    max_iter=20,
    random_state=0,
).fit(X)

codes = dl.transform(X)          # sparse codes, shape (n_samples, n_components)
X_hat = dl.inverse_transform(codes)
print(dl.error_[-1])             # training error curve
```

Classification and anomaly detection follow the same conventions:

```python
from dictlearn.classification import LCDLClassifier
clf = LCDLClassifier(n_components=8, alpha=1.0, beta=1.0, random_state=0)
clf.fit(X_train, y_train)
y_pred = clf.predict(X_test)

from dictlearn.anomaly import DictionaryLearningDetector
det = DictionaryLearningDetector(n_components=64, contamination=0.05).fit(X)
labels = det.predict(X)          # +1 inlier, -1 outlier
```

All estimators are checked with scikit-learn's `check_estimator` suite
(see `tests/test_sklearn_compliance.py`), work in `Pipeline` and
`GridSearchCV`, and are reproducible through `random_state`.

## Citation

If you use this package in your research, please cite the book:

```bibtex
@book{DL_book,
  author    = {Dumitrescu, Bogdan and Irofti, Paul},
  title     = {Dictionary Learning Algorithms and Applications},
  year      = {2018},
  publisher = {Springer},
  doi       = {10.1007/978-3-319-78674-2},
}
```

The references for the individual algorithms are listed in the
documentation.

## Development

```bash
git clone https://gitlab.com/unibuc/graphomaly/dictionary-learning
cd dictionary-learning
pip install -e .[dev]
pytest                # test suite
ruff check src tests  # lint
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution guide and
[CHANGELOG.md](CHANGELOG.md) for release notes. Licensed under the
[ISC license](LICENSE).
