.. role:: py(code)
   :language: python

Dictances
==========

|travis| |coveralls| |sonar_quality| |sonar_maintainability| |code_climate_maintainability| |code_climate_test_coverage| |pip|

Distances and divergences between dictionaries implemented in python 3.6.

In the complexity notations, :py:`n` is :py:`len(a)` and :py:`m` is :py:`len(b)`.

The samples are dictionaries generated by the `test utilities here`_.

How do I get it?
----------------
Just type into your terminal:

.. code:: shell

   pip install dictances


Basic example
--------------
For each metric, an example is present in `the folder examples`_. Here's a basic example for those too lazy to click links (like me).

.. code:: python

    import random
    from dictances import cosine, euclidean, canberra
    random.seed(42) # for reproducibility

    # Simple function to generate the example dictionaries
    def generate_example_dict(n=1000):
        return {random.randint(0,1000):random.uniform(0,1000) for i in range(n)}

    a, b = generate_example_dict(), generate_example_dict()

    print(cosine(a,b))
    # >>> 0.52336690346601

    print(euclidean(a,b))
    # >>> 15119.400349404095

    print(canberra(a,b))
    # >>> 624.9088876554047


Metrics table
--------------

+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| Metric name                    | Usage example                 | Average time on sample      | Complexity                           |
+================================+===============================+=============================+======================================+
| `Euclidean distance`_          | `euclidean`_                  | 53.7 µs ± 981 ns            | |On+m|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| Squared variation              | `squared_variation`_          | 50.6 µs ± 982 ns            | |On+m|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| `Total variation`_             | `total_variation`_            | 50.6 µs ± 2.75 µs           | |On+m|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| Nth variation                  | `nth_variation`_              | 50.6 µs ± 1.07 µs           | |On+m|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| `Manhattan distance`_          | `manhattan`_                  | 51 µs ± 1.2 µs              | |On+m|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| `Mean absolute error`_         | `mae`_                        | 51.9 µs ± 2.4 µs            | |On+m|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| `Mean squared error`_          | `mse`_                        | 51.8 µs ± 1.67 µs           | |On+m|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| `Chebyshev distance`_          | `chebyshev`_                  | 49.8 µs ± 628 ns            | |On+m|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| `Minkowski distance`_          | `minkowsky`_                  | 50.4 µs ± 2.94 µs           | |On+m|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| `Canberra distance`_           | `canberra`_                   | 30.9 µs ± 340 ns            | |On+m|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| `Cosine distance`_             | `cosine`_                     | 41.7 µs ± 1.42 µs           | |On+m|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| `Pearson distance`_            | `pearson`_                    | 49.8 µs ± 2.51 µs           | |On+m|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| `Hamming distance`_            | `hamming`_                    | 5.57 µs ± 191 ns            | |Omin|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| `Kullback Leibler divergence`_ | `kullback_leibler`_           | 31.6 µs ± 591 ns            | |Omin|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| `Jensen Shannon divergence`_   | `jensen_shannon`_             | 21.1 µs ± 442 ns            | |Omin|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| `Bhattacharyya distance`_      | `bhattacharyya`_              | 13.7 µs ± 71.9 ns           | |Omin|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+
| `Hellinger distance`_          | `hellinger`_                  | 16.8 µs ± 372 ns            | |Omin|                               |
+--------------------------------+-------------------------------+-----------------------------+--------------------------------------+

Test computer specifications
----------------------------

The computer on which the metrics where timed had the following specifications:

+---------------------------------------+
| Computer specifications               |
+=======================+===============+
| Model Name            | MacBook Pro   |
+-----------------------+---------------+
| Processor Name        | Intel Core i7 |
+-----------------------+---------------+
| Processor Speed       | 2.3 GHz       |
+-----------------------+---------------+
| Number of Processors  | 1             |
+-----------------------+---------------+
| Total Number of Cores | 4             |
+-----------------------+---------------+
| L2 Cache (per Core)   | 256 KB        |
+-----------------------+---------------+
| L3 Cache              | 6 MB          |
+-----------------------+---------------+
| Memory                | 16 GB         |
+-----------------------+---------------+

.. |travis| image:: https://travis-ci.org/LucaCappelletti94/dictances.png
   :target: https://travis-ci.org/LucaCappelletti94/dictances

.. |coveralls| image:: https://coveralls.io/repos/github/LucaCappelletti94/distances/badge.svg?branch=master
    :target: https://coveralls.io/github/LucaCappelletti94/distances

.. |sonar_quality| image:: https://sonarcloud.io/api/project_badges/measure?project=dictances.lucacappelletti&metric=alert_status
    :target: https://sonarcloud.io/dashboard/index/dictances.lucacappelletti

