Kendall Rank Corr. Coef.

Module Interface

class torchmetrics.KendallRankCorrCoef(variant='b', t_test=False, alternative='two-sided', num_outputs=1, **kwargs)

Compute Kendall Rank Correlation Coefficient.

\[tau_a = \frac{C - D}{C + D}\]

where \(C\) represents concordant pairs, \(D\) stands for discordant pairs.

\[tau_b = \frac{C - D}{\sqrt{(C + D + T_{preds}) * (C + D + T_{target})}}\]

where \(C\) represents concordant pairs, \(D\) stands for discordant pairs and \(T\) represents a total number of ties.

\[tau_c = 2 * \frac{C - D}{n^2 * \frac{m - 1}{m}}\]

where \(C\) represents concordant pairs, \(D\) stands for discordant pairs, \(n\) is a total number of observations and \(m\) is a min of unique values in preds and target sequence.

Definitions according to Definition according to The Treatment of Ties in Ranking Problems.

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

• preds (Tensor): Sequence of data in float tensor of either shape (N,) or (N,d)

• target (Tensor): Sequence of data in float tensor of either shape (N,) or (N,d)

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

• kendall (Tensor): A tensor with the correlation tau statistic, and if it is not None, the p-value of corresponding statistical test.

Parameters:

• variant (Literal['a', 'b', 'c']) – Indication of which variant of Kendall’s tau to be used

• t_test (bool) – Indication whether to run t-test

• alternative (Optional[Literal['two-sided', 'less', 'greater']]) – Alternative hypothesis for t-test. Possible values: - ‘two-sided’: the rank correlation is nonzero - ‘less’: the rank correlation is negative (less than zero) - ‘greater’: the rank correlation is positive (greater than zero)

• num_outputs (int) – Number of outputs in multioutput setting

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

Raises:

• ValueError – If t_test is not of a type bool

• ValueError – If t_test=True and alternative=None

Example (single output regression):

>>> from torch import tensor
>>> from torchmetrics.regression import KendallRankCorrCoef
>>> preds = tensor([2.5, 0.0, 2, 8])
>>> target = tensor([3, -0.5, 2, 1])
>>> kendall = KendallRankCorrCoef()
>>> kendall(preds, target)
tensor(0.3333)

Example (multi output regression):

>>> from torchmetrics.regression import KendallRankCorrCoef
>>> preds = tensor([[2.5, 0.0], [2, 8]])
>>> target = tensor([[3, -0.5], [2, 1]])
>>> kendall = KendallRankCorrCoef(num_outputs=2)
>>> kendall(preds, target)
tensor([1., 1.])

Example (single output regression with t-test):

>>> from torchmetrics.regression import KendallRankCorrCoef
>>> preds = tensor([2.5, 0.0, 2, 8])
>>> target = tensor([3, -0.5, 2, 1])
>>> kendall = KendallRankCorrCoef(t_test=True, alternative='two-sided')
>>> kendall(preds, target)
(tensor(0.3333), tensor(0.4969))

Example (multi output regression with t-test):

>>> from torchmetrics.regression import KendallRankCorrCoef
>>> preds = tensor([[2.5, 0.0], [2, 8]])
>>> target = tensor([[3, -0.5], [2, 1]])
>>> kendall = KendallRankCorrCoef(t_test=True, alternative='two-sided', num_outputs=2)
>>> kendall(preds, target)
(tensor([1., 1.]), tensor([nan, nan]))

plot(val=None, ax=None)

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

>>> from torch import randn
>>> # Example plotting a single value
>>> from torchmetrics.regression import KendallRankCorrCoef
>>> metric = KendallRankCorrCoef()
>>> metric.update(randn(10,), randn(10,))
>>> fig_, ax_ = metric.plot()

>>> from torch import randn
>>> # Example plotting multiple values
>>> from torchmetrics.regression import KendallRankCorrCoef
>>> metric = KendallRankCorrCoef()
>>> values = []
>>> for _ in range(10):
...     values.append(metric(randn(10,), randn(10,)))
>>> fig, ax = metric.plot(values)

Functional Interface

torchmetrics.functional.kendall_rank_corrcoef(preds, target, variant='b', t_test=False, alternative='two-sided')

Compute Kendall Rank Correlation Coefficient.

\[tau_a = \frac{C - D}{C + D}\]

where \(C\) represents concordant pairs, \(D\) stands for discordant pairs.

\[tau_b = \frac{C - D}{\sqrt{(C + D + T_{preds}) * (C + D + T_{target})}}\]

where \(C\) represents concordant pairs, \(D\) stands for discordant pairs and \(T\) represents a total number of ties.

\[tau_c = 2 * \frac{C - D}{n^2 * \frac{m - 1}{m}}\]

where \(C\) represents concordant pairs, \(D\) stands for discordant pairs, \(n\) is a total number of observations and \(m\) is a min of unique values in preds and target sequence.

Definitions according to Definition according to The Treatment of Ties in Ranking Problems.

Parameters:

• preds (Tensor) – Sequence of data of either shape (N,) or (N,d)

• target (Tensor) – Sequence of data of either shape (N,) or (N,d)

• variant (Literal['a', 'b', 'c']) – Indication of which variant of Kendall’s tau to be used

• t_test (bool) – Indication whether to run t-test

• alternative (Optional[Literal['two-sided', 'less', 'greater']]) – Alternative hypothesis for t-test. Possible values: - ‘two-sided’: the rank correlation is nonzero - ‘less’: the rank correlation is negative (less than zero) - ‘greater’: the rank correlation is positive (greater than zero)

Return type:

Union[Tensor, Tuple[Tensor, Tensor]]

Returns:

Correlation tau statistic (Optional) p-value of corresponding statistical test (asymptotic)

Raises:

• ValueError – If t_test is not of a type bool

• ValueError – If t_test=True and alternative=None

Example (single output regression):

>>> from torchmetrics.functional.regression import kendall_rank_corrcoef
>>> preds = torch.tensor([2.5, 0.0, 2, 8])
>>> target = torch.tensor([3, -0.5, 2, 1])
>>> kendall_rank_corrcoef(preds, target)
tensor(0.3333)

Example (multi output regression):

>>> from torchmetrics.functional.regression import kendall_rank_corrcoef
>>> preds = torch.tensor([[2.5, 0.0], [2, 8]])
>>> target = torch.tensor([[3, -0.5], [2, 1]])
>>> kendall_rank_corrcoef(preds, target)
tensor([1., 1.])

Example (single output regression with t-test)

>>> from torchmetrics.functional.regression import kendall_rank_corrcoef
>>> preds = torch.tensor([2.5, 0.0, 2, 8])
>>> target = torch.tensor([3, -0.5, 2, 1])
>>> kendall_rank_corrcoef(preds, target, t_test=True, alternative='two-sided')
(tensor(0.3333), tensor(0.4969))

Example (multi output regression with t-test):

>>> from torchmetrics.functional.regression import kendall_rank_corrcoef
>>> preds = torch.tensor([[2.5, 0.0], [2, 8]])
>>> target = torch.tensor([[3, -0.5], [2, 1]])
>>> kendall_rank_corrcoef(preds, target, t_test=True, alternative='two-sided')
    (tensor([1., 1.]), tensor([nan, nan]))