evomap.mapping._sammon
======================

.. py:module:: evomap.mapping._sammon

.. autoapi-nested-parse::

   Nonlinear Sammon Mapping, as proposed in:

   Sammon, J. W. (1969). A nonlinear mapping for data structure analysis. IEEE Transactions on computers, 100(5), 401-409.



Classes
-------

.. autoapisummary::

   evomap.mapping._sammon.Sammon


Functions
---------

.. autoapisummary::

   evomap.mapping._sammon._check_prepare_input_sammon
   evomap.mapping._sammon._sammon_stress_function
   evomap.mapping._sammon._sammon_stress_gradient


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

.. py:class:: Sammon(n_dims=2, n_iter=2000, n_iter_check=50, init=None, verbose=0, input_type='distance', max_halves=5, tol=0.001, n_inits=1, step_size=1)

   .. py:attribute:: n_dims
      :value: 2



   .. py:attribute:: n_iter
      :value: 2000



   .. py:attribute:: n_iter_check
      :value: 50



   .. py:attribute:: init
      :value: None



   .. py:attribute:: verbose
      :value: 0



   .. py:attribute:: input_type
      :value: 'distance'



   .. py:attribute:: max_halves
      :value: 5



   .. py:attribute:: tol
      :value: 0.001



   .. py:attribute:: n_inits
      :value: 1



   .. py:attribute:: step_size
      :value: 1



   .. py:attribute:: method_str
      :value: 'SAMMON'



   .. py:method:: __str__()

      Return a string representation of the Sammon instance with input_type and user-modified parameters.



   .. py:method:: fit(X)

      Fit the Sammon model to the input data.

      :param X: The input data. If `input_type` is 'vector', `X` should be the feature
                vectors of the samples. If `input_type` is 'distance', `X` should be
                the pairwise distance matrix.
      :type X: np.array of shape (n_samples, n_features) or (n_samples, n_samples)

      :returns: **self** -- Returns the instance of the Sammon class with the configuration matrix
                `Y_` stored as an attribute.
      :rtype: object



   .. py:method:: fit_transform(X)

      Fit the Sammon mapping model and return the transformed coordinates.

      :param X: The input data. If `input_type` is 'vector', `X` should be the feature
                vectors of the samples. If `input_type` is 'distance', `X` should be
                the pairwise distance matrix.
      :type X: np.array of shape (n_samples, n_features) or (n_samples, n_samples)

      :returns: The transformed coordinates of the samples in the reduced-dimensional space.
      :rtype: np.array of shape (n_samples, n_dims)

      :raises ValueError: If the `input_type` is not 'distance' or 'vector'.



.. py:function:: _check_prepare_input_sammon(D)

   Check and prepare the input distance matrix for Sammon Mapping.

   This function ensures that the input distance matrix is valid for Sammon Mapping.
   It checks for strictly positive off-diagonal dissimilarities and adds a small
   diagonal correction if necessary.

   :param D: Input distance matrix. Should be a square, symmetric matrix representing
             pairwise dissimilarities between samples.
   :type D: ndarray of shape (n_samples, n_samples)

   :returns: Prepared distance matrix with a diagonal correction applied.
   :rtype: ndarray of shape (n_samples, n_samples)

   :raises ValueError: If any off-diagonal entries in the distance matrix are non-positive.


.. py:function:: _sammon_stress_function(positions, disparities, compute_error=True, compute_grad=True)

   Compute the Sammon stress function and its gradient.

   The Sammon stress function measures the discrepancy between the input distances
   (disparities) and the distances among the estimated positions in the reduced space.
   Optionally, it can also compute the gradient of the stress function for optimization purposes.

   :param positions: The estimated positions of the samples in the reduced-dimensional space.
   :type positions: ndarray of shape (n_samples, n_dims)
   :param disparities: The input distance (or dissimilarity) matrix.
   :type disparities: ndarray of shape (n_samples, n_samples)
   :param compute_error: Whether to compute the stress (error) value, by default True.
   :type compute_error: bool, optional
   :param compute_grad: Whether to compute the gradient of the stress function, by default True.
   :type compute_grad: bool, optional

   :returns: * *float or None* -- The Sammon stress value (cost), or None if `compute_error` is False.
             * *ndarray or None* -- The gradient of the stress function, or None if `compute_grad` is False.


.. py:function:: _sammon_stress_gradient(Y, D_map, D)

   Compute the gradient of the Sammon stress function.

   :param Y: The current positions of the samples in the reduced-dimensional space.
   :type Y: ndarray of shape (n_samples, n_dims)
   :param D_map: The pairwise Euclidean distances between the estimated positions.
   :type D_map: ndarray of shape (n_samples, n_samples)
   :param D: The input distance (or dissimilarity) matrix.
   :type D: ndarray of shape (n_samples, n_samples)

   :returns: The computed gradient of the Sammon stress function, flattened for optimization.
   :rtype: ndarray of shape (n_samples * n_dims)