SPAMS: a SPArse Modeling Software

Here is the Python package interfacing the SPAMS C++ library.

What is SPAMS?

SPAMS (SPArse Modeling Software) is an optimization toolbox for solving various sparse estimation problems.

• Dictionary learning and matrix factorization (NMF, sparse PCA, ...)
• Solving sparse decomposition problems with LARS, coordinate descent, OMP, SOMP, proximal methods
• Solving structured sparse decomposition problems (l1/l2, l1/linf, sparse group lasso, tree-structured regularization, structured sparsity with overlapping groups, ...)

Installation

Requirements

• a C++ modern compiler (tested with gcc >= 4.5)
• a BLAS/LAPACK library (like OpenBLAS, Intel MKL, Atlas)

Carefully install libblas & liblapack. For example, on Ubuntu, it is necessary to do sudo apt-get -y install libblas-dev liblapack-dev gfortran. For MacOS, you most likely need to do brew install gcc openblas lapack.

For better performance, we recommend to install the MKL Intel library (available for instance on PyPI with pip install mkl, or in the Anaconda Python distribution with conda install mkl) before installing Numpy (which is a dependency of SPAMS, the latter checking Numpy configuration for its installation).

SPAMS for Python was tested on Linux and MacOS. It is not available for Windows at the moment. For MacOS users, the install setup detects if OpenMP is available on your system and enable/disable OpenMP support accordingly. For better performance, we recommend to install an OpenMP-compatible compiler on your system (e.g. gcc or llvm).

Note for Windows users: at the moment you can run pip install spams-bin (provided by https://github.com/samuelstjean/spams-python).

Installation from PyPI:

The standard installation uses the BLAS and LAPACK libraries used by Numpy:

pip install spams

Installation from sources

Make sure you have install libblas & liblapack (see above)

git clone https://github.com/getspams/spams-python
cd spams-python
pip install -e .

Usage

Manipulated objects are imported from numpy and scipy. Matrices should be stored by columns, and sparse matrices should be "column compressed".

Testing the interface

• From the command line (to be called from the project root directory):

python tests/test_spams.py -h       # print the man page
python tests/test_spams.py          # run all the tests

• From Python (assuming spams package is installed):

from spams.tests import test_spams

test_spams('-h')                    # print the man page
test_spams()                        # run all tests
test_spams(['sort', 'calcAAt'])     # run specific tests
test_spams(python_exec='python3')   # specify the python exec

• From the command line (assuming spams package is installed):

# c.f. previous point for the different options
python -c "from spams.tests import test_spams; test_spams()"

---

Links

• Official website (documentation and downloads)
• Python specific project and PyPI repository (available with pip install spams)
• R specific project (available with remotes::install_github("getspams/spams-R"))
• Original C++ project (and original sources for Matlab, Python and R interfaces)

SPAMS-related git repositories are also available on Inria gitlab forge: see original C++ project (and original sources for Matlab, Python and R interfaces), Python specific project

Contact

Regarding SPAMS Python package: you can open an issue on the dedicated git project at https://github.com/getspams/spams-python

Regarding SPAMS R package: you can open an issue on the dedicated git project at https://github.com/getspams/spams-R

For any other question related to the use or development of SPAMS:

• you can you can contact us at spams.dev'AT'inria.fr (replace 'AT' by @)
• you can open an issue on the general git project at https://github.com/getspams/spams-devel

---

Authorship

SPAMS is developed and maintained by Julien Mairal (Inria), and contains sparse estimation methods resulting from collaborations with various people: notably, Francis Bach, Jean Ponce, Guillermo Sapiro, Rodolphe Jenatton and Guillaume Obozinski.

It is coded in C++ with a Matlab interface. Interfaces for R and Python have been developed by Jean-Paul Chieze, and archetypal analysis was written by Yuansi Chen.

Release of version 2.6/2.6.1 and porting to R-3.x and Python3.x was done by Ghislain Durif (Inria). The original porting to Python3.x is based on this patch and on the work of John Kirkham available here.

Version 2.6.2 (Python only) update is based on contributions by Francois Rheault and Samuel Saint-Jean.

Maintenance

Since version 2.6.3+, SPAMS (especially the Python version) is now maintained by the following team:

• Alessandro Daducci
• Ghislain Durif
• Francois Rheault
• Samuel Saint-Jean

---

Funding

This work was supported in part by the SIERRA and VIDEOWORLD ERC projects, and by the MACARON ANR project.

License

Version 2.1 and later are open-source under GPLv3 licence. For other licenses, please contact the authors.

---

News

• 14/02/2022: Python SPAMS is now officially hosted on Github
• 07/02/2022: SPAMS C++ project and SPAMS for R are now officially hosted on Github
• 03/02/2022: Python SPAMS v2.6.3 is released (source and PyPI)
• 03/09/2020: Python SPAMS v2.6.2 is released (source and PyPI)
• 15/01/2019: Python SPAMS v2.6.1 is available on PyPI)
• 08/12/2017: Python SPAMS v2.6.1 for Anaconda (with MKL support) is released
• 24/08/2017: Python SPAMS v2.6.1 is released (a single source code for Python 3 and 2)
• 27/02/2017: SPAMS v2.6 is released, including precompiled Matlab packages, R-3.x and Python3.x compatibility
• 25/05/2014: SPAMS v2.5 is released
• 12/05/2013: SPAMS v2.4 is released
• 05/23/2012: SPAMS v2.3 is released
• 03/24/2012: SPAMS v2.2 is released with a Python and R interface, and new compilation scripts for a better Windows/Mac OS compatibility
• 06/30/2011: SPAMS v2.1 goes open-source!
• 11/04/2010: SPAMS v2.0 is out for Linux and Mac OS!
• 02/23/2010: Windows 32 bits version available! Elastic-Net is implemented
• 10/26/2009: Mac OS, 64 bits version available!

---

References

A monograph about sparse estimation

We encourage the users of SPAMS to read the following monograph, which contains numerous applications of dictionary learning, an introduction to sparse modeling, and many practical advices.

• J. Mairal, F. Bach and J. Ponce. Sparse Modeling for Image and Visio Processing. Foundations and Trends in Computer Graphics and Vision. vol 8. number 2-3. pages 85--283. 2014

Related publications

You can find here some publications at the origin of this software.

The "matrix factorization" and "sparse decomposition" modules were developed for the following papers:

• J. Mairal, F. Bach, J. Ponce and G. Sapiro. Online Learning for Matrix Factorization and Sparse Coding. Journal of Machine Learning Research, volume 11, pages 19-60. 2010.
• J. Mairal, F. Bach, J. Ponce and G. Sapiro. Online Dictionary Learning for Sparse Coding. International Conference on Machine Learning, Montreal, Canada, 2009

The "proximal" module was developed for the following papers:

• J. Mairal, R. Jenatton, G. Obozinski and F. Bach. Network Flow Algorithms for Structured Sparsity. Adv. Neural Information Processing Systems (NIPS). 2010.
• R. Jenatton, J. Mairal, G. Obozinski and F. Bach. Proximal Methods for Sparse Hierarchical Dictionary Learning. International Conference on Machine Learning. 2010.

The feature selection tools for graphs were developed for:

• J. Mairal and B. Yu. Supervised Feature Selection in Graphs with Path Coding Penalties and Network Flows. JMLR. 2013.

The incremental and stochastic proximal gradient algorithm correspond to the following papers:

• J. Mairal. Stochastic Majorization-Minimization Algorithms for Large-Scale Optimization. NIPS. 2013.
• J. Mairal. Optimization with First-Order Surrogate Functions. International Conference on Machine Learning. 2013.