Shortcuts

# Theil’s U¶

## Module Interface¶

class torchmetrics.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. where is entropy of variable while is the conditional entropy of given . It is also know as the Uncertainty Coefficient.

Theils’s U is an asymmetric coefficient, i.e. .

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
Returns

Tensor

Return type

Theil’s U Statistic

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)


Initializes internal Module state, shared by both nn.Module and ScriptModule.

plot(val=None, ax=None)[source]

Plot a single or multiple values from the metric.

Parameters
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()

>>> # 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)


## Functional Interface¶

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

Compute Theil’s U statistic (Uncertainty Coef.) measuring the association between two nominal data series. where is entropy of variable while is the conditional entropy of given .

Theils’s U is an asymmetric coefficient, i.e. .

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
Returns

Tensor

Return type

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
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]])


© Copyright Copyright (c) 2020-2023, Lightning-AI et al... Revision 1edf6a11.

Built with Sphinx using a theme provided by Read the Docs.
Versions
latest
stable
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