.. |sonar_maintainability| image:: https://sonarcloud.io/api/project_badges/measure?project=dictances.lucacappelletti&metric=sqale_rating
    :target: https://sonarcloud.io/dashboard/index/dictances.lucacappelletti

.. |code_climate_maintainability| image:: https://api.codeclimate.com/v1/badges/25fb7c6119e188dbd12c/maintainability
   :target: https://codeclimate.com/github/LucaCappelletti94/dictances/maintainability
   :alt: Maintainability

.. |code_climate_test_coverage| image:: https://api.codeclimate.com/v1/badges/25fb7c6119e188dbd12c/test_coverage
   :target: https://codeclimate.com/github/LucaCappelletti94/dictances/test_coverage
   :alt: Test Coverage

.. |pip| image:: https://badge.fury.io/py/dictances.svg
    :target: https://badge.fury.io/py/dictances

.. _Euclidean distance: https://en.wikipedia.org/wiki/Euclidean_distance
.. _Manhattan distance: https://en.wikipedia.org/wiki/Taxicab_geometry
.. _Jensen Shannon divergence: https://en.wikipedia.org/wiki/Jensen%E2%80%93Shannon_divergence
.. _Bhattacharyya distance: https://en.wikipedia.org/wiki/Bhattacharyya_distance
.. _Total variation: https://en.wikipedia.org/wiki/Total_variation
.. _Hellinger distance: https://en.wikipedia.org/wiki/Hellinger_distance
.. _Kullback Leibler divergence: https://en.wikipedia.org/wiki/Hellinger_distance
.. _Mean absolute error: https://en.wikipedia.org/wiki/Mean_absolute_error
.. _Mean squared error: https://en.wikipedia.org/wiki/Mean_squared_error
.. _Chebyshev distance: https://en.wikipedia.org/wiki/Chebyshev_distance
.. _Minkowski distance: https://en.wikipedia.org/wiki/Minkowski_distance
.. _Canberra distance: https://en.wikipedia.org/wiki/Canberra_distance
.. _Cosine distance: https://en.wikipedia.org/wiki/Cosine_similarity
.. _Pearson distance: https://en.wikipedia.org/wiki/Pearson_correlation_coefficient
.. _Hamming distance: https://en.wikipedia.org/wiki/Hamming_distance

.. _euclidean: https://github.com/LucaCappelletti94/distances/blob/master/examples/euclidean.py
.. _jensen_shannon: https://github.com/LucaCappelletti94/distances/blob/master/examples/jensen_shannon.py
.. _bhattacharyya: https://github.com/LucaCappelletti94/distances/blob/master/examples/bhattacharyya.py
.. _total_variation: https://github.com/LucaCappelletti94/distances/blob/master/examples/total_variation.py
.. _squared_variation: https://github.com/LucaCappelletti94/distances/blob/master/examples/squared_variation.py
.. _nth_variation: https://github.com/LucaCappelletti94/distances/blob/master/examples/nth_variation.py
.. _hellinger: https://github.com/LucaCappelletti94/distances/blob/master/examples/hellinger.py
.. _kullback_leibler: https://github.com/LucaCappelletti94/distances/blob/master/examples/kullback_leibler.py
.. _manhattan: https://github.com/LucaCappelletti94/distances/blob/master/examples/manhattan.py
.. _mae: https://github.com/LucaCappelletti94/distances/blob/master/examples/mae.py
.. _mse: https://github.com/LucaCappelletti94/distances/blob/master/examples/mse.py
.. _chebyshev: https://github.com/LucaCappelletti94/distances/blob/master/examples/chebyshev.py
.. _minkowsky: https://github.com/LucaCappelletti94/distances/blob/master/examples/minkowski.py
.. _canberra: https://github.com/LucaCappelletti94/distances/blob/master/examples/canberra.py
.. _cosine: https://github.com/LucaCappelletti94/distances/blob/master/examples/cosine.py
.. _pearson: https://github.com/LucaCappelletti94/distances/blob/master/examples/pearson.py
.. _hamming: https://github.com/LucaCappelletti94/distances/blob/master/examples/hamming.py

.. _test utilities here: https://github.com/LucaCappelletti94/distances/blob/master/tests/helpers/utils.py
.. _the folder examples: https://github.com/LucaCappelletti94/distances/tree/master/examples

.. |On+m| image:: https://github.com/LucaCappelletti94/distances/blob/master/images/On+m.gif?raw=true
.. |Omin| image:: https://github.com/LucaCappelletti94/distances/blob/master/images/Omin.gif?raw=true
