Metadata-Version: 2.1
Name: deepcola
Version: 0.0.0
Summary: COLA - Competitive layers for deep learning.
Home-page: https://github.com/pietrobarbiero/cola
Maintainer: P. Barbiero
Maintainer-email: barbiero@tutanota.com
License: Apache 2.0
Download-URL: https://github.com/pietrobarbiero/cola.git
Platform: UNKNOWN
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
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/x-rst
Requires-Dist: numpy
Requires-Dist: scikit-learn
Requires-Dist: tensorflow
Requires-Dist: tqdm
Provides-Extra: docs
Requires-Dist: sphinx ; extra == 'docs'
Requires-Dist: sphinx-gallery ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme ; extra == 'docs'
Requires-Dist: numpydoc ; extra == 'docs'
Requires-Dist: matplotlib ; extra == 'docs'
Provides-Extra: tests
Requires-Dist: pytest ; extra == 'tests'
Requires-Dist: pytest-cov ; extra == 'tests'

COLA - Competitive layers for deep learning
======================================================

COLA (COmpetitive LAyers) is a Python package providing the implementation of
gradient-based competitive layers which can be used on top of deep
learning models for unsupervised tasks.


.. image:: https://github.com/pietrobarbiero/deep-topological-learning/blob/master/deep_dual_figure.png
    :height: 300px


Theory
--------
Theoretical foundations can be found in our paper.

If you find COLA useful in your research, please consider citing the following paper::

    @misc{barbiero2020topological,
        title={Topological Gradient-based Competitive Learning},
        author={Pietro Barbiero and Gabriele Ciravegna and Vincenzo Randazzo and Giansalvo Cirrincione},
        year={2020},
        eprint={2008.09477},
        archivePrefix={arXiv},
        primaryClass={stat.ML}
    }

Examples
----------

Dual Competitive Layer (DCL)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::

    * - .. figure:: https://github.com/pietrobarbiero/deep-topological-learning/blob/master/test/test-results/circles_dynamic_dual.png
            :height: 200px

      - .. image:: https://github.com/pietrobarbiero/deep-topological-learning/blob/master/test/test-results/circles_scatter_dual.png
            :height: 200px


Vanilla Competitive Layer (VCL)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::

    * - .. figure:: https://github.com/pietrobarbiero/deep-topological-learning/blob/master/test/test-results/circles_dynamic_vanilla.png
            :height: 200px

      - .. image:: https://github.com/pietrobarbiero/deep-topological-learning/blob/master/test/test-results/circles_scatter_vanilla.png
            :height: 200px



Using COLA
---------------

.. code:: python

    from cola import DualModel, plot_confusion_matrix, scatterplot, scatterplot_dynamic

    X, y = ... # load dataset

    # load custom tensorflow layers
    inputs = Input(shape=(d,), name='input')
    ...
    outputs = ...

    # instantiate the dual model
    n = X.shape[0] # number of samples
    k = ... # upper bound of the desired number of prototypes
    model = DualModel(n_samples=n, k_prototypes=k, inputs=inputs, outputs=outputs, deep=False)
    model.compile(optimizer=optimizer)
    model.fit(X, y, epochs=epochs)

    # plot prototype dynamics
    plt.figure()
    scatterplot_dynamic(X, model.prototypes_, y, valid=True)
    plt.show()

    # plot confusion matrix
    # considering the prototypes estimated in the last epoch
    plt.figure()
    plot_confusion_matrix(x_pred, model.prototypes[-1], y)
    plt.show()

    # plot estimated topology
    # considering the prototypes estimated in the last epoch
    plt.figure()
    scatterplot(x_pred, model.prototypes[-1], y, valid=True)
    plt.show()



Authors
-------

`Pietro Barbiero <http://www.pietrobarbiero.eu/>`__

Licence
-------

Copyright 2020 Pietro Barbiero.

Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and
limitations under the License.

