o
    yi                     @   sp   d dl mZmZmZ d dlZd dlmZ d dlmZ d dlm	Z	m
Z
 d dlmZ d dlmZ G dd	 d	eZdS )
    )AnyOptionalUnionN)Tensor)Literal)_theils_u_compute_theils_u_update)_nominal_input_validation)Metricc                
       s   e Zd ZU dZdZeed< dZeed< dZeed< e	ed< 			dd
e
ded deee
ef  def fddZde	de	ddfddZde	fddZ  ZS )TheilsUa  Compute `Theil's U`_ statistic (Uncertainty Coefficient) measuring the association between two categorical
    (nominal) data series.

    .. math::
        U(X|Y) = \frac{H(X) - H(X|Y)}{H(X)}

    where :math:`H(X)` is entropy of variable :math:`X` while :math:`H(X|Y)` is the conditional entropy of :math:`X`
    given :math:`Y`.

    Theils's U is an asymmetric coefficient, i.e. :math:`TheilsU(preds, target) \neq TheilsU(target, preds)`.

    The output values lies in [0, 1]. 0 means y has no information about x while value 1 means y has complete
    information about x.

    Args:
        num_classes: Integer specifing the number of classes
        nan_strategy: Indication of whether to replace or drop ``NaN`` values
        nan_replace_value: Value to replace ``NaN``s when ``nan_strategy = 'replace'``
        kwargs: Additional keyword arguments, see :ref:`Metric kwargs` for more info.

    Returns:
        Theil's U Statistic: Tensor

    Example:
        >>> from torchmetrics import TheilsU
        >>> _ = torch.manual_seed(42)
        >>> preds = torch.randint(10, (10,))
        >>> target = torch.randint(10, (10,))
        >>> TheilsU(num_classes=10)(preds, target)
        tensor(0.8530)
    Ffull_state_updateis_differentiableThigher_is_betterconfmatreplace        num_classesnan_strategy)r   dropnan_replace_valuekwargsc                    sJ   t  jdi | || _t|| || _|| _| jdt||dd d S )Nr   sum)dist_reduce_fx )	super__init__r   r	   r   r   	add_statetorchzeros)selfr   r   r   r   	__class__r   Q/home/ubuntu/.local/lib/python3.10/site-packages/torchmetrics/nominal/theils_u.pyr   ?   s   
zTheilsU.__init__predstargetreturnNc                 C   s(   t ||| j| j| j}|  j|7  _dS )aq  Update state with predictions and targets.

        Args:
            preds: 1D or 2D tensor of categorical (nominal) data
            - 1D shape: (batch_size,)
            - 2D shape: (batch_size, num_classes)
        target: 1D or 2D tensor of categorical (nominal) data
            - 1D shape: (batch_size,)
            - 2D shape: (batch_size, num_classes)
        N)r   r   r   r   r   )r   r#   r$   r   r   r   r"   updateO   s   zTheilsU.updatec                 C   s
   t | jS )zComputer Theil's U statistic.)r   r   )r   r   r   r"   compute]   s   
zTheilsU.compute)r   r   )__name__
__module____qualname____doc__r   bool__annotations__r   r   r   intr   r   r   floatr   r   r&   r'   __classcell__r   r   r    r"   r      s&   
  r   )typingr   r   r   r   r   typing_extensionsr   (torchmetrics.functional.nominal.theils_ur   r   %torchmetrics.functional.nominal.utilsr	   torchmetrics.metricr
   r   r   r   r   r"   <module>   s   