Shortcuts

Theil’s U

Module Interface

class torchmetrics.nominal.TheilsU(num_classes, nan_strategy='replace', nan_replace_value=0.0, **kwargs)[source]

Compute Theil’s U statistic measuring the association between two categorical (nominal) data series.

\[U(X|Y) = \frac{H(X) - H(X|Y)}{H(X)}\]

where \(H(X)\) is entropy of variable \(X\) while \(H(X|Y)\) is the conditional entropy of \(X\) given \(Y\). It is also know as the Uncertainty Coefficient. Theils’s U is an asymmetric coefficient, i.e. \(TheilsU(preds, target) \neq TheilsU(target, preds)\), so the order of the inputs matters. The output values lies in [0, 1], where a 0 means y has no information about x while value 1 means y has complete information about x.

As input to forward and update the metric accepts the following input:

  • preds (Tensor): Either 1D or 2D tensor of categorical (nominal) data from the first data series (called X in the above definition) with shape (batch_size,) or (batch_size, num_classes), respectively.

  • target (Tensor): Either 1D or 2D tensor of categorical (nominal) data from the second data series (called Y in the above definition) with shape (batch_size,) or (batch_size, num_classes), respectively.

As output of forward and compute the metric returns the following output:

  • theils_u (Tensor): Scalar tensor containing the Theil’s U statistic.

Parameters:
  • num_classes (int) – Integer specifing the number of classes

  • nan_strategy (Literal['replace', 'drop']) – Indication of whether to replace or drop NaN values

  • nan_replace_value (Union[int, float, None]) – Value to replace NaN``s when ``nan_strategy = 'replace'

  • kwargs (Any) – Additional keyword arguments, see Advanced metric settings for more info.

Example:

>>> from torchmetrics.nominal import TheilsU
>>> _ = torch.manual_seed(42)
>>> preds = torch.randint(10, (10,))
>>> target = torch.randint(10, (10,))
>>> metric = TheilsU(num_classes=10)
>>> metric(preds, target)
tensor(0.8530)
plot(val=None, ax=None)[source]

Plot a single or multiple values from the metric.

Parameters:
  • val (Union[Tensor, Sequence[Tensor], None]) – Either a single result from calling metric.forward or metric.compute or a list of these results. If no value is provided, will automatically call metric.compute and plot that result.

  • ax (Optional[Axes]) – An matplotlib axis object. If provided will add plot to that axis

Return type:

Tuple[Figure, Union[Axes, ndarray]]

Returns:

Figure and Axes object

Raises:

ModuleNotFoundError – If matplotlib is not installed

>>> # Example plotting a single value
>>> import torch
>>> from torchmetrics.nominal import TheilsU
>>> metric = TheilsU(num_classes=10)
>>> metric.update(torch.randint(10, (10,)), torch.randint(10, (10,)))
>>> fig_, ax_ = metric.plot()
../_images/theils_u-1.png
>>> # Example plotting multiple values
>>> import torch
>>> from torchmetrics.nominal import TheilsU
>>> metric = TheilsU(num_classes=10)
>>> values = [ ]
>>> for _ in range(10):
...     values.append(metric(torch.randint(10, (10,)), torch.randint(10, (10,))))
>>> fig_, ax_ = metric.plot(values)
../_images/theils_u-2.png

Functional Interface

torchmetrics.functional.nominal.theils_u(preds, target, nan_strategy='replace', nan_replace_value=0.0)[source]

Compute Theils Uncertainty coefficient statistic measuring the association between two nominal data series.

\[U(X|Y) = \frac{H(X) - H(X|Y)}{H(X)}\]

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

Theils’s U is an asymmetric coefficient, i.e. \(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.

Parameters:
  • preds (Tensor) – 1D or 2D tensor of categorical (nominal) data - 1D shape: (batch_size,) - 2D shape: (batch_size, num_classes)

  • target (Tensor) – 1D or 2D tensor of categorical (nominal) data - 1D shape: (batch_size,) - 2D shape: (batch_size, num_classes)

  • nan_strategy (Literal['replace', 'drop']) – Indication of whether to replace or drop NaN values

  • nan_replace_value (Union[int, float, None]) – Value to replace NaN``s when ``nan_strategy = 'replace'

Return type:

Tensor

Returns:

Tensor containing Theil’s U statistic

Example

>>> from torchmetrics.functional.nominal import theils_u
>>> _ = torch.manual_seed(42)
>>> preds = torch.randint(10, (10,))
>>> target = torch.randint(10, (10,))
>>> theils_u(preds, target)
tensor(0.8530)

theils_u_matrix

torchmetrics.functional.nominal.theils_u_matrix(matrix, nan_strategy='replace', nan_replace_value=0.0)[source]

Compute Theil’s U statistic between a set of multiple variables.

This can serve as a convenient tool to compute Theil’s U statistic for analyses of correlation between categorical variables in your dataset.

Parameters:
  • matrix (Tensor) – A tensor of categorical (nominal) data, where: - rows represent a number of data points - columns represent a number of categorical (nominal) features

  • nan_strategy (Literal['replace', 'drop']) – Indication of whether to replace or drop NaN values

  • nan_replace_value (Union[int, float, None]) – Value to replace NaN``s when ``nan_strategy = 'replace'

Return type:

Tensor

Returns:

Theil’s U statistic for a dataset of categorical variables

Example

>>> from torchmetrics.functional.nominal import theils_u_matrix
>>> _ = torch.manual_seed(42)
>>> matrix = torch.randint(0, 4, (200, 5))
>>> theils_u_matrix(matrix)
tensor([[1.0000, 0.0202, 0.0142, 0.0196, 0.0353],
        [0.0202, 1.0000, 0.0070, 0.0136, 0.0065],
        [0.0143, 0.0070, 1.0000, 0.0125, 0.0206],
        [0.0198, 0.0137, 0.0125, 1.0000, 0.0312],
        [0.0352, 0.0065, 0.0204, 0.0308, 1.0000]])
Read the Docs v: stable
Versions
latest
stable
v1.1.0
v1.0.3
v1.0.2
v1.0.1
v1.0.0
v0.11.4
v0.11.3
v0.11.2
v0.11.1
v0.11.0
v0.10.3
v0.10.2
v0.10.1
v0.10.0
v0.9.3
v0.9.2
v0.9.1
v0.9.0
v0.8.2
v0.8.1
v0.8.0
v0.7.3
v0.7.2
v0.7.1
v0.7.0
v0.6.2
v0.6.1
v0.6.0
v0.5.1
v0.5.0
v0.4.1
v0.4.0
v0.3.2
v0.3.1
v0.3.0
v0.2.0
v0.1.0
Downloads
pdf
html
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.