Shortcuts

Cramer’s V

Module Interface

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

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

\[V = \sqrt{\frac{\chi^2 / n}{\min(r - 1, k - 1)}}\]

where

\[\chi^2 = \sum_{i,j} \ frac{\left(n_{ij} - \frac{n_{i.} n_{.j}}{n}\right)^2}{\frac{n_{i.} n_{.j}}{n}}\]

where \(n_{ij}\) denotes the number of times the values \((A_i, B_j)\) are observed with \(A_i, B_j\) represent frequencies of values in preds and target, respectively. Cramer’s V is a symmetric coefficient, i.e. \(V(preds, target) = V(target, preds)\), so order of input arguments does not matter. The output values lies in [0, 1] with 1 meaning the perfect association.

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 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 with shape (batch_size,) or (batch_size, num_classes), respectively.

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

  • cramers_v (Tensor): Scalar tensor containing the Cramer’s V statistic.

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

  • bias_correction (bool) – Indication of whether to use bias correction.

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

Raises:
  • ValueError – If nan_strategy is not one of ‘replace’ and ‘drop’

  • ValueError – If nan_strategy is equal to ‘replace’ and nan_replace_value is not an int or float

Example:

>>> from torchmetrics.nominal import CramersV
>>> _ = torch.manual_seed(42)
>>> preds = torch.randint(0, 4, (100,))
>>> target = torch.round(preds + torch.randn(100)).clamp(0, 4)
>>> cramers_v = CramersV(num_classes=5)
>>> cramers_v(preds, target)
tensor(0.5284)
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 CramersV
>>> metric = CramersV(num_classes=5)
>>> metric.update(torch.randint(0, 4, (100,)), torch.randint(0, 4, (100,)))
>>> fig_, ax_ = metric.plot()
../_images/cramers_v-1.png
>>> # Example plotting multiple values
>>> import torch
>>> from torchmetrics.nominal import CramersV
>>> metric = CramersV(num_classes=5)
>>> values = [ ]
>>> for _ in range(10):
...     values.append(metric(torch.randint(0, 4, (100,)), torch.randint(0, 4, (100,))))
>>> fig_, ax_ = metric.plot(values)
../_images/cramers_v-2.png

Functional Interface

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

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

\[V = \sqrt{\frac{\chi^2 / n}{\min(r - 1, k - 1)}}\]

where

\[\chi^2 = \sum_{i,j} \ frac{\left(n_{ij} - \frac{n_{i.} n_{.j}}{n}\right)^2}{\frac{n_{i.} n_{.j}}{n}}\]

where \(n_{ij}\) denotes the number of times the values \((A_i, B_j)\) are observed with \(A_i, B_j\) represent frequencies of values in preds and target, respectively.

Cramer’s V is a symmetric coefficient, i.e. \(V(preds, target) = V(target, preds)\).

The output values lies in [0, 1] with 1 meaning the perfect association.

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)

  • bias_correction (bool) – Indication of whether to use bias correction.

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

Cramer’s V statistic

Example

>>> from torchmetrics.functional.nominal import cramers_v
>>> _ = torch.manual_seed(42)
>>> preds = torch.randint(0, 4, (100,))
>>> target = torch.round(preds + torch.randn(100)).clamp(0, 4)
>>> cramers_v(preds, target)
tensor(0.5284)

cramers_v_matrix

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

Compute Cramer’s V statistic between a set of multiple variables.

This can serve as a convenient tool to compute Cramer’s V 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

  • bias_correction (bool) – Indication of whether to use bias correction.

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

Cramer’s V statistic for a dataset of categorical variables

Example

>>> from torchmetrics.functional.nominal import cramers_v_matrix
>>> _ = torch.manual_seed(42)
>>> matrix = torch.randint(0, 4, (200, 5))
>>> cramers_v_matrix(matrix)
tensor([[1.0000, 0.0637, 0.0000, 0.0542, 0.1337],
        [0.0637, 1.0000, 0.0000, 0.0000, 0.0000],
        [0.0000, 0.0000, 1.0000, 0.0000, 0.0649],
        [0.0542, 0.0000, 0.0000, 1.0000, 0.1100],
        [0.1337, 0.0000, 0.0649, 0.1100, 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.