jpt.base.correlation.xi
=======================

.. py:module:: jpt.base.correlation.xi

.. autoapi-nested-parse::

   Chatterjee's xi correlation coefficient.

   A rank-based measure of functional dependence
   introduced by Chatterjee (JASA, 2021). The
   coefficient equals 0 iff X and Y are independent
   and 1 iff Y is a measurable function of X.



Functions
---------

.. autoapisummary::

   jpt.base.correlation.xi.xi_correlation
   jpt.base.correlation.xi.xi_correlation_matrix


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

.. py:function:: xi_correlation(x: numpy.ndarray, y: numpy.ndarray) -> float

   Compute Chatterjee's xi correlation.

   Measures the degree to which ``y`` is a
   measurable function of ``x``. Requires only
   two sorts and a linear pass, giving
   O(n log n) complexity.

   :param x: feature values, shape (n,)
   :param y: target values, shape (n,)
   :returns: xi coefficient in [-0.5, 1]


.. py:function:: xi_correlation_matrix(data: numpy.ndarray, feature_indices: numpy.ndarray, target_indices: numpy.ndarray, row_indices: numpy.ndarray | None = None) -> numpy.ndarray

   Compute xi for all feature-target pairs.

   Returns a matrix M where
   M[i, j] = xi(data[:, feature_indices[i]],
                 data[:, target_indices[j]]).

   :param data:            array (n x d)
   :param feature_indices: feature column indices
   :param target_indices:  target column indices
   :param row_indices:     optional row subset
   :returns:               xi matrix (nf x nt)