Metadata-Version: 2.1
Name: alphacsc
Version: 0.4.0rc7
Summary: Convolutional dictionary learning for noisy signals.
Home-page: https://github.com/alphacsc/alphacsc.git
Author-email: mainakjas@gmail.com
Maintainer: Mainak Jas
License: BSD (3-clause)
Platform: any
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: mne
Requires-Dist: numba
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: joblib
Requires-Dist: matplotlib
Requires-Dist: scikit-learn
Provides-Extra: dev
Requires-Dist: flake8 ; extra == 'dev'
Provides-Extra: dicodile
Requires-Dist: dicodile ; extra == 'dicodile'
Provides-Extra: doc
Requires-Dist: numpydoc ; extra == 'doc'
Requires-Dist: sphinx-bootstrap-theme ; extra == 'doc'
Requires-Dist: sphinx-gallery ; extra == 'doc'
Requires-Dist: pactools ; extra == 'doc'
Requires-Dist: nibabel ; extra == 'doc'
Requires-Dist: pooch ; extra == 'doc'
Requires-Dist: tqdm ; extra == 'doc'
Provides-Extra: test
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'

===================================================
alphaCSC: Convolution sparse coding for time-series
===================================================
|Build Status| |codecov|

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 alphacsc

(Development version)

.. code::

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

(Dicodile backend)

.. code::
   
   pip install numpy cython
   pip install alphacsc[dicodile]

To use dicodile backend, do not forget to set ``MPI_HOSTFILE`` environment
variable.


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.

.. |Build Status| image:: https://github.com/alphacsc/alphacsc/workflows/unittests/badge.svg
.. |codecov| image:: https://codecov.io/gh/alphacsc/alphacsc/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/alphacsc/alphacsc


