sispca.utils
============

.. py:module:: sispca.utils


Classes
-------

.. autoapisummary::

   sispca.utils.Kernel


Functions
---------

.. autoapisummary::

   sispca.utils.normalize_col
   sispca.utils.tr_cov
   sispca.utils.gaussian_kernel
   sispca.utils.delta_kernel
   sispca.utils.hsic_gaussian
   sispca.utils.hsic_linear
   sispca.utils.gram_schmidt
   sispca.utils.slice_sparse_matrix


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

.. py:function:: normalize_col(x, center=True, scale=True)

   Z-score normalization.

   :param x: (n_sample, n_feature).
   :type x: 2D tensor

   :returns: (x - x.mean(dim=0)) / x.std(dim=0)


.. py:function:: tr_cov(x)

   Calculate the trace of the covariance matrix of the hidden representation.

   :param x: (n_sample, n_feature).
   :type x: 2D tensor

   :returns: tr(x @ x.T)


.. py:function:: gaussian_kernel(x, bw=None)

   Calculate the Gaussian kernel matrix.

   :param x: (n_sample, n_feature).
   :type x: 2D tensor
   :param bw: Bendwidth of the Gaussian kernel.
              If None, will set to the median distance.

   Returns
       K (2D tensor): (n_sample, n_sample).


.. py:function:: delta_kernel(x)

   Calculate the delta kernel matrix.

   :param x: Category labels. (n_sample, n_feature).
   :type x: 2D array

   Returns
       K (2D tensor): (n_sample, n_sample).


.. py:function:: hsic_gaussian(x, y, bw=None)

   Calculate the HSIC between two tensors using Gaussian kernel.

   :param x: (n_sample, n_feature_1).
   :type x: 2D tensor
   :param y: (n_sample, n_feature_2).
   :type y: 2D tensor
   :param bw: Bendwidth of the Gaussian kernel.
              If None, will set to the median distance.

   :returns: HSIC between x and y.
   :rtype: HSIC (float)


.. py:function:: hsic_linear(x, y)

   Calculate the HSIC between two tensors using linear kernel.

   :param x: (n_sample, n_feature_1).
   :type x: 2D tensor
   :param y: (n_sample, n_feature_2).
   :type y: 2D tensor

   :returns: HSIC between x and y.
   :rtype: HSIC (float)


.. py:function:: gram_schmidt(x)

   Project the data to an orthogonal space using Gram-Schmidt process.

   :param x:
   :type x: 2D tensor

   :returns: data with orthonormal columns.
   :rtype: x_new (2D tensor)


.. py:class:: Kernel(target_type, Q=None, target_kernel=None)

   Custom data class for more efficient storage of kernels.

   Usage:
       kernel = Kernel('continuous', Q = target_data) # K = Q @ Q.T
       kernel.realization() # return the (n, n) kernel matrix
       kernel.subset(idx) # return the sub-kernel matrix of shape (m, m) where m = len(idx)
       kernel.xtKx(x) # return x.T @ K @ x

   :param target_type: One of ['continuous', 'categorical', 'identity','custom']. The type of the target data.
                       If 'custom', the target_kernel should be provided.
   :type target_type: str
   :param Q: If int, Q is the dimension of the identity matrix.
             If 2D tensor, Q is the decomposed matrix (n_obs, n_var) where K = Q @ Q.T.
   :type Q: int or 2D tensor
   :param target_kernel: The pre-calculated kernel matrix K of shape (n_obs, n_obs).
                         Applied when target_type is 'custom'. Will overwrite Q if provided.
   :type target_kernel: 2D tensor


   .. py:attribute:: target_type


   .. py:attribute:: Q
      :value: None



   .. py:attribute:: target_kernel
      :value: None



   .. py:attribute:: shape


   .. py:attribute:: _rank
      :value: None



   .. py:method:: _sanity_check()


   .. py:method:: _shape()


   .. py:method:: realization()


   .. py:method:: xtKx(x)


   .. py:method:: subset(idx)

      Helper function to extract batched inputs for training. idx (tensor) is the index of the batch.

      :param idx: 1D tensor of m indices to subset the kernel matrix.

      :returns: A new Kernel object with the subsetted kernel matrix of shape (m, m).



   .. py:method:: rank()

      Calculate the rank of the kernel matrix



.. py:function:: slice_sparse_matrix(K: torch.sparse_coo_tensor, index: torch.Tensor)

   Slice a PyTorch sparse matrix `K` by the indices in `index` such that the result is K[index, :][:, index].

   :param K: Input sparse matrix (torch.sparse_coo_tensor).
   :param index: 1D tensor of row/column indices to slice (torch.Tensor).

   :returns: ][:, index].
   :rtype: A new sparse matrix (torch.sparse_coo_tensor) corresponding to K[index,