Matthews Correlation Coefficient¶
Module Interface¶
- class torchmetrics.MatthewsCorrCoef(**kwargs)[source]¶
Calculate Matthews correlation coefficient .
This metric measures the general correlation or quality of a classification.
This function is a simple wrapper to get the task specific versions of this metric, which is done by setting the
task
argument to either'binary'
,'multiclass'
ormultilabel
. See the documentation ofBinaryMatthewsCorrCoef
,MulticlassMatthewsCorrCoef
andMultilabelMatthewsCorrCoef
for the specific details of each argument influence and examples.- Legacy Example:
>>> from torch import tensor >>> target = tensor([1, 1, 0, 0]) >>> preds = tensor([0, 1, 0, 0]) >>> matthews_corrcoef = MatthewsCorrCoef(task='binary') >>> matthews_corrcoef(preds, target) tensor(0.5774)
BinaryMatthewsCorrCoef¶
- class torchmetrics.classification.BinaryMatthewsCorrCoef(threshold=0.5, ignore_index=None, validate_args=True, **kwargs)[source]¶
Calculate Matthews correlation coefficient for binary tasks.
This metric measures the general correlation or quality of a classification.
As input to
forward
andupdate
the metric accepts the following input:preds
(Tensor
): A int tensor or float tensor of shape(N, ...)
. If preds is a floating point tensor with values outside [0,1] range we consider the input to be logits and will auto apply sigmoid per element. Additionally, we convert to int tensor with thresholding using the value inthreshold
.target
(Tensor
): An int tensor of shape(N, ...)
Note
Additional dimension
...
will be flattened into the batch dimension.As output to
forward
andcompute
the metric returns the following output:bmcc
(Tensor
): A tensor containing the Binary Matthews Correlation Coefficient.
- Parameters:
threshold¶ (
float
) – Threshold for transforming probability to binary (0,1) predictionsignore_index¶ (
Optional
[int
]) – Specifies a target value that is ignored and does not contribute to the metric calculationvalidate_args¶ (
bool
) – bool indicating if input arguments and tensors should be validated for correctness. Set toFalse
for faster computations.kwargs¶ (
Any
) – Additional keyword arguments, see Advanced metric settings for more info.
- Example (preds is int tensor):
>>> from torch import tensor >>> from torchmetrics.classification import BinaryMatthewsCorrCoef >>> target = tensor([1, 1, 0, 0]) >>> preds = tensor([0, 1, 0, 0]) >>> metric = BinaryMatthewsCorrCoef() >>> metric(preds, target) tensor(0.5774)
- Example (preds is float tensor):
>>> from torchmetrics.classification import BinaryMatthewsCorrCoef >>> target = tensor([1, 1, 0, 0]) >>> preds = tensor([0.35, 0.85, 0.48, 0.01]) >>> metric = BinaryMatthewsCorrCoef() >>> metric(preds, target) tensor(0.5774)
- 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:
- Returns:
Figure object and Axes object
- Raises:
ModuleNotFoundError – If matplotlib is not installed
>>> from torch import rand, randint >>> # Example plotting a single value >>> from torchmetrics.classification import BinaryMatthewsCorrCoef >>> metric = BinaryMatthewsCorrCoef() >>> metric.update(rand(10), randint(2,(10,))) >>> fig_, ax_ = metric.plot()
>>> from torch import rand, randint >>> # Example plotting multiple values >>> from torchmetrics.classification import BinaryMatthewsCorrCoef >>> metric = BinaryMatthewsCorrCoef() >>> values = [ ] >>> for _ in range(10): ... values.append(metric(rand(10), randint(2,(10,)))) >>> fig_, ax_ = metric.plot(values)
MulticlassMatthewsCorrCoef¶
- class torchmetrics.classification.MulticlassMatthewsCorrCoef(num_classes, ignore_index=None, validate_args=True, **kwargs)[source]¶
Calculate Matthews correlation coefficient for multiclass tasks.
This metric measures the general correlation or quality of a classification.
As input to
forward
andupdate
the metric accepts the following input:preds
(Tensor
): A int tensor of shape(N, ...)
or float tensor of shape(N, C, ..)
. If preds is a floating point we applytorch.argmax
along theC
dimension to automatically convert probabilities/logits into an int tensor.target
(Tensor
): An int tensor of shape(N, ...)
Note
Additional dimension
...
will be flattened into the batch dimension.As output to
forward
andcompute
the metric returns the following output:mcmcc
(Tensor
): A tensor containing the Multi-class Matthews Correlation Coefficient.
- Parameters:
num_classes¶ (
int
) – Integer specifying the number of classesignore_index¶ (
Optional
[int
]) – Specifies a target value that is ignored and does not contribute to the metric calculationvalidate_args¶ (
bool
) – bool indicating if input arguments and tensors should be validated for correctness. Set toFalse
for faster computations.kwargs¶ (
Any
) – Additional keyword arguments, see Advanced metric settings for more info.
- Example (pred is integer tensor):
>>> from torch import tensor >>> from torchmetrics.classification import MulticlassMatthewsCorrCoef >>> target = tensor([2, 1, 0, 0]) >>> preds = tensor([2, 1, 0, 1]) >>> metric = MulticlassMatthewsCorrCoef(num_classes=3) >>> metric(preds, target) tensor(0.7000)
- Example (pred is float tensor):
>>> from torchmetrics.classification import MulticlassMatthewsCorrCoef >>> target = tensor([2, 1, 0, 0]) >>> preds = tensor([[0.16, 0.26, 0.58], ... [0.22, 0.61, 0.17], ... [0.71, 0.09, 0.20], ... [0.05, 0.82, 0.13]]) >>> metric = MulticlassMatthewsCorrCoef(num_classes=3) >>> metric(preds, target) tensor(0.7000)
- 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:
- Returns:
Figure object and Axes object
- Raises:
ModuleNotFoundError – If matplotlib is not installed
>>> from torch import randint >>> # Example plotting a single value per class >>> from torchmetrics.classification import MulticlassMatthewsCorrCoef >>> metric = MulticlassMatthewsCorrCoef(num_classes=3) >>> metric.update(randint(3, (20,)), randint(3, (20,))) >>> fig_, ax_ = metric.plot()
>>> from torch import randint >>> # Example plotting a multiple values per class >>> from torchmetrics.classification import MulticlassMatthewsCorrCoef >>> metric = MulticlassMatthewsCorrCoef(num_classes=3) >>> values = [] >>> for _ in range(20): ... values.append(metric(randint(3, (20,)), randint(3, (20,)))) >>> fig_, ax_ = metric.plot(values)
MultilabelMatthewsCorrCoef¶
- class torchmetrics.classification.MultilabelMatthewsCorrCoef(num_labels, threshold=0.5, ignore_index=None, validate_args=True, **kwargs)[source]¶
Calculate Matthews correlation coefficient for multilabel tasks.
This metric measures the general correlation or quality of a classification.
As input to
forward
andupdate
the metric accepts the following input:preds
(Tensor
): An int or float tensor of shape(N, C, ...)
. If preds is a floating point tensor with values outside [0,1] range we consider the input to be logits and will auto apply sigmoid per element. Additionally, we convert to int tensor with thresholding using the value inthreshold
.target
(Tensor
): An int tensor of shape(N, C, ...)
Note
Additional dimension
...
will be flattened into the batch dimension.As output to
forward
andcompute
the metric returns the following output:mlmcc
(Tensor
): A tensor containing the Multi-label Matthews Correlation Coefficient.
- Parameters:
threshold¶ (
float
) – Threshold for transforming probability to binary (0,1) predictionsignore_index¶ (
Optional
[int
]) – Specifies a target value that is ignored and does not contribute to the metric calculationvalidate_args¶ (
bool
) – bool indicating if input arguments and tensors should be validated for correctness. Set toFalse
for faster computations.kwargs¶ (
Any
) – Additional keyword arguments, see Advanced metric settings for more info.
- Example (preds is int tensor):
>>> from torch import tensor >>> from torchmetrics.classification import MultilabelMatthewsCorrCoef >>> target = tensor([[0, 1, 0], [1, 0, 1]]) >>> preds = tensor([[0, 0, 1], [1, 0, 1]]) >>> metric = MultilabelMatthewsCorrCoef(num_labels=3) >>> metric(preds, target) tensor(0.3333)
- Example (preds is float tensor):
>>> from torchmetrics.classification import MultilabelMatthewsCorrCoef >>> target = tensor([[0, 1, 0], [1, 0, 1]]) >>> preds = tensor([[0.11, 0.22, 0.84], [0.73, 0.33, 0.92]]) >>> metric = MultilabelMatthewsCorrCoef(num_labels=3) >>> metric(preds, target) tensor(0.3333)
- 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:
- Returns:
Figure object and Axes object
- Raises:
ModuleNotFoundError – If matplotlib is not installed
>>> from torch import rand, randint >>> # Example plotting a single value >>> from torchmetrics.classification import MultilabelMatthewsCorrCoef >>> metric = MultilabelMatthewsCorrCoef(num_labels=3) >>> metric.update(randint(2, (20, 3)), randint(2, (20, 3))) >>> fig_, ax_ = metric.plot()
>>> from torch import rand, randint >>> # Example plotting multiple values >>> from torchmetrics.classification import MultilabelMatthewsCorrCoef >>> metric = MultilabelMatthewsCorrCoef(num_labels=3) >>> values = [ ] >>> for _ in range(10): ... values.append(metric(randint(2, (20, 3)), randint(2, (20, 3)))) >>> fig_, ax_ = metric.plot(values)
Functional Interface¶
matthews_corrcoef¶
- torchmetrics.functional.matthews_corrcoef(preds, target, task, threshold=0.5, num_classes=None, num_labels=None, ignore_index=None, validate_args=True)[source]¶
Calculate Matthews correlation coefficient .
This metric measures the general correlation or quality of a classification.
This function is a simple wrapper to get the task specific versions of this metric, which is done by setting the
task
argument to either'binary'
,'multiclass'
ormultilabel
. See the documentation ofbinary_matthews_corrcoef()
,multiclass_matthews_corrcoef()
andmultilabel_matthews_corrcoef()
for the specific details of each argument influence and examples.- Return type:
- Legacy Example:
>>> from torch import tensor >>> target = tensor([1, 1, 0, 0]) >>> preds = tensor([0, 1, 0, 0]) >>> matthews_corrcoef(preds, target, task="multiclass", num_classes=2) tensor(0.5774)
binary_matthews_corrcoef¶
- torchmetrics.functional.classification.binary_matthews_corrcoef(preds, target, threshold=0.5, ignore_index=None, validate_args=True)[source]¶
Calculate Matthews correlation coefficient for binary tasks.
This metric measures the general correlation or quality of a classification.
Accepts the following input tensors:
preds
(int or float tensor):(N, ...)
. If preds is a floating point tensor with values outside [0,1] range we consider the input to be logits and will auto apply sigmoid per element. Additionally, we convert to int tensor with thresholding using the value inthreshold
.target
(int tensor):(N, ...)
Additional dimension
...
will be flattened into the batch dimension.- Parameters:
threshold¶ (
float
) – Threshold for transforming probability to binary (0,1) predictionsignore_index¶ (
Optional
[int
]) – Specifies a target value that is ignored and does not contribute to the metric calculationvalidate_args¶ (
bool
) – bool indicating if input arguments and tensors should be validated for correctness. Set toFalse
for faster computations.kwargs¶ – Additional keyword arguments, see Advanced metric settings for more info.
- Return type:
- Example (preds is int tensor):
>>> from torch import tensor >>> from torchmetrics.functional.classification import binary_matthews_corrcoef >>> target = tensor([1, 1, 0, 0]) >>> preds = tensor([0, 1, 0, 0]) >>> binary_matthews_corrcoef(preds, target) tensor(0.5774)
- Example (preds is float tensor):
>>> from torchmetrics.functional.classification import binary_matthews_corrcoef >>> target = tensor([1, 1, 0, 0]) >>> preds = tensor([0.35, 0.85, 0.48, 0.01]) >>> binary_matthews_corrcoef(preds, target) tensor(0.5774)
multiclass_matthews_corrcoef¶
- torchmetrics.functional.classification.multiclass_matthews_corrcoef(preds, target, num_classes, ignore_index=None, validate_args=True)[source]¶
Calculate Matthews correlation coefficient for multiclass tasks.
This metric measures the general correlation or quality of a classification.
Accepts the following input tensors:
preds
:(N, ...)
(int tensor) or(N, C, ..)
(float tensor). If preds is a floating point we applytorch.argmax
along theC
dimension to automatically convert probabilities/logits into an int tensor.target
(int tensor):(N, ...)
Additional dimension
...
will be flattened into the batch dimension.- Parameters:
num_classes¶ (
int
) – Integer specifying the number of classesignore_index¶ (
Optional
[int
]) – Specifies a target value that is ignored and does not contribute to the metric calculationvalidate_args¶ (
bool
) – bool indicating if input arguments and tensors should be validated for correctness. Set toFalse
for faster computations.kwargs¶ – Additional keyword arguments, see Advanced metric settings for more info.
- Return type:
- Example (pred is integer tensor):
>>> from torch import tensor >>> from torchmetrics.functional.classification import multiclass_matthews_corrcoef >>> target = tensor([2, 1, 0, 0]) >>> preds = tensor([2, 1, 0, 1]) >>> multiclass_matthews_corrcoef(preds, target, num_classes=3) tensor(0.7000)
- Example (pred is float tensor):
>>> from torchmetrics.functional.classification import multiclass_matthews_corrcoef >>> target = tensor([2, 1, 0, 0]) >>> preds = tensor([[0.16, 0.26, 0.58], ... [0.22, 0.61, 0.17], ... [0.71, 0.09, 0.20], ... [0.05, 0.82, 0.13]]) >>> multiclass_matthews_corrcoef(preds, target, num_classes=3) tensor(0.7000)
multilabel_matthews_corrcoef¶
- torchmetrics.functional.classification.multilabel_matthews_corrcoef(preds, target, num_labels, threshold=0.5, ignore_index=None, validate_args=True)[source]¶
Calculate Matthews correlation coefficient for multilabel tasks.
This metric measures the general correlation or quality of a classification.
Accepts the following input tensors:
preds
(int or float tensor):(N, C, ...)
. If preds is a floating point tensor with values outside [0,1] range we consider the input to be logits and will auto apply sigmoid per element. Additionally, we convert to int tensor with thresholding using the value inthreshold
.target
(int tensor):(N, C, ...)
Additional dimension
...
will be flattened into the batch dimension.- Parameters:
threshold¶ (
float
) – Threshold for transforming probability to binary (0,1) predictionsignore_index¶ (
Optional
[int
]) – Specifies a target value that is ignored and does not contribute to the metric calculationvalidate_args¶ (
bool
) – bool indicating if input arguments and tensors should be validated for correctness. Set toFalse
for faster computations.
- Return type:
- Example (preds is int tensor):
>>> from torch import tensor >>> from torchmetrics.functional.classification import multilabel_matthews_corrcoef >>> target = tensor([[0, 1, 0], [1, 0, 1]]) >>> preds = tensor([[0, 0, 1], [1, 0, 1]]) >>> multilabel_matthews_corrcoef(preds, target, num_labels=3) tensor(0.3333)
- Example (preds is float tensor):
>>> from torchmetrics.functional.classification import multilabel_matthews_corrcoef >>> target = tensor([[0, 1, 0], [1, 0, 1]]) >>> preds = tensor([[0.11, 0.22, 0.84], [0.73, 0.33, 0.92]]) >>> multilabel_matthews_corrcoef(preds, target, num_labels=3) tensor(0.3333)