Specificity¶
Module Interface¶
- class torchmetrics.Specificity(num_classes=None, threshold=0.5, average='micro', mdmc_average=None, ignore_index=None, top_k=None, multiclass=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 Specificity:
Where and represent the number of true negatives and false positives respecitively. With the use of
top_k
parameter, this metric can generalize to Specificity@K.The reduction method (how the specificity scores are aggregated) is controlled by the
average
parameter, and additionally by themdmc_average
parameter in the multi-dimensional multi-class case. Accepts all inputs listed in Input types.- Parameters
num_classes¶ (
Optional
[int
]) – Number of classes. Necessary for'macro'
,'weighted'
andNone
average methods.threshold¶ (
float
) – Threshold probability value for transforming probability predictions to binary (0,1) predictions, in the case of binary or multi-label inputs.average¶ (
Optional
[Literal
[‘micro’, ‘macro’, ‘weighted’, ‘none’]]) –Defines the reduction that is applied. Should be one of the following:
'micro'
[default]: Calculate the metric globally, across all samples and classes.'macro'
: Calculate the metric for each class separately, and average the metrics across classes (with equal weights for each class).'weighted'
: Calculate the metric for each class separately, and average the metrics across classes, weighting each class by its support (tn + fp
).'none'
orNone
: Calculate the metric for each class separately, and return the metric for every class.'samples'
: Calculate the metric for each sample, and average the metrics across samples (with equal weights for each sample).
Note
What is considered a sample in the multi-dimensional multi-class case depends on the value of
mdmc_average
.mdmc_average¶ (
Optional
[str
]) –Defines how averaging is done for multi-dimensional multi-class inputs (on top of the
average
parameter). Should be one of the following:None
[default]: Should be left unchanged if your data is not multi-dimensional multi-class.'samplewise'
: In this case, the statistics are computed separately for each sample on theN
axis, and then averaged over samples. The computation for each sample is done by treating the flattened extra axes...
(see Input types) as theN
dimension within the sample, and computing the metric for the sample based on that.'global'
: In this case theN
and...
dimensions of the inputs (see Input types) are flattened into a newN_X
sample axis, i.e. the inputs are treated as if they were(N_X, C)
. From here on theaverage
parameter applies as usual.
ignore_index¶ (
Optional
[int
]) – Integer specifying a target class to ignore. If given, this class index does not contribute to the returned score, regardless of reduction method. If an index is ignored, andaverage=None
or'none'
, the score for the ignored class will be returned asnan
.Number of the highest probability entries for each sample to convert to 1s - relevant only for inputs with probability predictions. If this parameter is set for multi-label inputs, it will take precedence over
threshold
. For (multi-dim) multi-class inputs, this parameter defaults to 1.Should be left unset (
None
) for inputs with label predictions.multiclass¶ (
Optional
[bool
]) – Used only in certain special cases, where you want to treat inputs as a different type than what they appear to be. See the parameter’s documentation section for a more detailed explanation and examples.kwargs¶ (
Any
) – Additional keyword arguments, see Advanced metric settings for more info.
- Raises
ValueError – If
average
is none of"micro"
,"macro"
,"weighted"
,"samples"
,"none"
,None
.
Example
>>> from torchmetrics import Specificity >>> preds = torch.tensor([2, 0, 2, 1]) >>> target = torch.tensor([1, 1, 2, 0]) >>> specificity = Specificity(average='macro', num_classes=3) >>> specificity(preds, target) tensor(0.6111) >>> specificity = Specificity(average='micro') >>> specificity(preds, target) tensor(0.6250)
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- compute()[source]
Computes the specificity score based on inputs passed in to
update
previously.- Returns
If
average in ['micro', 'macro', 'weighted', 'samples']
, a one-element tensor will be returnedIf
average in ['none', None]
, the shape will be(C,)
, whereC
stands for the number of classes
- Return type
The shape of the returned tensor depends on the
average
parameter
BinarySpecificity¶
- class torchmetrics.classification.BinarySpecificity(threshold=0.5, multidim_average='global', ignore_index=None, validate_args=True, **kwargs)[source]
Computes Specificity for binary tasks:
Where and represent the number of true negatives and false positives respecitively.
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. Addtionally, we convert to int tensor with thresholding using the value inthreshold
.target
(int tensor):(N, ...)
The influence of the additional dimension
...
(if present) will be determined by the multidim_average argument.- Parameters
threshold¶ (
float
) – Threshold for transforming probability to binary {0,1} predictionsmultidim_average¶ (
Literal
[‘global’, ‘samplewise’]) –Defines how additionally dimensions
...
should be handled. Should be one of the following:global
: Additional dimensions are flatted along the batch dimensionsamplewise
: Statistic will be calculated independently for each sample on theN
axis. The statistics in this case are calculated over the additional dimensions.
ignore_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.
- Returns
If
multidim_average
is set toglobal
, the metric returns a scalar value. Ifmultidim_average
is set tosamplewise
, the metric returns(N,)
vector consisting of a scalar value per sample.
- Example (preds is int tensor):
>>> from torchmetrics.classification import BinarySpecificity >>> target = torch.tensor([0, 1, 0, 1, 0, 1]) >>> preds = torch.tensor([0, 0, 1, 1, 0, 1]) >>> metric = BinarySpecificity() >>> metric(preds, target) tensor(0.6667)
- Example (preds is float tensor):
>>> from torchmetrics.classification import BinarySpecificity >>> target = torch.tensor([0, 1, 0, 1, 0, 1]) >>> preds = torch.tensor([0.11, 0.22, 0.84, 0.73, 0.33, 0.92]) >>> metric = BinarySpecificity() >>> metric(preds, target) tensor(0.6667)
- Example (multidim tensors):
>>> from torchmetrics.classification import BinarySpecificity >>> target = torch.tensor([[[0, 1], [1, 0], [0, 1]], [[1, 1], [0, 0], [1, 0]]]) >>> preds = torch.tensor( ... [ ... [[0.59, 0.91], [0.91, 0.99], [0.63, 0.04]], ... [[0.38, 0.04], [0.86, 0.780], [0.45, 0.37]], ... ] ... ) >>> metric = BinarySpecificity(multidim_average='samplewise') >>> metric(preds, target) tensor([0.0000, 0.3333])
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- compute()[source]
Computes the final statistics.
- Return type
- Returns
The metric returns a tensor of shape
(..., 5)
, where the last dimension corresponds to[tp, fp, tn, fn, sup]
(sup
stands for support and equalstp + fn
). The shape depends on themultidim_average
parameter:If
multidim_average
is set toglobal
, the shape will be(5,)
If
multidim_average
is set tosamplewise
, the shape will be(N, 5)
MulticlassSpecificity¶
- class torchmetrics.classification.MulticlassSpecificity(num_classes, top_k=1, average='macro', multidim_average='global', ignore_index=None, validate_args=True, **kwargs)[source]
Computes Specificity for multiclass tasks:
Where and represent the number of true negatives and false positives respecitively.
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, ...)
The influence of the additional dimension
...
(if present) will be determined by the multidim_average argument.- Parameters
num_classes¶ (
int
) – Integer specifing the number of classesaverage¶ (
Optional
[Literal
[‘micro’, ‘macro’, ‘weighted’, ‘none’]]) –Defines the reduction that is applied over labels. Should be one of the following:
micro
: Sum statistics over all labelsmacro
: Calculate statistics for each label and average themweighted
: Calculates statistics for each label and computes weighted average using their support"none"
orNone
: Calculates statistic for each label and applies no reduction
top_k¶ (
int
) – Number of highest probability or logit score predictions considered to find the correct label. Only works whenpreds
contain probabilities/logits.multidim_average¶ (
Literal
[‘global’, ‘samplewise’]) –Defines how additionally dimensions
...
should be handled. Should be one of the following:global
: Additional dimensions are flatted along the batch dimensionsamplewise
: Statistic will be calculated independently for each sample on theN
axis. The statistics in this case are calculated over the additional dimensions.
ignore_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.
- Returns
If
multidim_average
is set toglobal
:If
average='micro'/'macro'/'weighted'
, the output will be a scalar tensorIf
average=None/'none'
, the shape will be(C,)
If
multidim_average
is set tosamplewise
:If
average='micro'/'macro'/'weighted'
, the shape will be(N,)
If
average=None/'none'
, the shape will be(N, C)
- Return type
The returned shape depends on the
average
andmultidim_average
arguments
- Example (preds is int tensor):
>>> from torchmetrics.classification import MulticlassSpecificity >>> target = torch.tensor([2, 1, 0, 0]) >>> preds = torch.tensor([2, 1, 0, 1]) >>> metric = MulticlassSpecificity(num_classes=3) >>> metric(preds, target) tensor(0.8889) >>> metric = MulticlassSpecificity(num_classes=3, average=None) >>> metric(preds, target) tensor([1.0000, 0.6667, 1.0000])
- Example (preds is float tensor):
>>> from torchmetrics.classification import MulticlassSpecificity >>> target = torch.tensor([2, 1, 0, 0]) >>> preds = torch.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 = MulticlassSpecificity(num_classes=3) >>> metric(preds, target) tensor(0.8889) >>> metric = MulticlassSpecificity(num_classes=3, average=None) >>> metric(preds, target) tensor([1.0000, 0.6667, 1.0000])
- Example (multidim tensors):
>>> from torchmetrics.classification import MulticlassSpecificity >>> target = torch.tensor([[[0, 1], [2, 1], [0, 2]], [[1, 1], [2, 0], [1, 2]]]) >>> preds = torch.tensor([[[0, 2], [2, 0], [0, 1]], [[2, 2], [2, 1], [1, 0]]]) >>> metric = MulticlassSpecificity(num_classes=3, multidim_average='samplewise') >>> metric(preds, target) tensor([0.7500, 0.6556]) >>> metric = MulticlassSpecificity(num_classes=3, multidim_average='samplewise', average=None) >>> metric(preds, target) tensor([[0.7500, 0.7500, 0.7500], [0.8000, 0.6667, 0.5000]])
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- compute()[source]
Computes the final statistics.
- Return type
- Returns
The metric returns a tensor of shape
(..., 5)
, where the last dimension corresponds to[tp, fp, tn, fn, sup]
(sup
stands for support and equalstp + fn
). The shape depends onaverage
andmultidim_average
parameters:If
multidim_average
is set toglobal
If
average='micro'/'macro'/'weighted'
, the shape will be(5,)
If
average=None/'none'
, the shape will be(C, 5)
If
multidim_average
is set tosamplewise
If
average='micro'/'macro'/'weighted'
, the shape will be(N, 5)
If
average=None/'none'
, the shape will be(N, C, 5)
MultilabelSpecificity¶
- class torchmetrics.classification.MultilabelSpecificity(num_labels, threshold=0.5, average='macro', multidim_average='global', ignore_index=None, validate_args=True, **kwargs)[source]
Computes Specificity for multilabel tasks
Where and represent the number of true negatives and false positives respecitively.
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. Addtionally, we convert to int tensor with thresholding using the value inthreshold
.target
(int tensor):(N, C, ...)
The influence of the additional dimension
...
(if present) will be determined by the multidim_average argument.- Parameters
threshold¶ (
float
) – Threshold for transforming probability to binary (0,1) predictionsaverage¶ (
Optional
[Literal
[‘micro’, ‘macro’, ‘weighted’, ‘none’]]) –Defines the reduction that is applied over labels. Should be one of the following:
micro
: Sum statistics over all labelsmacro
: Calculate statistics for each label and average themweighted
: Calculates statistics for each label and computes weighted average using their support"none"
orNone
: Calculates statistic for each label and applies no reduction
multidim_average¶ (
Literal
[‘global’, ‘samplewise’]) –Defines how additionally dimensions
...
should be handled. Should be one of the following:global
: Additional dimensions are flatted along the batch dimensionsamplewise
: Statistic will be calculated independently for each sample on theN
axis. The statistics in this case are calculated over the additional dimensions.
ignore_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.
- Returns
If
multidim_average
is set toglobal
- Ifaverage='micro'/'macro'/'weighted'
, the output will be a scalar tensor - Ifaverage=None/'none'
, the shape will be(C,)
If
multidim_average
is set tosamplewise
- Ifaverage='micro'/'macro'/'weighted'
, the shape will be(N,)
- Ifaverage=None/'none'
, the shape will be(N, C)
- Return type
The returned shape depends on the
average
andmultidim_average
arguments
- Example (preds is int tensor):
>>> from torchmetrics.classification import MultilabelSpecificity >>> target = torch.tensor([[0, 1, 0], [1, 0, 1]]) >>> preds = torch.tensor([[0, 0, 1], [1, 0, 1]]) >>> metric = MultilabelSpecificity(num_labels=3) >>> metric(preds, target) tensor(0.6667) >>> metric = MultilabelSpecificity(num_labels=3, average=None) >>> metric(preds, target) tensor([1., 1., 0.])
- Example (preds is float tensor):
>>> from torchmetrics.classification import MultilabelSpecificity >>> target = torch.tensor([[0, 1, 0], [1, 0, 1]]) >>> preds = torch.tensor([[0.11, 0.22, 0.84], [0.73, 0.33, 0.92]]) >>> metric = MultilabelSpecificity(num_labels=3) >>> metric(preds, target) tensor(0.6667) >>> metric = MultilabelSpecificity(num_labels=3, average=None) >>> metric(preds, target) tensor([1., 1., 0.])
- Example (multidim tensors):
>>> from torchmetrics.classification import MultilabelSpecificity >>> target = torch.tensor([[[0, 1], [1, 0], [0, 1]], [[1, 1], [0, 0], [1, 0]]]) >>> preds = torch.tensor( ... [ ... [[0.59, 0.91], [0.91, 0.99], [0.63, 0.04]], ... [[0.38, 0.04], [0.86, 0.780], [0.45, 0.37]], ... ] ... ) >>> metric = MultilabelSpecificity(num_labels=3, multidim_average='samplewise') >>> metric(preds, target) tensor([0.0000, 0.3333]) >>> metric = MultilabelSpecificity(num_labels=3, multidim_average='samplewise', average=None) >>> metric(preds, target) tensor([[0., 0., 0.], [0., 0., 1.]])
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- compute()[source]
Computes the final statistics.
- Return type
- Returns
The metric returns a tensor of shape
(..., 5)
, where the last dimension corresponds to[tp, fp, tn, fn, sup]
(sup
stands for support and equalstp + fn
). The shape depends onaverage
andmultidim_average
parameters:If
multidim_average
is set toglobal
If
average='micro'/'macro'/'weighted'
, the shape will be(5,)
If
average=None/'none'
, the shape will be(C, 5)
If
multidim_average
is set tosamplewise
If
average='micro'/'macro'/'weighted'
, the shape will be(N, 5)
If
average=None/'none'
, the shape will be(N, C, 5)
Functional Interface¶
- torchmetrics.functional.specificity(preds, target, average='micro', mdmc_average=None, ignore_index=None, num_classes=None, threshold=0.5, top_k=None, multiclass=None, task=None, num_labels=None, multidim_average='global', 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 Specificity
Where and represent the number of true negatives and false positives respecitively. With the use of
top_k
parameter, this metric can generalize to Specificity@K.The reduction method (how the specificity scores are aggregated) is controlled by the
average
parameter, and additionally by themdmc_average
parameter in the multi-dimensional multi-class case. Accepts all inputs listed in Input types.- Parameters
preds¶ (
Tensor
) – Predictions from model (probabilities, or labels)average¶ (
Optional
[Literal
[‘micro’, ‘macro’, ‘weighted’, ‘none’]]) –Defines the reduction that is applied. Should be one of the following:
'micro'
[default]: Calculate the metric globally, across all samples and classes.'macro'
: Calculate the metric for each class separately, and average the metrics across classes (with equal weights for each class).'weighted'
: Calculate the metric for each class separately, and average the metrics across classes, weighting each class by its support (tn + fp
).'none'
orNone
: Calculate the metric for each class separately, and return the metric for every class.'samples'
: Calculate the metric for each sample, and average the metrics across samples (with equal weights for each sample).
Note
What is considered a sample in the multi-dimensional multi-class case depends on the value of
mdmc_average
.Note
If
'none'
and a given class doesn’t occur in thepreds
ortarget
, the value for the class will benan
.mdmc_average¶ (
Optional
[str
]) –Defines how averaging is done for multi-dimensional multi-class inputs (on top of the
average
parameter). Should be one of the following:None
[default]: Should be left unchanged if your data is not multi-dimensional multi-class.'samplewise'
: In this case, the statistics are computed separately for each sample on theN
axis, and then averaged over samples. The computation for each sample is done by treating the flattened extra axes...
(see Input types) as theN
dimension within the sample, and computing the metric for the sample based on that.'global'
: In this case theN
and...
dimensions of the inputs (see Input types) are flattened into a newN_X
sample axis, i.e. the inputs are treated as if they were(N_X, C)
. From here on theaverage
parameter applies as usual.
ignore_index¶ (
Optional
[int
]) – Integer specifying a target class to ignore. If given, this class index does not contribute to the returned score, regardless of reduction method. If an index is ignored, andaverage=None
or'none'
, the score for the ignored class will be returned asnan
.num_classes¶ (
Optional
[int
]) – Number of classes. Necessary for'macro'
,'weighted'
andNone
average methods.threshold¶ (
float
) – Threshold probability value for transforming probability predictions to binary (0,1) predictions, in the case of binary or multi-label inputsNumber of highest probability entries for each sample to convert to 1s - relevant only for inputs with probability predictions. If this parameter is set for multi-label inputs, it will take precedence over
threshold
. For (multi-dim) multi-class inputs, this parameter defaults to 1.Should be left unset (
None
) for inputs with label predictions.multiclass¶ (
Optional
[bool
]) – Used only in certain special cases, where you want to treat inputs as a different type than what they appear to be. See the parameter’s documentation section for a more detailed explanation and examples.
- Return type
- Returns
The shape of the returned tensor depends on the
average
parameterIf
average in ['micro', 'macro', 'weighted', 'samples']
, a one-element tensor will be returnedIf
average in ['none', None]
, the shape will be(C,)
, whereC
stands for the number of classes
- Raises
ValueError – If
average
is not one of"micro"
,"macro"
,"weighted"
,"samples"
,"none"
orNone
ValueError – If
mdmc_average
is not one ofNone
,"samplewise"
,"global"
.ValueError – If
average
is set butnum_classes
is not provided.ValueError – If
num_classes
is set andignore_index
is not in the range[0, num_classes)
.
Example
>>> from torchmetrics.functional import specificity >>> preds = torch.tensor([2, 0, 2, 1]) >>> target = torch.tensor([1, 1, 2, 0]) >>> specificity(preds, target, average='macro', num_classes=3) tensor(0.6111) >>> specificity(preds, target, average='micro') tensor(0.6250)
binary_specificity¶
- torchmetrics.functional.classification.binary_specificity(preds, target, threshold=0.5, multidim_average='global', ignore_index=None, validate_args=True)[source]
Computes Specificity for binary tasks:
Where and represent the number of true negatives and false positives respecitively.
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. Addtionally, we convert to int tensor with thresholding using the value inthreshold
.target
(int tensor):(N, ...)
The influence of the additional dimension
...
(if present) will be determined by the multidim_average argument.- Parameters
threshold¶ (
float
) – Threshold for transforming probability to binary {0,1} predictionsmultidim_average¶ (
Literal
[‘global’, ‘samplewise’]) –Defines how additionally dimensions
...
should be handled. Should be one of the following:global
: Additional dimensions are flatted along the batch dimensionsamplewise
: Statistic will be calculated independently for each sample on theN
axis. The statistics in this case are calculated over the additional dimensions.
ignore_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
- Returns
If
multidim_average
is set toglobal
, the metric returns a scalar value. Ifmultidim_average
is set tosamplewise
, the metric returns(N,)
vector consisting of a scalar value per sample.
- Example (preds is int tensor):
>>> from torchmetrics.functional.classification import binary_specificity >>> target = torch.tensor([0, 1, 0, 1, 0, 1]) >>> preds = torch.tensor([0, 0, 1, 1, 0, 1]) >>> binary_specificity(preds, target) tensor(0.6667)
- Example (preds is float tensor):
>>> from torchmetrics.functional.classification import binary_specificity >>> target = torch.tensor([0, 1, 0, 1, 0, 1]) >>> preds = torch.tensor([0.11, 0.22, 0.84, 0.73, 0.33, 0.92]) >>> binary_specificity(preds, target) tensor(0.6667)
- Example (multidim tensors):
>>> from torchmetrics.functional.classification import binary_specificity >>> target = torch.tensor([[[0, 1], [1, 0], [0, 1]], [[1, 1], [0, 0], [1, 0]]]) >>> preds = torch.tensor( ... [ ... [[0.59, 0.91], [0.91, 0.99], [0.63, 0.04]], ... [[0.38, 0.04], [0.86, 0.780], [0.45, 0.37]], ... ] ... ) >>> binary_specificity(preds, target, multidim_average='samplewise') tensor([0.0000, 0.3333])
multiclass_specificity¶
- torchmetrics.functional.classification.multiclass_specificity(preds, target, num_classes, average='macro', top_k=1, multidim_average='global', ignore_index=None, validate_args=True)[source]
Computes Specificity for multiclass tasks:
Where and represent the number of true negatives and false positives respecitively.
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, ...)
The influence of the additional dimension
...
(if present) will be determined by the multidim_average argument.- Parameters
num_classes¶ (
int
) – Integer specifing the number of classesaverage¶ (
Optional
[Literal
[‘micro’, ‘macro’, ‘weighted’, ‘none’]]) –Defines the reduction that is applied over labels. Should be one of the following:
micro
: Sum statistics over all labelsmacro
: Calculate statistics for each label and average themweighted
: Calculates statistics for each label and computes weighted average using their support"none"
orNone
: Calculates statistic for each label and applies no reduction
top_k¶ (
int
) – Number of highest probability or logit score predictions considered to find the correct label. Only works whenpreds
contain probabilities/logits.multidim_average¶ (
Literal
[‘global’, ‘samplewise’]) –Defines how additionally dimensions
...
should be handled. Should be one of the following:global
: Additional dimensions are flatted along the batch dimensionsamplewise
: Statistic will be calculated independently for each sample on theN
axis. The statistics in this case are calculated over the additional dimensions.
ignore_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.
- Returns
If
multidim_average
is set toglobal
:If
average='micro'/'macro'/'weighted'
, the output will be a scalar tensorIf
average=None/'none'
, the shape will be(C,)
If
multidim_average
is set tosamplewise
:If
average='micro'/'macro'/'weighted'
, the shape will be(N,)
If
average=None/'none'
, the shape will be(N, C)
- Return type
The returned shape depends on the
average
andmultidim_average
arguments
- Example (preds is int tensor):
>>> from torchmetrics.functional.classification import multiclass_specificity >>> target = torch.tensor([2, 1, 0, 0]) >>> preds = torch.tensor([2, 1, 0, 1]) >>> multiclass_specificity(preds, target, num_classes=3) tensor(0.8889) >>> multiclass_specificity(preds, target, num_classes=3, average=None) tensor([1.0000, 0.6667, 1.0000])
- Example (preds is float tensor):
>>> from torchmetrics.functional.classification import multiclass_specificity >>> target = torch.tensor([2, 1, 0, 0]) >>> preds = torch.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_specificity(preds, target, num_classes=3) tensor(0.8889) >>> multiclass_specificity(preds, target, num_classes=3, average=None) tensor([1.0000, 0.6667, 1.0000])
- Example (multidim tensors):
>>> from torchmetrics.functional.classification import multiclass_specificity >>> target = torch.tensor([[[0, 1], [2, 1], [0, 2]], [[1, 1], [2, 0], [1, 2]]]) >>> preds = torch.tensor([[[0, 2], [2, 0], [0, 1]], [[2, 2], [2, 1], [1, 0]]]) >>> multiclass_specificity(preds, target, num_classes=3, multidim_average='samplewise') tensor([0.7500, 0.6556]) >>> multiclass_specificity(preds, target, num_classes=3, multidim_average='samplewise', average=None) tensor([[0.7500, 0.7500, 0.7500], [0.8000, 0.6667, 0.5000]])
multilabel_specificity¶
- torchmetrics.functional.classification.multilabel_specificity(preds, target, num_labels, threshold=0.5, average='macro', multidim_average='global', ignore_index=None, validate_args=True)[source]
Computes Specificity for multilabel tasks
Where and represent the number of true negatives and false positives respecitively.
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. Addtionally, we convert to int tensor with thresholding using the value inthreshold
.target
(int tensor):(N, C, ...)
The influence of the additional dimension
...
(if present) will be determined by the multidim_average argument.- Parameters
threshold¶ (
float
) – Threshold for transforming probability to binary (0,1) predictionsaverage¶ (
Optional
[Literal
[‘micro’, ‘macro’, ‘weighted’, ‘none’]]) –Defines the reduction that is applied over labels. Should be one of the following:
micro
: Sum statistics over all labelsmacro
: Calculate statistics for each label and average themweighted
: Calculates statistics for each label and computes weighted average using their support"none"
orNone
: Calculates statistic for each label and applies no reduction
multidim_average¶ (
Literal
[‘global’, ‘samplewise’]) –Defines how additionally dimensions
...
should be handled. Should be one of the following:global
: Additional dimensions are flatted along the batch dimensionsamplewise
: Statistic will be calculated independently for each sample on theN
axis. The statistics in this case are calculated over the additional dimensions.
ignore_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.
- Returns
If
multidim_average
is set toglobal
:If
average='micro'/'macro'/'weighted'
, the output will be a scalar tensorIf
average=None/'none'
, the shape will be(C,)
If
multidim_average
is set tosamplewise
:If
average='micro'/'macro'/'weighted'
, the shape will be(N,)
If
average=None/'none'
, the shape will be(N, C)
- Return type
The returned shape depends on the
average
andmultidim_average
arguments
- Example (preds is int tensor):
>>> from torchmetrics.functional.classification import multilabel_specificity >>> target = torch.tensor([[0, 1, 0], [1, 0, 1]]) >>> preds = torch.tensor([[0, 0, 1], [1, 0, 1]]) >>> multilabel_specificity(preds, target, num_labels=3) tensor(0.6667) >>> multilabel_specificity(preds, target, num_labels=3, average=None) tensor([1., 1., 0.])
- Example (preds is float tensor):
>>> from torchmetrics.functional.classification import multilabel_specificity >>> target = torch.tensor([[0, 1, 0], [1, 0, 1]]) >>> preds = torch.tensor([[0.11, 0.22, 0.84], [0.73, 0.33, 0.92]]) >>> multilabel_specificity(preds, target, num_labels=3) tensor(0.6667) >>> multilabel_specificity(preds, target, num_labels=3, average=None) tensor([1., 1., 0.])
- Example (multidim tensors):
>>> from torchmetrics.functional.classification import multilabel_specificity >>> target = torch.tensor([[[0, 1], [1, 0], [0, 1]], [[1, 1], [0, 0], [1, 0]]]) >>> preds = torch.tensor( ... [ ... [[0.59, 0.91], [0.91, 0.99], [0.63, 0.04]], ... [[0.38, 0.04], [0.86, 0.780], [0.45, 0.37]], ... ] ... ) >>> multilabel_specificity(preds, target, num_labels=3, multidim_average='samplewise') tensor([0.0000, 0.3333]) >>> multilabel_specificity(preds, target, num_labels=3, multidim_average='samplewise', average=None) tensor([[0., 0., 0.], [0., 0., 1.]])