=================================================== alphaCSC: Convolution sparse coding for time-series

.. image:: https://api.travis-ci.org/alphacsc/alphacsc.svg?branch=master :target: https://travis-ci.org/alphacsc/alphacsc :alt: Build Status

.. image:: https://codecov.io/github/alphacsc/alphacsc/coverage.svg?precision=0 :target: https://codecov.io/gh/alphacsc/alphacsc :alt: Test coverage

This is a library to perform shift-invariant sparse dictionary learning <https://en.wikipedia.org/wiki/Sparse_dictionary_learning>_, also known as convolutional sparse coding (CSC), on time-series data. It includes a number of different models:

1. univariate CSC
2. multivariate CSC
3. multivariate CSC with a rank-1 constraint [1]_
4. univariate CSC with an alpha-stable distribution [2]_

A mathematical descriptions of these models is available in the documentation <https://alphacsc.github.io/models.html>_.

Installation

To install this package, the easiest way is using pip. It will install this package and its dependencies. The setup.py depends on numpy and cython for the installation so it is advised to install them beforehand. To install this package, please run one of the two commands:

(Latest stable version)

.. code::

pip install numpy cython
pip install alphacsc

(Development version)

.. code::

pip install numpy cython
pip install git+https://github.com/alphacsc/alphacsc.git#egg=alphacsc

If you do not have admin privileges on the computer, use the --user flag with pip. To upgrade, use the --upgrade flag provided by pip.

To check if everything worked fine, you can run:

.. code::

python -c 'import alphacsc'

and it should not give any error messages.

Quickstart

Here is an example to present briefly the API:

.. code:: python

import numpy as np
import matplotlib.pyplot as plt
from alphacsc import BatchCDL

# Define the different dimensions of the problem
n_atoms = 10
n_times_atom = 50
n_channels = 5
n_trials = 10
n_times = 1000

# Generate a random set of signals
X = np.random.randn(n_trials, n_channels, n_times)

# Learn a dictionary with batch algorithm and rank1 constraints.
cdl = BatchCDL(n_atoms, n_times_atom, rank1=True)
cdl.fit(X)

# Display the learned atoms
fig, axes = plt.subplots(n_atoms, 2, num="Dictionary")
for k in range(n_atoms):
    axes[k, 0].plot(cdl.u_hat_[k])
    axes[k, 1].plot(cdl.v_hat_[k])

axes[0, 0].set_title("Spatial map")
axes[0, 1].set_title("Temporal map")
for ax in axes.ravel():
    ax.set_xticklabels([])
    ax.set_yticklabels([])

plt.show()

Bug reports

Use the github issue tracker <https://github.com/alphacsc/alphacsc/issues>_ to report bugs.

Cite our work

If you use this code in your project, please consider citing our work:

.. [1] Dupré La Tour, T., Moreau, T., Jas, M., & Gramfort, A. (2018). Multivariate Convolutional Sparse Coding for Electromagnetic Brain Signals <https://arxiv.org/abs/1805.09654v2>_. Advances in Neural Information Processing Systems (NIPS).

.. [2] Jas, M., Dupré La Tour, T., Şimşekli, U., & Gramfort, A. (2017). Learning the Morphology of Brain Signals Using Alpha-Stable Convolutional Sparse Coding <https://papers.nips.cc/paper/6710-learning-the-morphology-of-brain-signals-using-alpha-stable-convolutional-sparse-coding.pdf>_. Advances in Neural Information Processing Systems (NIPS), pages 1099--1108.