tdads.distance
==============

.. py:module:: tdads.distance


Classes
-------

.. autoapisummary::

   tdads.distance.distance


Module Contents
---------------

.. py:class:: distance(dim: int = 0, metric='W', p: float = 2.0, sigma: float = None, inf_replace_val: float = None, n_cores: int = cpu_count() - 1)

   .. py:method:: __str__()

      Describe a distance metric by type (Wasserstein, bottleneck or
      Fisher information metric) and major parameter (`p` for Wasserstein and
      `sigma` for Fisher information metric).



   .. py:method:: compute(D1, D2) -> float

      Compute the distance between two persistence diagrams.

      :param `D1`: The first persistence diagram (computed from either the ripser, gph, flagser, gudhi or cechmate packages).
      :type `D1`: any
      :param `D2`: The second persistence diagram ("").
      :type `D2`: any

      :returns: The numeric distance calculation value. In dimension 0 persistence diagrams may contain a point whose death is inf,
                and these points are ignored (if you wish to use these points make sure to replace inf with the maximum filtration value
                you used to compute the diagram).
      :rtype: float

      .. rubric:: Examples

      >>> from tdads import distance
      >>> from ripser import ripser
      >>> import numpy as np
      >>> # create 2 datasets
      >>> data1 = np.random((100,2))
      >>> data2 = np.random((100,2))
      >>> # compute persistence diagrams with ripser
      >>> diagram1 = ripser(data1)
      >>> diagram2 = ripser(data2)
      >>> # create distance object
      >>> d_wass = distance() # 2-wasserstein distance
      >>> # compute distance
      >>> d_wass.compute(diagram1, diagrams2)

      Citations
      ---------
      Kerber M, Morozov D and Nigmetov A (2017). "Geometry Helps to Compare Persistence Diagrams." https://dl.acm.org/doi/10.1145/3064175.

      Le T, Yamada M (2018). "Persistence fisher kernel: a riemannian manifold kernel for persistence diagrams." https://proceedings.neurips.cc/paper/2018/file/959ab9a0695c467e7caf75431a872e5c-Paper.pdf.

      Vlad I. Morariu, Balaji Vasan Srinivasan, Vikas C. Raykar, Ramani Duraiswami, and Larry S. Davis. Automatic online tuning for fast Gaussian summation. Advances in Neural Information Processing Systems (NIPS), 2008.



   .. py:method:: compute_matrix(diagrams: list, other_diagrams: list = None)

      Compute a distance matrix between one or two lists of persistence diagrams.
      :param `diagrams`: The first first of persistence diagram (computed from either the ripser, gph, flagser, gudhi or cechmate packages).
      :type `diagrams`: list
      :param `other_diagrams`: The optional second list of persistence diagram for computing a cross-distance matrix. Default `None`.
      :type `other_diagrams`: any

      :returns: The (cross) distance matrix.
      :rtype: numpy.ndarray

      .. rubric:: Examples

      >>> from tdads import distance
      >>> from ripser import ripser
      >>> import numpy as np
      >>> # create 2 datasets
      >>> data1 = np.random((100,2))
      >>> data2 = np.random((100,2))
      >>> # compute persistence diagrams with ripser
      >>> diagram1 = ripser(data1)
      >>> diagram2 = ripser(data2)
      >>> # create distance object
      >>> d_wass = distance() # 2-wasserstein distance
      >>> # compute distance matrix
      >>> d_wass.compute_matrix([diagram1, diagram2])
      >>> # this is the same as:
      >>> d_wass.compute_matrix([diagram1, diagram2], [diagram1, diagram2])