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 (Uncertainty Coefficient) 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.

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
  • 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.

Returns

Tensor

Return type

Theil’s U Statistic

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)

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

compute()[source]

Computer Theil’s U statistic.

Return type

Tensor

update(preds, target)[source]

Update state with predictions and targets.

Parameters
  • preds (Tensor) – 1D or 2D tensor of categorical (nominal) data

  • shape (- _sphinx_paramlinks_torchmetrics.TheilsU.update.2D) – (batch_size,)

  • shape – (batch_size, num_classes)

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

  • 2D shape: (batch_size, num_classes)

Return type

None

Functional Interface

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

Compute Theil’s U statistic (Uncertainty Coefficient) 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.

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'

Returns

Tensor

Return type

Theil’s U Statistic

Example

>>> from torchmetrics.functional 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: latest
Versions
latest
stable
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.