tdads.machine_learning
======================

.. py:module:: tdads.machine_learning


Classes
-------

.. autoapisummary::

   tdads.machine_learning.diagram_mds
   tdads.machine_learning.diagram_kpca


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

.. py:class:: diagram_mds(n_components: int = 2, random_state: int = None, precomputed: bool = False, dim: int = 0, metric: str = 'W', p: float = 2, sigma: float = None, n_cores: int = cpu_count() - 1)

   Multidimensional scaling with persistence diagrams.


   .. py:method:: __str__()

      Describe a persistence diagram multidimensional scaling object via its distance metric.



   .. py:method:: fit_transform(X, y: any = None)

      Fit the data in X and compute the position of the persistence diagrams in the embedding space.

      :param `X`: Either a precomputed distance matrix of `n_diagrams` many persistence diagrams (if `precomputed` was set to `True`) or a list of `n_diagrams` many persistence diagrams (otherwise).
      :type `X`: {array-like of shape `(n_diagrams, n_diagrams)`} or {list of length `n_diagrams`}
      :param `y`: Not used, present for API consistency by convention.
      :type `y`: Ignored

      :returns: **`X_new`** -- `X` transformed in the new space.
      :rtype: ndarray of shape `(n_diagrams, n_components)`

      .. rubric:: Examples

      >>> from tdads.machine_learning import diagram_mds
      >>> from tdads.distance 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)
      >>> # project into 2D with the 2-wasserstein distance
      >>> mds = diagram_mds()
      >>> mds.fit_transform([D1, D2])
      >>> # can also fit with a precomputed distance matrix
      >>> d_wass = distance()
      >>> dist_mat = d_wass.compute_matrix([D1, D2])
      >>> mds_precomp = diagram_mds(precomputed = True)
      >>> mds_precomp.fit_transform(dist_mat)



.. py:class:: diagram_kpca(n_components: int = 2, random_state: int = None, precomputed: bool = False, diagrams: list = None, dim: int = 0, sigma: float = 1.0, t: float = 1.0, n_cores: int = cpu_count() - 1)

   Kernel PCA with persistence diagrams.


   .. py:method:: __str__()

      Describe a persistence diagram kernel principle components analysis object via its kernel function.



   .. py:method:: fit(X, y: any = None)

      Fit the model from data in X.

      :param `X`: Either a precomputed Gram matrix of `n_diagrams` many persistence diagrams (if `precomputed` was set to `True`) or a list of `n_diagrams` many persistence diagrams (otherwise).
      :type `X`: {array-like of shape `(n_diagrams, n_diagrams)`} or {list of length `n_diagrams`}
      :param `y`: Not used, present for API consistency by convention.
      :type `y`: Ignored

      :returns: **`self`** -- Returns the instance itself.
      :rtype: object

      .. rubric:: Examples

      >>> from tdads.machine_learning import diagram_mds
      >>> from tdads.kernel import kernel
      >>> 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)
      >>> # fit model with the persistence Fisher kernel (sigma = t = 1)
      >>> kpca = diagram_kpca()
      >>> kpca_fitted = kpca.fit([D1, D2])
      >>> # can also fit with a precomputed distance matrix
      >>> pfk = kernel()
      >>> gram_mat = pfk.compute_matrix([D1, D2])
      >>> kpca_precomp = diagram_kpca(precomputed = True)
      >>> kpca_precomp_fitted = kpca_precomp.fit(gram_mat)



   .. py:method:: transform(X)

      Project new persistence diagrams into the embedding space.

      :param `X`: Either a precomputed (cross) Gram matrix of shape `(n_new_diagrams, n_diagrams)` (between the new persistence diagrams and the
                  training set diagrams, if `precomputed` was set to `True`) or a list of `n_new_diagrams` many persistence diagrams (otherwise).
      :type `X`: {array-like of shape `(n_diagrams, n_diagrams)`} or {list of length `n_diagrams`}

      :returns: **`X_new`** -- The embedding of the new persistence diagrams.
      :rtype: ndarray

      .. rubric:: Examples

      >>> from tdads.machine_learning import diagram_mds
      >>> from tdads.kernel import kernel
      >>> 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)
      >>> # fit models (regular and precomputed) with the
      >>> # persistence Fisher kernel (sigma = t = 1)
      >>> kpca = diagram_kpca()
      >>> kpca_fitted = kpca.fit([D1, D2]) # or
      >>> pfk = kernel()
      >>> gram_mat = pfk.compute_matrix([D1, D2])
      >>> kpca_precomp = diagram_kpca(precomputed = True)
      >>> kpca_precomp_fitted = kpca_precomp.fit(gram_mat)
      >>> # create 2 new datasets
      >>> data3 = np.random((100,2))
      >>> data4 = np.random((100,2))
      >>> # project new data into 2D space
      >>> kpca_fitted.transform([D3, D4]) # or
      >>> cross_gram = pfk.compute_matrix([D1, D2], [D3, D4])
      >>> kpca_precomputed_fitted.transform([D3, D4])



   .. py:method:: fit_transform(X, y: any = None)

      Fit the data in X and compute the position of the persistence diagrams in the embedding space.

      :param `X`: Either a precomputed Gram matrix of `n_diagrams` many persistence diagrams (if `precomputed` was set to `True`) or a list of `n_diagrams` many persistence diagrams (otherwise).
      :type `X`: {array-like of shape `(n_diagrams, n_diagrams)`} or {list of length `n_diagrams`}
      :param `y`: Not used, present for API consistency by convention.
      :type `y`: Ignored

      :returns: **`X_new`** -- `X` transformed in the new space.
      :rtype: ndarray

      .. rubric:: Examples

      >>> from tdads.machine_learning import diagram_mds
      >>> from tdads.kernel import kernel
      >>> 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)
      >>> # fit models (regular and precomputed) with the
      >>> # persistence Fisher kernel (sigma = t = 1) and
      >>> # project into 2D space
      >>> kpca = diagram_kpca()
      >>> kpca.fit_transform([D1, D2]) # or
      >>> pfk = kernel()
      >>> gram_mat = pfk.compute_matrix([D1, D2])
      >>> kpca_precomp = diagram_kpca(precomputed = True)
      >>> kpca_precomp.fit_transform(gram_mat)