ROC¶
Module Interface¶
- class torchmetrics.ROC(num_classes=None, pos_label=None, **kwargs)[source]
Note
From v0.10 an ‘binary_*’, ‘multiclass_*’, `’multilabel_*’ version now exist of each classification metric. Moving forward we recommend using these versions. This base metric will still work as it did prior to v0.10 until v0.11. From v0.11 the task argument introduced in this metric will be required and the general order of arguments may change, such that this metric will just function as an single entrypoint to calling the three specialized versions.
Computes the Receiver Operating Characteristic (ROC). Works for both binary, multiclass and multilabel problems. In the case of multiclass, the values will be calculated based on a one-vs-the-rest approach.
Forward accepts
preds
(float tensor):(N, ...)
(binary) or(N, C, ...)
(multiclass/multilabel) tensor with probabilities, where C is the number of classes/labels.target
(long tensor):(N, ...)
or(N, C, ...)
with integer labels
Note
If either the positive class or negative class is completly missing in the target tensor, the roc values are not well-defined in this case and a tensor of zeros will be returned (either fpr or tpr depending on what class is missing) together with a warning.
- Parameters
num_classes¶ (
Optional
[int
]) – integer with number of classes for multi-label and multiclass problems. Should be set toNone
for binary problemspos_label¶ (
Optional
[int
]) – integer determining the positive class. Default isNone
which for binary problem is translated to 1. For multiclass problems this argument should not be set as we iteratively change it in the range[0,num_classes-1]
kwargs¶ (
Any
) – Additional keyword arguments, see Advanced metric settings for more info.
- Example (binary case):
>>> from torchmetrics import ROC >>> pred = torch.tensor([0, 1, 2, 3]) >>> target = torch.tensor([0, 1, 1, 1]) >>> roc = ROC(pos_label=1) >>> fpr, tpr, thresholds = roc(pred, target) >>> fpr tensor([0., 0., 0., 0., 1.]) >>> tpr tensor([0.0000, 0.3333, 0.6667, 1.0000, 1.0000]) >>> thresholds tensor([4, 3, 2, 1, 0])
- Example (multiclass case):
>>> pred = torch.tensor([[0.75, 0.05, 0.05, 0.05], ... [0.05, 0.75, 0.05, 0.05], ... [0.05, 0.05, 0.75, 0.05], ... [0.05, 0.05, 0.05, 0.75]]) >>> target = torch.tensor([0, 1, 3, 2]) >>> roc = ROC(num_classes=4) >>> fpr, tpr, thresholds = roc(pred, target) >>> fpr [tensor([0., 0., 1.]), tensor([0., 0., 1.]), tensor([0.0000, 0.3333, 1.0000]), tensor([0.0000, 0.3333, 1.0000])] >>> tpr [tensor([0., 1., 1.]), tensor([0., 1., 1.]), tensor([0., 0., 1.]), tensor([0., 0., 1.])] >>> thresholds [tensor([1.7500, 0.7500, 0.0500]), tensor([1.7500, 0.7500, 0.0500]), tensor([1.7500, 0.7500, 0.0500]), tensor([1.7500, 0.7500, 0.0500])]
- Example (multilabel case):
>>> pred = torch.tensor([[0.8191, 0.3680, 0.1138], ... [0.3584, 0.7576, 0.1183], ... [0.2286, 0.3468, 0.1338], ... [0.8603, 0.0745, 0.1837]]) >>> target = torch.tensor([[1, 1, 0], [0, 1, 0], [0, 0, 0], [0, 1, 1]]) >>> roc = ROC(num_classes=3, pos_label=1) >>> fpr, tpr, thresholds = roc(pred, target) >>> fpr [tensor([0.0000, 0.3333, 0.3333, 0.6667, 1.0000]), tensor([0., 0., 0., 1., 1.]), tensor([0.0000, 0.0000, 0.3333, 0.6667, 1.0000])] >>> tpr [tensor([0., 0., 1., 1., 1.]), tensor([0.0000, 0.3333, 0.6667, 0.6667, 1.0000]), tensor([0., 1., 1., 1., 1.])] >>> thresholds [tensor([1.8603, 0.8603, 0.8191, 0.3584, 0.2286]), tensor([1.7576, 0.7576, 0.3680, 0.3468, 0.0745]), tensor([1.1837, 0.1837, 0.1338, 0.1183, 0.1138])]
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- compute()[source]
Compute the receiver operating characteristic.
- Return type
Union
[Tuple
[Tensor
,Tensor
,Tensor
],Tuple
[List
[Tensor
],List
[Tensor
],List
[Tensor
]]]- Returns
3-element tuple containing
- fpr: tensor with false positive rates.
If multiclass, this is a list of such tensors, one for each class.
- tpr: tensor with true positive rates.
If multiclass, this is a list of such tensors, one for each class.
- thresholds:
thresholds used for computing false- and true-positive rates
BinaryROC¶
- class torchmetrics.classification.BinaryROC(thresholds=None, ignore_index=None, validate_args=True, **kwargs)[source]
Computes the Receiver Operating Characteristic (ROC) for binary tasks. The curve consist of multiple pairs of true positive rate (TPR) and false positive rate (FPR) values evaluated at different thresholds, such that the tradeoff between the two values can be seen.
Accepts the following input tensors:
preds
(float tensor):(N, ...)
. Preds should be a tensor containing probabilities or logits for each observation. If preds has values outside [0,1] range we consider the input to be logits and will auto apply sigmoid per element.target
(int tensor):(N, ...)
. Target should be a tensor containing ground truth labels, and therefore only contain {0,1} values (except if ignore_index is specified).
Additional dimension
...
will be flattened into the batch dimension.The implementation both supports calculating the metric in a non-binned but accurate version and a binned version that is less accurate but more memory efficient. Setting the thresholds argument to None will activate the non-binned version that uses memory of size whereas setting the thresholds argument to either an integer, list or a 1d tensor will use a binned version that uses memory of size (constant memory).
Note that outputted thresholds will be in reversed order to ensure that they corresponds to both fpr and tpr which are sorted in reversed order during their calculation, such that they are monotome increasing.
- Parameters
thresholds¶ (
Union
[int
,List
[float
],Tensor
,None
]) –Can be one of:
If set to None, will use a non-binned approach where thresholds are dynamically calculated from all the data. Most accurate but also most memory consuming approach.
If set to an int (larger than 1), will use that number of thresholds linearly spaced from 0 to 1 as bins for the calculation.
If set to an list of floats, will use the indicated thresholds in the list as bins for the calculation
If set to an 1d tensor of floats, will use the indicated thresholds in the tensor as bins for the calculation.
validate_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.
- Returns
a tuple of 3 tensors containing:
fpr: an 1d tensor of size (n_thresholds+1, ) with false positive rate values
tpr: an 1d tensor of size (n_thresholds+1, ) with true positive rate values
thresholds: an 1d tensor of size (n_thresholds, ) with decreasing threshold values
- Return type
(tuple)
Example
>>> from torchmetrics.classification import BinaryROC >>> preds = torch.tensor([0, 0.5, 0.7, 0.8]) >>> target = torch.tensor([0, 1, 1, 0]) >>> metric = BinaryROC(thresholds=None) >>> metric(preds, target) (tensor([0.0000, 0.5000, 0.5000, 0.5000, 1.0000]), tensor([0.0000, 0.0000, 0.5000, 1.0000, 1.0000]), tensor([1.0000, 0.8000, 0.7000, 0.5000, 0.0000])) >>> metric = BinaryROC(thresholds=5) >>> metric(preds, target) (tensor([0.0000, 0.5000, 0.5000, 0.5000, 1.0000]), tensor([0., 0., 1., 1., 1.]), tensor([1.0000, 0.7500, 0.5000, 0.2500, 0.0000]))
Initializes internal Module state, shared by both nn.Module and ScriptModule.
MulticlassROC¶
- class torchmetrics.classification.MulticlassROC(num_classes, thresholds=None, ignore_index=None, validate_args=True, **kwargs)[source]
Computes the Receiver Operating Characteristic (ROC) for binary tasks. The curve consist of multiple pairs of true positive rate (TPR) and false positive rate (FPR) values evaluated at different thresholds, such that the tradeoff between the two values can be seen.
Accepts the following input tensors:
preds
(float tensor):(N, C, ...)
. Preds should be a tensor containing probabilities or logits for each observation. If preds has values outside [0,1] range we consider the input to be logits and will auto apply softmax per sample.target
(int tensor):(N, ...)
. Target should be a tensor containing ground truth labels, and therefore only contain values in the [0, n_classes-1] range (except if ignore_index is specified).
Additional dimension
...
will be flattened into the batch dimension.The implementation both supports calculating the metric in a non-binned but accurate version and a binned version that is less accurate but more memory efficient. Setting the thresholds argument to None will activate the non-binned version that uses memory of size whereas setting the thresholds argument to either an integer, list or a 1d tensor will use a binned version that uses memory of size (constant memory).
Note that outputted thresholds will be in reversed order to ensure that they corresponds to both fpr and tpr which are sorted in reversed order during their calculation, such that they are monotome increasing.
- Parameters
num_classes¶ (
int
) – Integer specifing the number of classesthresholds¶ (
Union
[int
,List
[float
],Tensor
,None
]) –Can be one of:
If set to None, will use a non-binned approach where thresholds are dynamically calculated from all the data. Most accurate but also most memory consuming approach.
If set to an int (larger than 1), will use that number of thresholds linearly spaced from 0 to 1 as bins for the calculation.
If set to an list of floats, will use the indicated thresholds in the list as bins for the calculation
If set to an 1d tensor of floats, will use the indicated thresholds in the tensor as bins for the calculation.
validate_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.
- Returns
a tuple of either 3 tensors or 3 lists containing
fpr: if thresholds=None a list for each class is returned with an 1d tensor of size (n_thresholds+1, ) with false positive rate values (length may differ between classes). If thresholds is set to something else, then a single 2d tensor of size (n_classes, n_thresholds+1) with false positive rate values is returned.
tpr: if thresholds=None a list for each class is returned with an 1d tensor of size (n_thresholds+1, ) with true positive rate values (length may differ between classes). If thresholds is set to something else, then a single 2d tensor of size (n_classes, n_thresholds+1) with true positive rate values is returned.
thresholds: if thresholds=None a list for each class is returned with an 1d tensor of size (n_thresholds, ) with decreasing threshold values (length may differ between classes). If threshold is set to something else, then a single 1d tensor of size (n_thresholds, ) is returned with shared threshold values for all classes.
- Return type
(tuple)
Example
>>> from torchmetrics.classification import MulticlassROC >>> preds = torch.tensor([[0.75, 0.05, 0.05, 0.05, 0.05], ... [0.05, 0.75, 0.05, 0.05, 0.05], ... [0.05, 0.05, 0.75, 0.05, 0.05], ... [0.05, 0.05, 0.05, 0.75, 0.05]]) >>> target = torch.tensor([0, 1, 3, 2]) >>> metric = MulticlassROC(num_classes=5, thresholds=None) >>> fpr, tpr, thresholds = metric(preds, target) >>> fpr [tensor([0., 0., 1.]), tensor([0., 0., 1.]), tensor([0.0000, 0.3333, 1.0000]), tensor([0.0000, 0.3333, 1.0000]), tensor([0., 1.])] >>> tpr [tensor([0., 1., 1.]), tensor([0., 1., 1.]), tensor([0., 0., 1.]), tensor([0., 0., 1.]), tensor([0., 0.])] >>> thresholds [tensor([1.0000, 0.7500, 0.0500]), tensor([1.0000, 0.7500, 0.0500]), tensor([1.0000, 0.7500, 0.0500]), tensor([1.0000, 0.7500, 0.0500]), tensor([1.0000, 0.0500])] >>> metric = MulticlassROC(num_classes=5, thresholds=5) >>> metric(preds, target) (tensor([[0.0000, 0.0000, 0.0000, 0.0000, 1.0000], [0.0000, 0.0000, 0.0000, 0.0000, 1.0000], [0.0000, 0.3333, 0.3333, 0.3333, 1.0000], [0.0000, 0.3333, 0.3333, 0.3333, 1.0000], [0.0000, 0.0000, 0.0000, 0.0000, 1.0000]]), tensor([[0., 1., 1., 1., 1.], [0., 1., 1., 1., 1.], [0., 0., 0., 0., 1.], [0., 0., 0., 0., 1.], [0., 0., 0., 0., 0.]]), tensor([1.0000, 0.7500, 0.5000, 0.2500, 0.0000]))
Initializes internal Module state, shared by both nn.Module and ScriptModule.
MultilabelROC¶
- class torchmetrics.classification.MultilabelROC(num_labels, thresholds=None, ignore_index=None, validate_args=True, **kwargs)[source]
Computes the Receiver Operating Characteristic (ROC) for binary tasks. The curve consist of multiple pairs of true positive rate (TPR) and false positive rate (FPR) values evaluated at different thresholds, such that the tradeoff between the two values can be seen.
Accepts the following input tensors:
preds
(float tensor):(N, C, ...)
. Preds should be a tensor containing probabilities or logits for each observation. If preds has values outside [0,1] range we consider the input to be logits and will auto apply sigmoid per element.target
(int tensor):(N, C, ...)
. Target should be a tensor containing ground truth labels, and therefore only contain {0,1} values (except if ignore_index is specified).
Additional dimension
...
will be flattened into the batch dimension.The implementation both supports calculating the metric in a non-binned but accurate version and a binned version that is less accurate but more memory efficient. Setting the thresholds argument to None will activate the non-binned version that uses memory of size whereas setting the thresholds argument to either an integer, list or a 1d tensor will use a binned version that uses memory of size (constant memory).
Note that outputted thresholds will be in reversed order to ensure that they corresponds to both fpr and tpr which are sorted in reversed order during their calculation, such that they are monotome increasing.
- Parameters
thresholds¶ (
Union
[int
,List
[float
],Tensor
,None
]) –Can be one of:
If set to None, will use a non-binned approach where thresholds are dynamically calculated from all the data. Most accurate but also most memory consuming approach.
If set to an int (larger than 1), will use that number of thresholds linearly spaced from 0 to 1 as bins for the calculation.
If set to an list of floats, will use the indicated thresholds in the list as bins for the calculation
If set to an 1d tensor of floats, will use the indicated thresholds in the tensor as bins for the calculation.
validate_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.
- Returns
a tuple of either 3 tensors or 3 lists containing
fpr: if thresholds=None a list for each label is returned with an 1d tensor of size (n_thresholds+1, ) with false positive rate values (length may differ between labels). If thresholds is set to something else, then a single 2d tensor of size (n_labels, n_thresholds+1) with false positive rate values is returned.
tpr: if thresholds=None a list for each label is returned with an 1d tensor of size (n_thresholds+1, ) with true positive rate values (length may differ between labels). If thresholds is set to something else, then a single 2d tensor of size (n_labels, n_thresholds+1) with true positive rate values is returned.
thresholds: if thresholds=None a list for each label is returned with an 1d tensor of size (n_thresholds, ) with decreasing threshold values (length may differ between labels). If threshold is set to something else, then a single 1d tensor of size (n_thresholds, ) is returned with shared threshold values for all labels.
- Return type
(tuple)
Example
>>> from torchmetrics.classification import MultilabelROC >>> preds = torch.tensor([[0.75, 0.05, 0.35], ... [0.45, 0.75, 0.05], ... [0.05, 0.55, 0.75], ... [0.05, 0.65, 0.05]]) >>> target = torch.tensor([[1, 0, 1], ... [0, 0, 0], ... [0, 1, 1], ... [1, 1, 1]]) >>> metric = MultilabelROC(num_labels=3, thresholds=None) >>> fpr, tpr, thresholds = metric(preds, target) >>> fpr [tensor([0.0000, 0.0000, 0.5000, 1.0000]), tensor([0.0000, 0.5000, 0.5000, 0.5000, 1.0000]), tensor([0., 0., 0., 1.])] >>> tpr [tensor([0.0000, 0.5000, 0.5000, 1.0000]), tensor([0.0000, 0.0000, 0.5000, 1.0000, 1.0000]), tensor([0.0000, 0.3333, 0.6667, 1.0000])] >>> thresholds [tensor([1.0000, 0.7500, 0.4500, 0.0500]), tensor([1.0000, 0.7500, 0.6500, 0.5500, 0.0500]), tensor([1.0000, 0.7500, 0.3500, 0.0500])] >>> metric = MultilabelROC(num_labels=3, thresholds=5) >>> metric(preds, target) (tensor([[0.0000, 0.0000, 0.0000, 0.5000, 1.0000], [0.0000, 0.5000, 0.5000, 0.5000, 1.0000], [0.0000, 0.0000, 0.0000, 0.0000, 1.0000]]), tensor([[0.0000, 0.5000, 0.5000, 0.5000, 1.0000], [0.0000, 0.0000, 1.0000, 1.0000, 1.0000], [0.0000, 0.3333, 0.3333, 0.6667, 1.0000]]), tensor([1.0000, 0.7500, 0.5000, 0.2500, 0.0000]))
Initializes internal Module state, shared by both nn.Module and ScriptModule.
Functional Interface¶
- torchmetrics.functional.roc(preds, target, num_classes=None, pos_label=None, sample_weights=None, task=None, thresholds=None, num_labels=None, ignore_index=None, validate_args=True)[source]
Note
From v0.10 an ‘binary_*’, ‘multiclass_*’, `’multilabel_*’ version now exist of each classification metric. Moving forward we recommend using these versions. This base metric will still work as it did prior to v0.10 until v0.11. From v0.11 the task argument introduced in this metric will be required and the general order of arguments may change, such that this metric will just function as an single entrypoint to calling the three specialized versions.
Computes the Receiver Operating Characteristic (ROC). Works with both binary, multiclass and multilabel input.
Note
If either the positive class or negative class is completly missing in the target tensor, the roc values are not well-defined in this case and a tensor of zeros will be returned (either fpr or tpr depending on what class is missing) together with a warning.
- Parameters
preds¶ (
Tensor
) – predictions from model (logits or probabilities)num_classes¶ (
Optional
[int
]) – integer with number of classes for multi-label and multiclass problems. Should be set toNone
for binary problems.pos_label¶ (
Optional
[int
]) – integer determining the positive class. Default isNone
which for binary problem is translated to 1. For multiclass problems this argument should not be set as we iteratively change it in the range[0, num_classes-1]
sample_weights¶ (
Optional
[Sequence
]) – sample weights for each data point
- Return type
Union
[Tuple
[Tensor
,Tensor
,Tensor
],Tuple
[List
[Tensor
],List
[Tensor
],List
[Tensor
]]]- Returns
3-element tuple containing
- fpr: tensor with false positive rates.
If multiclass or multilabel, this is a list of such tensors, one for each class/label.
- tpr: tensor with true positive rates.
If multiclass or multilabel, this is a list of such tensors, one for each class/label.
- thresholds: tensor with thresholds used for computing false- and true postive rates
If multiclass or multilabel, this is a list of such tensors, one for each class/label.
- Example (binary case):
>>> from torchmetrics.functional import roc >>> pred = torch.tensor([0, 1, 2, 3]) >>> target = torch.tensor([0, 1, 1, 1]) >>> fpr, tpr, thresholds = roc(pred, target, pos_label=1) >>> fpr tensor([0., 0., 0., 0., 1.]) >>> tpr tensor([0.0000, 0.3333, 0.6667, 1.0000, 1.0000]) >>> thresholds tensor([4, 3, 2, 1, 0])
- Example (multiclass case):
>>> from torchmetrics.functional import roc >>> pred = torch.tensor([[0.75, 0.05, 0.05, 0.05], ... [0.05, 0.75, 0.05, 0.05], ... [0.05, 0.05, 0.75, 0.05], ... [0.05, 0.05, 0.05, 0.75]]) >>> target = torch.tensor([0, 1, 3, 2]) >>> fpr, tpr, thresholds = roc(pred, target, num_classes=4) >>> fpr [tensor([0., 0., 1.]), tensor([0., 0., 1.]), tensor([0.0000, 0.3333, 1.0000]), tensor([0.0000, 0.3333, 1.0000])] >>> tpr [tensor([0., 1., 1.]), tensor([0., 1., 1.]), tensor([0., 0., 1.]), tensor([0., 0., 1.])] >>> thresholds [tensor([1.7500, 0.7500, 0.0500]), tensor([1.7500, 0.7500, 0.0500]), tensor([1.7500, 0.7500, 0.0500]), tensor([1.7500, 0.7500, 0.0500])]
- Example (multilabel case):
>>> from torchmetrics.functional import roc >>> pred = torch.tensor([[0.8191, 0.3680, 0.1138], ... [0.3584, 0.7576, 0.1183], ... [0.2286, 0.3468, 0.1338], ... [0.8603, 0.0745, 0.1837]]) >>> target = torch.tensor([[1, 1, 0], [0, 1, 0], [0, 0, 0], [0, 1, 1]]) >>> fpr, tpr, thresholds = roc(pred, target, num_classes=3, pos_label=1) >>> fpr [tensor([0.0000, 0.3333, 0.3333, 0.6667, 1.0000]), tensor([0., 0., 0., 1., 1.]), tensor([0.0000, 0.0000, 0.3333, 0.6667, 1.0000])] >>> tpr [tensor([0., 0., 1., 1., 1.]), tensor([0.0000, 0.3333, 0.6667, 0.6667, 1.0000]), tensor([0., 1., 1., 1., 1.])] >>> thresholds [tensor([1.8603, 0.8603, 0.8191, 0.3584, 0.2286]), tensor([1.7576, 0.7576, 0.3680, 0.3468, 0.0745]), tensor([1.1837, 0.1837, 0.1338, 0.1183, 0.1138])]
binary_roc¶
- torchmetrics.functional.classification.binary_roc(preds, target, thresholds=None, ignore_index=None, validate_args=True)[source]
Computes the Receiver Operating Characteristic (ROC) for binary tasks. The curve consist of multiple pairs of true positive rate (TPR) and false positive rate (FPR) values evaluated at different thresholds, such that the tradeoff between the two values can be seen.
Accepts the following input tensors:
preds
(float tensor):(N, ...)
. Preds should be a tensor containing probabilities or logits for each observation. If preds has values outside [0,1] range we consider the input to be logits and will auto apply sigmoid per element.target
(int tensor):(N, ...)
. Target should be a tensor containing ground truth labels, and therefore only contain {0,1} values (except if ignore_index is specified).
Additional dimension
...
will be flattened into the batch dimension.The implementation both supports calculating the metric in a non-binned but accurate version and a binned version that is less accurate but more memory efficient. Setting the thresholds argument to None will activate the non-binned version that uses memory of size whereas setting the thresholds argument to either an integer, list or a 1d tensor will use a binned version that uses memory of size (constant memory).
Note that outputted thresholds will be in reversed order to ensure that they corresponds to both fpr and tpr which are sorted in reversed order during their calculation, such that they are monotome increasing.
- Parameters
thresholds¶ (
Union
[int
,List
[float
],Tensor
,None
]) –Can be one of:
If set to None, will use a non-binned approach where thresholds are dynamically calculated from all the data. Most accurate but also most memory consuming approach.
If set to an int (larger than 1), will use that number of thresholds linearly spaced from 0 to 1 as bins for the calculation.
If set to an list of floats, will use the indicated thresholds in the list as bins for the calculation
If set to an 1d tensor of floats, will use the indicated thresholds in the tensor as bins for the calculation.
validate_args¶ (
bool
) – bool indicating if input arguments and tensors should be validated for correctness. Set toFalse
for faster computations.
- Returns
a tuple of 3 tensors containing:
fpr: an 1d tensor of size (n_thresholds+1, ) with false positive rate values
tpr: an 1d tensor of size (n_thresholds+1, ) with true positive rate values
thresholds: an 1d tensor of size (n_thresholds, ) with decreasing threshold values
- Return type
(tuple)
Example
>>> from torchmetrics.functional.classification import binary_roc >>> preds = torch.tensor([0, 0.5, 0.7, 0.8]) >>> target = torch.tensor([0, 1, 1, 0]) >>> binary_roc(preds, target, thresholds=None) (tensor([0.0000, 0.5000, 0.5000, 0.5000, 1.0000]), tensor([0.0000, 0.0000, 0.5000, 1.0000, 1.0000]), tensor([1.0000, 0.8000, 0.7000, 0.5000, 0.0000])) >>> binary_roc(preds, target, thresholds=5) (tensor([0.0000, 0.5000, 0.5000, 0.5000, 1.0000]), tensor([0., 0., 1., 1., 1.]), tensor([1.0000, 0.7500, 0.5000, 0.2500, 0.0000]))
multiclass_roc¶
- torchmetrics.functional.classification.multiclass_roc(preds, target, num_classes, thresholds=None, ignore_index=None, validate_args=True)[source]
Computes the Receiver Operating Characteristic (ROC) for binary tasks. The curve consist of multiple pairs of true positive rate (TPR) and false positive rate (FPR) values evaluated at different thresholds, such that the tradeoff between the two values can be seen.
Accepts the following input tensors:
preds
(float tensor):(N, C, ...)
. Preds should be a tensor containing probabilities or logits for each observation. If preds has values outside [0,1] range we consider the input to be logits and will auto apply softmax per sample.target
(int tensor):(N, ...)
. Target should be a tensor containing ground truth labels, and therefore only contain values in the [0, n_classes-1] range (except if ignore_index is specified).
Additional dimension
...
will be flattened into the batch dimension.The implementation both supports calculating the metric in a non-binned but accurate version and a binned version that is less accurate but more memory efficient. Setting the thresholds argument to None will activate the non-binned version that uses memory of size whereas setting the thresholds argument to either an integer, list or a 1d tensor will use a binned version that uses memory of size (constant memory).
Note that outputted thresholds will be in reversed order to ensure that they corresponds to both fpr and tpr which are sorted in reversed order during their calculation, such that they are monotome increasing.
- Parameters
num_classes¶ (
int
) – Integer specifing the number of classesthresholds¶ (
Union
[int
,List
[float
],Tensor
,None
]) –Can be one of:
If set to None, will use a non-binned approach where thresholds are dynamically calculated from all the data. Most accurate but also most memory consuming approach.
If set to an int (larger than 1), will use that number of thresholds linearly spaced from 0 to 1 as bins for the calculation.
If set to an list of floats, will use the indicated thresholds in the list as bins for the calculation
If set to an 1d tensor of floats, will use the indicated thresholds in the tensor as bins for the calculation.
validate_args¶ (
bool
) – bool indicating if input arguments and tensors should be validated for correctness. Set toFalse
for faster computations.
- Returns
a tuple of either 3 tensors or 3 lists containing
fpr: if thresholds=None a list for each class is returned with an 1d tensor of size (n_thresholds+1, ) with false positive rate values (length may differ between classes). If thresholds is set to something else, then a single 2d tensor of size (n_classes, n_thresholds+1) with false positive rate values is returned.
tpr: if thresholds=None a list for each class is returned with an 1d tensor of size (n_thresholds+1, ) with true positive rate values (length may differ between classes). If thresholds is set to something else, then a single 2d tensor of size (n_classes, n_thresholds+1) with true positive rate values is returned.
thresholds: if thresholds=None a list for each class is returned with an 1d tensor of size (n_thresholds, ) with decreasing threshold values (length may differ between classes). If threshold is set to something else, then a single 1d tensor of size (n_thresholds, ) is returned with shared threshold values for all classes.
- Return type
(tuple)
Example
>>> from torchmetrics.functional.classification import multiclass_roc >>> preds = torch.tensor([[0.75, 0.05, 0.05, 0.05, 0.05], ... [0.05, 0.75, 0.05, 0.05, 0.05], ... [0.05, 0.05, 0.75, 0.05, 0.05], ... [0.05, 0.05, 0.05, 0.75, 0.05]]) >>> target = torch.tensor([0, 1, 3, 2]) >>> fpr, tpr, thresholds = multiclass_roc( ... preds, target, num_classes=5, thresholds=None ... ) >>> fpr [tensor([0., 0., 1.]), tensor([0., 0., 1.]), tensor([0.0000, 0.3333, 1.0000]), tensor([0.0000, 0.3333, 1.0000]), tensor([0., 1.])] >>> tpr [tensor([0., 1., 1.]), tensor([0., 1., 1.]), tensor([0., 0., 1.]), tensor([0., 0., 1.]), tensor([0., 0.])] >>> thresholds [tensor([1.0000, 0.7500, 0.0500]), tensor([1.0000, 0.7500, 0.0500]), tensor([1.0000, 0.7500, 0.0500]), tensor([1.0000, 0.7500, 0.0500]), tensor([1.0000, 0.0500])] >>> multiclass_roc( ... preds, target, num_classes=5, thresholds=5 ... ) (tensor([[0.0000, 0.0000, 0.0000, 0.0000, 1.0000], [0.0000, 0.0000, 0.0000, 0.0000, 1.0000], [0.0000, 0.3333, 0.3333, 0.3333, 1.0000], [0.0000, 0.3333, 0.3333, 0.3333, 1.0000], [0.0000, 0.0000, 0.0000, 0.0000, 1.0000]]), tensor([[0., 1., 1., 1., 1.], [0., 1., 1., 1., 1.], [0., 0., 0., 0., 1.], [0., 0., 0., 0., 1.], [0., 0., 0., 0., 0.]]), tensor([1.0000, 0.7500, 0.5000, 0.2500, 0.0000]))
multilabel_roc¶
- torchmetrics.functional.classification.multilabel_roc(preds, target, num_labels, thresholds=None, ignore_index=None, validate_args=True)[source]
Computes the Receiver Operating Characteristic (ROC) for binary tasks. The curve consist of multiple pairs of true positive rate (TPR) and false positive rate (FPR) values evaluated at different thresholds, such that the tradeoff between the two values can be seen.
Accepts the following input tensors:
preds
(float tensor):(N, C, ...)
. Preds should be a tensor containing probabilities or logits for each observation. If preds has values outside [0,1] range we consider the input to be logits and will auto apply sigmoid per element.target
(int tensor):(N, C, ...)
. Target should be a tensor containing ground truth labels, and therefore only contain {0,1} values (except if ignore_index is specified).
Additional dimension
...
will be flattened into the batch dimension.The implementation both supports calculating the metric in a non-binned but accurate version and a binned version that is less accurate but more memory efficient. Setting the thresholds argument to None will activate the non-binned version that uses memory of size whereas setting the thresholds argument to either an integer, list or a 1d tensor will use a binned version that uses memory of size (constant memory).
Note that outputted thresholds will be in reversed order to ensure that they corresponds to both fpr and tpr which are sorted in reversed order during their calculation, such that they are monotome increasing.
- Parameters
thresholds¶ (
Union
[int
,List
[float
],Tensor
,None
]) –Can be one of:
If set to None, will use a non-binned approach where thresholds are dynamically calculated from all the data. Most accurate but also most memory consuming approach.
If set to an int (larger than 1), will use that number of thresholds linearly spaced from 0 to 1 as bins for the calculation.
If set to an list of floats, will use the indicated thresholds in the list as bins for the calculation
If set to an 1d tensor of floats, will use the indicated thresholds in the tensor as bins for the calculation.
validate_args¶ (
bool
) – bool indicating if input arguments and tensors should be validated for correctness. Set toFalse
for faster computations.
- Returns
a tuple of either 3 tensors or 3 lists containing
fpr: if thresholds=None a list for each label is returned with an 1d tensor of size (n_thresholds+1, ) with false positive rate values (length may differ between labels). If thresholds is set to something else, then a single 2d tensor of size (n_labels, n_thresholds+1) with false positive rate values is returned.
tpr: if thresholds=None a list for each label is returned with an 1d tensor of size (n_thresholds+1, ) with true positive rate values (length may differ between labels). If thresholds is set to something else, then a single 2d tensor of size (n_labels, n_thresholds+1) with true positive rate values is returned.
thresholds: if thresholds=None a list for each label is returned with an 1d tensor of size (n_thresholds, ) with decreasing threshold values (length may differ between labels). If threshold is set to something else, then a single 1d tensor of size (n_thresholds, ) is returned with shared threshold values for all labels.
- Return type
(tuple)
Example
>>> from torchmetrics.functional.classification import multilabel_roc >>> preds = torch.tensor([[0.75, 0.05, 0.35], ... [0.45, 0.75, 0.05], ... [0.05, 0.55, 0.75], ... [0.05, 0.65, 0.05]]) >>> target = torch.tensor([[1, 0, 1], ... [0, 0, 0], ... [0, 1, 1], ... [1, 1, 1]]) >>> fpr, tpr, thresholds = multilabel_roc( ... preds, target, num_labels=3, thresholds=None ... ) >>> fpr [tensor([0.0000, 0.0000, 0.5000, 1.0000]), tensor([0.0000, 0.5000, 0.5000, 0.5000, 1.0000]), tensor([0., 0., 0., 1.])] >>> tpr [tensor([0.0000, 0.5000, 0.5000, 1.0000]), tensor([0.0000, 0.0000, 0.5000, 1.0000, 1.0000]), tensor([0.0000, 0.3333, 0.6667, 1.0000])] >>> thresholds [tensor([1.0000, 0.7500, 0.4500, 0.0500]), tensor([1.0000, 0.7500, 0.6500, 0.5500, 0.0500]), tensor([1.0000, 0.7500, 0.3500, 0.0500])] >>> multilabel_roc( ... preds, target, num_labels=3, thresholds=5 ... ) (tensor([[0.0000, 0.0000, 0.0000, 0.5000, 1.0000], [0.0000, 0.5000, 0.5000, 0.5000, 1.0000], [0.0000, 0.0000, 0.0000, 0.0000, 1.0000]]), tensor([[0.0000, 0.5000, 0.5000, 0.5000, 1.0000], [0.0000, 0.0000, 1.0000, 1.0000, 1.0000], [0.0000, 0.3333, 0.3333, 0.6667, 1.0000]]), tensor([1.0000, 0.7500, 0.5000, 0.2500, 0.0000]))