evomap.mapping._mds
===================

.. py:module:: evomap.mapping._mds

.. autoapi-nested-parse::

   Stress-Based Multidimensional Scaling.



Attributes
----------

.. autoapisummary::

   evomap.mapping._mds.EPSILON


Classes
-------

.. autoapisummary::

   evomap.mapping._mds.MDS


Functions
---------

.. autoapisummary::

   evomap.mapping._mds._normalized_stress_function
   evomap.mapping._mds._normalized_stress_gradient


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

.. py:data:: EPSILON
   :value: 1e-10


.. py:class:: MDS(n_dims=2, mds_type=None, 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:: mds_type
      :value: None



   .. 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: 'MDS'



   .. py:method:: __str__()

      Create a string representation of the MDS instance. Displays the key attributes and
      all parameters modified by the user.

      :returns: A summary of the key attributes of this MDS object, including modified parameters.
      :rtype: str



   .. py:method:: fit(X)

      Fit the MDS model to the input data, without returning the
      transformed positions.

      :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
                a pairwise distance matrix.
      :type X: np.array of shape (n_samples, n_features) or (n_samples, n_samples)

      :returns: **self** -- The instance of the MDS class, after fitting the model to the input data.
      :rtype: object



   .. py:method:: fit_transform(X)

      Fit the MDS model to the input data and return transformed positions.

      Dependning on 'input_type', the input data is either interpreted as a distance matrix or feature vectors.
      The method uses gradient descent to optimize the lower-dimensional positions such that a Stress function,
      measuring the discrepancy between the input distances and resulting configuration, is minimized.

      :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
                a pairwise distance matrix.
      :type X: np.array of shape (n_samples, n_features) or (n_samples, n_samples)

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

      :raises ValueError: If `input_type` is neither 'distance' nor 'vector', a ValueError is raised.



.. py:function:: _normalized_stress_function(positions, disparities, mds_type=None, compute_error=True, compute_grad=True)

   Compute normalized stress and its gradient.

   The stress function quantifies the goodness-of-fit between the input
   disparities (or distances) and the Euclidean distances in the low-dimensional
   space, with options for different MDS types: absolute, ratio, interval, and
   ordinal scaling. The input distances are transformed to disparities according to the mds type.
   Optionally, the function also computes the gradient to be used in optimization.

   :param positions: The estimated positions in the low-dimensional space.
   :type positions: np.array of shape (n_samples, n_dims)
   :param disparities: The input distances or disparities matrix, depending on the MDS type.
   :type disparities: np.array of shape (n_samples, n_samples)
   :param mds_type: The type of MDS scaling to use: 'absolute', 'ratio', 'interval',
                    or 'ordinal'. If None, 'absolute' scaling is used by default.
   :type mds_type: str, optional
   :param compute_error: Whether to compute the normalized stress 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 computed stress value, or None if `compute_error` is False.
             * *np.array of shape (n_samples, n_dims) or None* -- The computed gradient of the stress function, or None if `compute_grad` is False.

   :raises ValueError: If an invalid `mds_type` is provided, or if `mds_type` is not recognized.


.. py:function:: _normalized_stress_gradient(positions, distances, disparities)

   Calculate the gradient of the normalized stress function for MDS.

   :param positions: The estimated positions in the low-dimensional space.
   :type positions: np.array of shape (n_samples, n_dims)
   :param distances: The Euclidean distances among the estimated positions.
   :type distances: np.array of shape (n_samples, n_samples)
   :param disparities: The input disparities (or distance) matrix.
   :type disparities: np.array of shape (n_samples, n_samples)

   :returns: The gradient of the stress function with respect to the positions.
   :rtype: np.array of shape (n_samples, n_dims)