dictlearn: Dictionary Learning Toolbox

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. Documentation: https://unibuc.gitlab.io/graphomaly/dictionary-learning/.

Installation

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

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:

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:

@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

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 for the contribution guide and CHANGELOG.md for release notes. Licensed under the ISC license.