Metrics¶
time_interpret provides several metrics to evaluate the performance of time series attribution methods. These metrics are listed below:
Summary¶
|
Accuracy metric. |
|
Comprehensiveness metric. |
|
Cross-entropy metric. |
|
Lipschitz Max as a stability metric. |
|
Log-odds metric. |
|
Mean absolute error. |
|
Mean square error. |
|
Sufficiency metric. |
Detailed classes and methods¶
- tint.metrics.accuracy(forward_func: Callable, inputs: TensorOrTupleOfTensorsGeneric, attributions: TensorOrTupleOfTensorsGeneric, baselines: Union[None, Tensor, int, float, Tuple[Union[Tensor, int, float], ...]] = None, additional_forward_args: Any = None, target: Union[None, int, Tuple[int, ...], Tensor, List[Tuple[int, ...]], List[int]] = None, n_samples: int = 1, n_samples_batch_size: int = None, stdevs: Union[float, Tuple[float, ...]] = 0.0, draw_baseline_from_distrib: bool = False, topk: float = 0.2, mask_largest: bool = True, weight_fn: Callable[[Tuple[Tensor, ...], Tuple[Tensor, ...]], Tensor] = None, threshold: float = 0.5) float[source]¶
Accuracy metric.
This metric measures by how much the accuracy of a model drops when removing or only keeping the topk most important features. Lower is better.
- Parameters:
forward_func¶ (callable) – The forward function of the model or any modification of it.
inputs¶ (tensor or tuple of tensors) – Input for which occlusion attributions are computed. If forward_func takes a single tensor as input, a single input tensor should be provided. If forward_func takes multiple tensors as input, a tuple of the input tensors should be provided. It is assumed that for all given input tensors, dimension 0 corresponds to the number of examples (aka batch size), and if multiple input tensors are provided, the examples must be aligned appropriately.
attributions¶ (tensor or tuple of tensors) – The attributions with respect to each input feature. Attributions will always be the same size as the provided inputs, with each value providing the attribution of the corresponding input index. If a single tensor is provided as inputs, a single tensor is returned. If a tuple is provided for inputs, a tuple of corresponding sized tensors is returned.
baselines¶ (scalar, tensor, tuple of scalars or tensors, optional) –
Baselines define the starting point from which integral is computed and can be provided as:
a single tensor, if inputs is a single tensor, with exactly the same dimensions as inputs or the first dimension is one and the remaining dimensions match with inputs.
a single scalar, if inputs is a single tensor, which will be broadcasted for each input value in input tensor.
a tuple of tensors or scalars, the baseline corresponding to each tensor in the inputs’ tuple can be:
either a tensor with matching dimensions to corresponding tensor in the inputs’ tuple or the first dimension is one and the remaining dimensions match with the corresponding input tensor.
or a scalar, corresponding to a tensor in the inputs’ tuple. This scalar value is broadcasted for corresponding input tensor.
In the cases when baselines is not provided, we internally use zero scalar corresponding to each input tensor.
Default: None
additional_forward_args¶ (any, optional) – If the forward function requires additional arguments other than the inputs for which attributions should not be computed, this argument can be provided. It must be either a single additional argument of a Tensor or arbitrary (non-tuple) type or a tuple containing multiple additional arguments including tensors or any arbitrary python types. These arguments are provided to forward_func in order following the arguments in inputs. For a tensor, the first dimension of the tensor must correspond to the number of examples. It will be repeated for each of n_steps along the integrated path. For all other types, the given argument is used for all forward evaluations. Note that attributions are not computed with respect to these arguments. Default: None
target¶ (int, tuple, tensor or list, optional) –
Output indices for which gradients are computed (for classification cases, this is usually the target class). If the network returns a scalar value per example, no target index is necessary. For general 2D outputs, targets can be either:
a single integer or a tensor containing a single integer, which is applied to all input examples
a list of integers or a 1D tensor, with length matching the number of examples in inputs (dim 0). Each integer is applied as the target for the corresponding example.
For outputs with > 2 dimensions, targets can be either:
A single tuple, which contains #output_dims - 1 elements. This target index is applied to all examples.
A list of tuples with length equal to the number of examples in inputs (dim 0), and each tuple containing #output_dims - 1 elements. Each tuple is applied as the target for the corresponding example.
Default: None
n_samples¶ (int, optional) – The number of randomly generated examples per sample in the input batch. Random examples are generated by adding gaussian random noise to each sample. Default: 1
n_samples_batch_size¶ (int, optional) – The number of the n_samples that will be processed together. With the help of this parameter we can avoid out of memory situation and reduce the number of randomly generated examples per sample in each batch. Default: None if n_samples_batch_size is not provided. In this case all n_samples will be processed together.
stdevs¶ (float, or a tuple of floats optional) – The standard deviation of gaussian noise with zero mean that is added to each input in the batch. If stdevs is a single float value then that same value is used for all inputs. If it is a tuple, then it must have the same length as the inputs tuple. In this case, each stdev value in the stdevs tuple corresponds to the input with the same index in the inputs tuple. Default: 0.0
draw_baseline_from_distrib¶ (bool, optional) – Indicates whether to randomly draw baseline samples from the baselines distribution provided as an input tensor. Default: False
topk¶ – Proportion of input to be dropped. Must be between 0 and 1. Default: 0.2
mask_largest¶ – Whether to mask the topk attribution or to only keep the topk attribution. Default: True
weight_fn¶ (Callable) – Function to compute metrics weighting using original inputs and pertubed inputs. None if note provided. Default: None
threshold¶ – Threshold for the accuracy. Data higher than the threshold is considered as positive, and lower (strictly) negative. Default: 0.5
- Returns:
The accuracy metric.
- Return type:
(float)
References
Explaining Time Series Predictions with Dynamic Masks
Examples
>>> import torch as th >>> from captum.attr import Saliency >>> from tint.metrics import accuracy >>> from tint.models import MLP >>> inputs = th.rand(8, 7, 5) >>> mlp = MLP([5, 3, 1]) >>> explainer = Saliency(mlp) >>> attr = explainer.attribute(inputs, target=0) >>> acc = accuracy(mlp, inputs, attr, target=0)
- tint.metrics.comprehensiveness(forward_func: Callable, inputs: TensorOrTupleOfTensorsGeneric, attributions: TensorOrTupleOfTensorsGeneric, baselines: Union[None, Tensor, int, float, Tuple[Union[Tensor, int, float], ...]] = None, additional_forward_args: Any = None, target: Union[None, int, Tuple[int, ...], Tensor, List[Tuple[int, ...]], List[int]] = None, n_samples: int = 1, n_samples_batch_size: int = None, stdevs: Union[float, Tuple[float, ...]] = 0.0, draw_baseline_from_distrib: bool = False, topk: float = 0.2, weight_fn: Callable[[Tuple[Tensor, ...], Tuple[Tensor, ...]], Tensor] = None) float[source]¶
Comprehensiveness metric.
This comprehensiveness measures by how much the predicted class probability changes when removing the topk most important features. Higher is better.
- Parameters:
forward_func¶ (callable) – The forward function of the model or any modification of it.
inputs¶ (tensor or tuple of tensors) – Input for which occlusion attributions are computed. If forward_func takes a single tensor as input, a single input tensor should be provided. If forward_func takes multiple tensors as input, a tuple of the input tensors should be provided. It is assumed that for all given input tensors, dimension 0 corresponds to the number of examples (aka batch size), and if multiple input tensors are provided, the examples must be aligned appropriately.
attributions¶ (tensor or tuple of tensors) – The attributions with respect to each input feature. Attributions will always be the same size as the provided inputs, with each value providing the attribution of the corresponding input index. If a single tensor is provided as inputs, a single tensor is returned. If a tuple is provided for inputs, a tuple of corresponding sized tensors is returned.
baselines¶ (scalar, tensor, tuple of scalars or tensors, optional) –
Baselines define the starting point from which integral is computed and can be provided as:
a single tensor, if inputs is a single tensor, with exactly the same dimensions as inputs or the first dimension is one and the remaining dimensions match with inputs.
a single scalar, if inputs is a single tensor, which will be broadcasted for each input value in input tensor.
a tuple of tensors or scalars, the baseline corresponding to each tensor in the inputs’ tuple can be:
either a tensor with matching dimensions to corresponding tensor in the inputs’ tuple or the first dimension is one and the remaining dimensions match with the corresponding input tensor.
or a scalar, corresponding to a tensor in the inputs’ tuple. This scalar value is broadcasted for corresponding input tensor.
In the cases when baselines is not provided, we internally use zero scalar corresponding to each input tensor.
Default: None
additional_forward_args¶ (any, optional) – If the forward function requires additional arguments other than the inputs for which attributions should not be computed, this argument can be provided. It must be either a single additional argument of a Tensor or arbitrary (non-tuple) type or a tuple containing multiple additional arguments including tensors or any arbitrary python types. These arguments are provided to forward_func in order following the arguments in inputs. For a tensor, the first dimension of the tensor must correspond to the number of examples. It will be repeated for each of n_steps along the integrated path. For all other types, the given argument is used for all forward evaluations. Note that attributions are not computed with respect to these arguments. Default: None
target¶ (int, tuple, tensor or list, optional) –
Output indices for which gradients are computed (for classification cases, this is usually the target class). If the network returns a scalar value per example, no target index is necessary. For general 2D outputs, targets can be either:
a single integer or a tensor containing a single integer, which is applied to all input examples
a list of integers or a 1D tensor, with length matching the number of examples in inputs (dim 0). Each integer is applied as the target for the corresponding example.
For outputs with > 2 dimensions, targets can be either:
A single tuple, which contains #output_dims - 1 elements. This target index is applied to all examples.
A list of tuples with length equal to the number of examples in inputs (dim 0), and each tuple containing #output_dims - 1 elements. Each tuple is applied as the target for the corresponding example.
Default: None
n_samples¶ (int, optional) – The number of randomly generated examples per sample in the input batch. Random examples are generated by adding gaussian random noise to each sample. Default: 1
n_samples_batch_size¶ (int, optional) – The number of the n_samples that will be processed together. With the help of this parameter we can avoid out of memory situation and reduce the number of randomly generated examples per sample in each batch. Default: None if n_samples_batch_size is not provided. In this case all n_samples will be processed together.
stdevs¶ (float, or a tuple of floats optional) – The standard deviation of gaussian noise with zero mean that is added to each input in the batch. If stdevs is a single float value then that same value is used for all inputs. If it is a tuple, then it must have the same length as the inputs tuple. In this case, each stdev value in the stdevs tuple corresponds to the input with the same index in the inputs tuple. Default: 0.0
draw_baseline_from_distrib¶ (bool, optional) – Indicates whether to randomly draw baseline samples from the baselines distribution provided as an input tensor. Default: False
topk¶ – Proportion of input to be dropped. Must be between 0 and 1. Default: 0.2
weight_fn¶ (Callable) – Function to compute metrics weighting using original inputs and pertubed inputs. None if note provided. Default: None
- Returns:
The comprehensiveness metric.
- Return type:
(float)
References
ERASER: A Benchmark to Evaluate Rationalized NLP Models
Examples
>>> import torch as th >>> from captum.attr import Saliency >>> from tint.metrics import comprehensiveness >>> from tint.models import MLP >>> inputs = th.rand(8, 7, 5) >>> mlp = MLP([5, 3, 1]) >>> explainer = Saliency(mlp) >>> attr = explainer.attribute(inputs, target=0) >>> comp = comprehensiveness(mlp, inputs, attr, target=0)
- tint.metrics.cross_entropy(forward_func: Callable, inputs: TensorOrTupleOfTensorsGeneric, attributions: TensorOrTupleOfTensorsGeneric, baselines: Union[None, Tensor, int, float, Tuple[Union[Tensor, int, float], ...]] = None, additional_forward_args: Any = None, target: Union[None, int, Tuple[int, ...], Tensor, List[Tuple[int, ...]], List[int]] = None, n_samples: int = 1, n_samples_batch_size: int = None, stdevs: Union[float, Tuple[float, ...]] = 0.0, draw_baseline_from_distrib: bool = False, topk: float = 0.2, mask_largest: bool = True, weight_fn: Callable[[Tuple[Tensor, ...], Tuple[Tensor, ...]], Tensor] = None) float[source]¶
Cross-entropy metric.
This metric measures the cross-entropy between the outputs of the model using the original inputs and perturbed inputs by removing or only keeping the topk most important features. Higher is better.
- Parameters:
forward_func¶ (callable) – The forward function of the model or any modification of it.
inputs¶ (tensor or tuple of tensors) – Input for which occlusion attributions are computed. If forward_func takes a single tensor as input, a single input tensor should be provided. If forward_func takes multiple tensors as input, a tuple of the input tensors should be provided. It is assumed that for all given input tensors, dimension 0 corresponds to the number of examples (aka batch size), and if multiple input tensors are provided, the examples must be aligned appropriately.
attributions¶ (tensor or tuple of tensors) – The attributions with respect to each input feature. Attributions will always be the same size as the provided inputs, with each value providing the attribution of the corresponding input index. If a single tensor is provided as inputs, a single tensor is returned. If a tuple is provided for inputs, a tuple of corresponding sized tensors is returned.
baselines¶ (scalar, tensor, tuple of scalars or tensors, optional) –
Baselines define the starting point from which integral is computed and can be provided as:
a single tensor, if inputs is a single tensor, with exactly the same dimensions as inputs or the first dimension is one and the remaining dimensions match with inputs.
a single scalar, if inputs is a single tensor, which will be broadcasted for each input value in input tensor.
a tuple of tensors or scalars, the baseline corresponding to each tensor in the inputs’ tuple can be:
either a tensor with matching dimensions to corresponding tensor in the inputs’ tuple or the first dimension is one and the remaining dimensions match with the corresponding input tensor.
or a scalar, corresponding to a tensor in the inputs’ tuple. This scalar value is broadcasted for corresponding input tensor.
In the cases when baselines is not provided, we internally use zero scalar corresponding to each input tensor.
Default: None
additional_forward_args¶ (any, optional) – If the forward function requires additional arguments other than the inputs for which attributions should not be computed, this argument can be provided. It must be either a single additional argument of a Tensor or arbitrary (non-tuple) type or a tuple containing multiple additional arguments including tensors or any arbitrary python types. These arguments are provided to forward_func in order following the arguments in inputs. For a tensor, the first dimension of the tensor must correspond to the number of examples. It will be repeated for each of n_steps along the integrated path. For all other types, the given argument is used for all forward evaluations. Note that attributions are not computed with respect to these arguments. Default: None
target¶ (int, tuple, tensor or list, optional) –
Output indices for which gradients are computed (for classification cases, this is usually the target class). If the network returns a scalar value per example, no target index is necessary. For general 2D outputs, targets can be either:
a single integer or a tensor containing a single integer, which is applied to all input examples
a list of integers or a 1D tensor, with length matching the number of examples in inputs (dim 0). Each integer is applied as the target for the corresponding example.
For outputs with > 2 dimensions, targets can be either:
A single tuple, which contains #output_dims - 1 elements. This target index is applied to all examples.
A list of tuples with length equal to the number of examples in inputs (dim 0), and each tuple containing #output_dims - 1 elements. Each tuple is applied as the target for the corresponding example.
Default: None
n_samples¶ (int, optional) – The number of randomly generated examples per sample in the input batch. Random examples are generated by adding gaussian random noise to each sample. Default: 1
n_samples_batch_size¶ (int, optional) – The number of the n_samples that will be processed together. With the help of this parameter we can avoid out of memory situation and reduce the number of randomly generated examples per sample in each batch. Default: None if n_samples_batch_size is not provided. In this case all n_samples will be processed together.
stdevs¶ (float, or a tuple of floats optional) – The standard deviation of gaussian noise with zero mean that is added to each input in the batch. If stdevs is a single float value then that same value is used for all inputs. If it is a tuple, then it must have the same length as the inputs tuple. In this case, each stdev value in the stdevs tuple corresponds to the input with the same index in the inputs tuple. Default: 0.0
draw_baseline_from_distrib¶ (bool, optional) – Indicates whether to randomly draw baseline samples from the baselines distribution provided as an input tensor. Default: False
topk¶ – Proportion of input to be dropped. Must be between 0 and 1. Default: 0.2
mask_largest¶ – Whether to mask the topk attribution or to only keep the topk attribution. Default: True
weight_fn¶ (Callable) – Function to compute metrics weighting using original inputs and pertubed inputs. None if note provided. Default: None
- Returns:
The cross-entropy metric.
- Return type:
(float)
References
Explaining Time Series Predictions with Dynamic Masks
Examples
>>> import torch as th >>> from captum.attr import Saliency >>> from tint.metrics import cross_entropy >>> from tint.models import MLP >>> inputs = th.rand(8, 7, 5) >>> mlp = MLP([5, 3, 1]) >>> explainer = Saliency(mlp) >>> attr = explainer.attribute(inputs, target=0) >>> ce = cross_entropy(mlp, inputs, attr, target=0)
- tint.metrics.lipschitz_max(explanation_func: ~typing.Callable, inputs: ~captum._utils.typing.TensorOrTupleOfTensorsGeneric, perturb_func: ~typing.Callable = <function default_perturb_func>, perturb_radius: float = 0.02, n_perturb_samples: int = 10, norm_ord: str = 'fro', max_examples_per_batch: int = None, **kwargs: ~typing.Any) Tensor[source]¶
Lipschitz Max as a stability metric.
- Parameters:
explanation_func¶ (callable) – This function can be the attribute method of an attribution algorithm or any other explanation method that returns the explanations.
inputs¶ (tensor or tuple of tensors) – Input for which explanations are computed. If explanation_func takes a single tensor as input, a single input tensor should be provided. If explanation_func takes multiple tensors as input, a tuple of the input tensors should be provided. It is assumed that for all given input tensors, dimension 0 corresponds to the number of examples (aka batch size), and if multiple input tensors are provided, the examples must be aligned appropriately.
perturb_func¶ (callable) –
The perturbation function of model inputs. This function takes model inputs and optionally perturb_radius if the function takes more than one argument and returns perturbed inputs.
If there are more than one inputs passed to sensitivity function those will be passed to perturb_func as tuples in the same order as they are passed to sensitivity function.
It is important to note that for performance reasons perturb_func isn’t called for each example individually but on a batch of input examples that are repeated max_examples_per_batch / batch_size times within the batch. Default: default_perturb_func
perturb_radius¶ (float, optional) – The epsilon radius used for sampling. In the default_perturb_func it is used as the radius of the L-Infinity ball. In a general case it can serve as a radius of any L_p nom. This argument is passed to perturb_func if it takes more than one argument. Default: 0.02
n_perturb_samples¶ (int, optional) – The number of times input tensors are perturbed. Each input example in the inputs tensor is expanded n_perturb_samples times before calling perturb_func function. Default: 10
norm_ord¶ (int, float, inf, -inf, 'fro', 'nuc', optional) – The type of norm that is used to compute the norm of the sensitivity matrix which is defined as the difference between the explanation function at its input and perturbed input. Default: ‘fro’
max_examples_per_batch¶ (int, optional) – The number of maximum input examples that are processed together. In case the number of examples (input batch size * n_perturb_samples) exceeds max_examples_per_batch, they will be sliced into batches of max_examples_per_batch examples and processed in a sequential order. If max_examples_per_batch is None, all examples are processed together. max_examples_per_batch should at least be equal input batch size and at most input batch size * n_perturb_samples. Default: None
**kwargs¶ (Any, optional) – Contains a list of arguments that are passed to explanation_func explanation function which in some cases could be the attribute function of an attribution algorithm. Any additional arguments that need be passed to the explanation function should be included here. For instance, such arguments include: additional_forward_args, baselines and target.
- Returns:
- A tensor of scalar sensitivity scores per
input example. The first dimension is equal to the number of examples in the input batch and the second dimension is one. Returned sensitivities are normalized by the magnitudes of the input explanations.
- Return type:
sensitivities (tensor)
- Examples::
>>> # ImageClassifier takes a single input tensor of images Nx3x32x32, >>> # and returns an Nx10 tensor of class probabilities. >>> net = ImageClassifier() >>> saliency = Saliency(net) >>> input = torch.randn(2, 3, 32, 32, requires_grad=True) >>> # Computes sensitivity score for saliency maps of class 3 >>> sens = lipschitz_max(saliency.attribute, input, target = 3)
- tint.metrics.log_odds(forward_func: Callable, inputs: TensorOrTupleOfTensorsGeneric, attributions: TensorOrTupleOfTensorsGeneric, baselines: Union[None, Tensor, int, float, Tuple[Union[Tensor, int, float], ...]] = None, additional_forward_args: Any = None, target: Union[None, int, Tuple[int, ...], Tensor, List[Tuple[int, ...]], List[int]] = None, n_samples: int = 1, n_samples_batch_size: int = None, stdevs: Union[float, Tuple[float, ...]] = 0.0, draw_baseline_from_distrib: bool = False, topk: float = 0.2, weight_fn: Callable[[Tuple[Tensor, ...], Tuple[Tensor, ...]], Tensor] = None) float[source]¶
Log-odds metric.
This log-odds measures the average difference of the negative logarithmic probabilities on the predicted class when removing the topk most important features. Lower is better.
- Parameters:
forward_func¶ (callable) – The forward function of the model or any modification of it.
inputs¶ (tensor or tuple of tensors) – Input for which occlusion attributions are computed. If forward_func takes a single tensor as input, a single input tensor should be provided. If forward_func takes multiple tensors as input, a tuple of the input tensors should be provided. It is assumed that for all given input tensors, dimension 0 corresponds to the number of examples (aka batch size), and if multiple input tensors are provided, the examples must be aligned appropriately.
attributions¶ (tensor or tuple of tensors) – The attributions with respect to each input feature. Attributions will always be the same size as the provided inputs, with each value providing the attribution of the corresponding input index. If a single tensor is provided as inputs, a single tensor is returned. If a tuple is provided for inputs, a tuple of corresponding sized tensors is returned.
baselines¶ (scalar, tensor, tuple of scalars or tensors, optional) –
Baselines define the starting point from which integral is computed and can be provided as:
a single tensor, if inputs is a single tensor, with exactly the same dimensions as inputs or the first dimension is one and the remaining dimensions match with inputs.
a single scalar, if inputs is a single tensor, which will be broadcasted for each input value in input tensor.
a tuple of tensors or scalars, the baseline corresponding to each tensor in the inputs’ tuple can be:
either a tensor with matching dimensions to corresponding tensor in the inputs’ tuple or the first dimension is one and the remaining dimensions match with the corresponding input tensor.
or a scalar, corresponding to a tensor in the inputs’ tuple. This scalar value is broadcasted for corresponding input tensor.
In the cases when baselines is not provided, we internally use zero scalar corresponding to each input tensor.
Default: None
additional_forward_args¶ (any, optional) – If the forward function requires additional arguments other than the inputs for which attributions should not be computed, this argument can be provided. It must be either a single additional argument of a Tensor or arbitrary (non-tuple) type or a tuple containing multiple additional arguments including tensors or any arbitrary python types. These arguments are provided to forward_func in order following the arguments in inputs. For a tensor, the first dimension of the tensor must correspond to the number of examples. It will be repeated for each of n_steps along the integrated path. For all other types, the given argument is used for all forward evaluations. Note that attributions are not computed with respect to these arguments. Default: None
target¶ (int, tuple, tensor or list, optional) –
Output indices for which gradients are computed (for classification cases, this is usually the target class). If the network returns a scalar value per example, no target index is necessary. For general 2D outputs, targets can be either:
a single integer or a tensor containing a single integer, which is applied to all input examples
a list of integers or a 1D tensor, with length matching the number of examples in inputs (dim 0). Each integer is applied as the target for the corresponding example.
For outputs with > 2 dimensions, targets can be either:
A single tuple, which contains #output_dims - 1 elements. This target index is applied to all examples.
A list of tuples with length equal to the number of examples in inputs (dim 0), and each tuple containing #output_dims - 1 elements. Each tuple is applied as the target for the corresponding example.
Default: None
n_samples¶ (int, optional) – The number of randomly generated examples per sample in the input batch. Random examples are generated by adding gaussian random noise to each sample. Default: 1
n_samples_batch_size¶ (int, optional) – The number of the n_samples that will be processed together. With the help of this parameter we can avoid out of memory situation and reduce the number of randomly generated examples per sample in each batch. Default: None if n_samples_batch_size is not provided. In this case all n_samples will be processed together.
stdevs¶ (float, or a tuple of floats optional) – The standard deviation of gaussian noise with zero mean that is added to each input in the batch. If stdevs is a single float value then that same value is used for all inputs. If it is a tuple, then it must have the same length as the inputs tuple. In this case, each stdev value in the stdevs tuple corresponds to the input with the same index in the inputs tuple. Default: 0.0
draw_baseline_from_distrib¶ (bool, optional) – Indicates whether to randomly draw baseline samples from the baselines distribution provided as an input tensor. Default: False
topk¶ – Proportion of input to be dropped. Must be between 0 and 1. Default: 0.2
weight_fn¶ (Callable) – Function to compute metrics weighting using original inputs and pertubed inputs. None if note provided. Default: None
- Returns:
The log-odds metric.
- Return type:
(float)
References
Learning Important Features Through Propagating Activation Differences
Examples
>>> import torch as th >>> from captum.attr import Saliency >>> from tint.metrics import log_odds >>> from tint.models import MLP >>> inputs = th.rand(8, 7, 5) >>> mlp = MLP([5, 3, 1]) >>> explainer = Saliency(mlp) >>> attr = explainer.attribute(inputs, target=0) >>> log_odds_ = log_odds(mlp, inputs, attr, target=0)
- tint.metrics.mae(forward_func: Callable, inputs: TensorOrTupleOfTensorsGeneric, attributions: TensorOrTupleOfTensorsGeneric, baselines: Union[None, Tensor, int, float, Tuple[Union[Tensor, int, float], ...]] = None, additional_forward_args: Any = None, target: Union[None, int, Tuple[int, ...], Tensor, List[Tuple[int, ...]], List[int]] = None, n_samples: int = 1, n_samples_batch_size: int = None, stdevs: Union[float, Tuple[float, ...]] = 0.0, draw_baseline_from_distrib: bool = False, topk: float = 0.2, mask_largest: bool = True, weight_fn: Callable[[Tuple[Tensor, ...], Tuple[Tensor, ...]], Tensor] = None) float[source]¶
Mean absolute error.
This metric measures the mean absolute error between the outputs of the model using the original inputs and perturbed inputs by removing or only keeping the topk most important features. Lower is better.
- Parameters:
forward_func¶ (callable) – The forward function of the model or any modification of it.
inputs¶ (tensor or tuple of tensors) – Input for which occlusion attributions are computed. If forward_func takes a single tensor as input, a single input tensor should be provided. If forward_func takes multiple tensors as input, a tuple of the input tensors should be provided. It is assumed that for all given input tensors, dimension 0 corresponds to the number of examples (aka batch size), and if multiple input tensors are provided, the examples must be aligned appropriately.
attributions¶ (tensor or tuple of tensors) – The attributions with respect to each input feature. Attributions will always be the same size as the provided inputs, with each value providing the attribution of the corresponding input index. If a single tensor is provided as inputs, a single tensor is returned. If a tuple is provided for inputs, a tuple of corresponding sized tensors is returned.
baselines¶ (scalar, tensor, tuple of scalars or tensors, optional) –
Baselines define the starting point from which integral is computed and can be provided as:
a single tensor, if inputs is a single tensor, with exactly the same dimensions as inputs or the first dimension is one and the remaining dimensions match with inputs.
a single scalar, if inputs is a single tensor, which will be broadcasted for each input value in input tensor.
a tuple of tensors or scalars, the baseline corresponding to each tensor in the inputs’ tuple can be:
either a tensor with matching dimensions to corresponding tensor in the inputs’ tuple or the first dimension is one and the remaining dimensions match with the corresponding input tensor.
or a scalar, corresponding to a tensor in the inputs’ tuple. This scalar value is broadcasted for corresponding input tensor.
In the cases when baselines is not provided, we internally use zero scalar corresponding to each input tensor.
Default: None
additional_forward_args¶ (any, optional) – If the forward function requires additional arguments other than the inputs for which attributions should not be computed, this argument can be provided. It must be either a single additional argument of a Tensor or arbitrary (non-tuple) type or a tuple containing multiple additional arguments including tensors or any arbitrary python types. These arguments are provided to forward_func in order following the arguments in inputs. For a tensor, the first dimension of the tensor must correspond to the number of examples. It will be repeated for each of n_steps along the integrated path. For all other types, the given argument is used for all forward evaluations. Note that attributions are not computed with respect to these arguments. Default: None
target¶ (int, tuple, tensor or list, optional) –
Output indices for which gradients are computed (for classification cases, this is usually the target class). If the network returns a scalar value per example, no target index is necessary. For general 2D outputs, targets can be either:
a single integer or a tensor containing a single integer, which is applied to all input examples
a list of integers or a 1D tensor, with length matching the number of examples in inputs (dim 0). Each integer is applied as the target for the corresponding example.
For outputs with > 2 dimensions, targets can be either:
A single tuple, which contains #output_dims - 1 elements. This target index is applied to all examples.
A list of tuples with length equal to the number of examples in inputs (dim 0), and each tuple containing #output_dims - 1 elements. Each tuple is applied as the target for the corresponding example.
Default: None
n_samples¶ (int, optional) – The number of randomly generated examples per sample in the input batch. Random examples are generated by adding gaussian random noise to each sample. Default: 1
n_samples_batch_size¶ (int, optional) – The number of the n_samples that will be processed together. With the help of this parameter we can avoid out of memory situation and reduce the number of randomly generated examples per sample in each batch. Default: None if n_samples_batch_size is not provided. In this case all n_samples will be processed together.
stdevs¶ (float, or a tuple of floats optional) – The standard deviation of gaussian noise with zero mean that is added to each input in the batch. If stdevs is a single float value then that same value is used for all inputs. If it is a tuple, then it must have the same length as the inputs tuple. In this case, each stdev value in the stdevs tuple corresponds to the input with the same index in the inputs tuple. Default: 0.0
draw_baseline_from_distrib¶ (bool, optional) – Indicates whether to randomly draw baseline samples from the baselines distribution provided as an input tensor. Default: False
topk¶ – Proportion of input to be dropped. Must be between 0 and 1. Default: 0.2
mask_largest¶ – Whether to mask the topk attribution or to only keep the topk attribution. Default: True
weight_fn¶ (Callable) – Function to compute metrics weighting using original inputs and pertubed inputs. None if note provided. Default: None
- Returns:
The mean absoule error metric.
- Return type:
(float)
Examples
>>> import torch as th >>> from captum.attr import Saliency >>> from tint.metrics import mae >>> from tint.models import MLP >>> inputs = th.rand(8, 7, 5) >>> mlp = MLP([5, 3, 1]) >>> explainer = Saliency(mlp) >>> attr = explainer.attribute(inputs, target=0) >>> mae_ = mae(mlp, inputs, attr, target=0)
- tint.metrics.mse(forward_func: Callable, inputs: TensorOrTupleOfTensorsGeneric, attributions: TensorOrTupleOfTensorsGeneric, baselines: Union[None, Tensor, int, float, Tuple[Union[Tensor, int, float], ...]] = None, additional_forward_args: Any = None, target: Union[None, int, Tuple[int, ...], Tensor, List[Tuple[int, ...]], List[int]] = None, n_samples: int = 1, n_samples_batch_size: int = None, stdevs: Union[float, Tuple[float, ...]] = 0.0, draw_baseline_from_distrib: bool = False, topk: float = 0.2, mask_largest: bool = True, weight_fn: Callable[[Tuple[Tensor, ...], Tuple[Tensor, ...]], Tensor] = None) float[source]¶
Mean square error.
This metric measures the mean square error between the outputs of the model using the original inputs and perturbed inputs by removing or only keeping the topk most important features. Lower is better.
- Parameters:
forward_func¶ (callable) – The forward function of the model or any modification of it.
inputs¶ (tensor or tuple of tensors) – Input for which occlusion attributions are computed. If forward_func takes a single tensor as input, a single input tensor should be provided. If forward_func takes multiple tensors as input, a tuple of the input tensors should be provided. It is assumed that for all given input tensors, dimension 0 corresponds to the number of examples (aka batch size), and if multiple input tensors are provided, the examples must be aligned appropriately.
attributions¶ (tensor or tuple of tensors) – The attributions with respect to each input feature. Attributions will always be the same size as the provided inputs, with each value providing the attribution of the corresponding input index. If a single tensor is provided as inputs, a single tensor is returned. If a tuple is provided for inputs, a tuple of corresponding sized tensors is returned.
baselines¶ (scalar, tensor, tuple of scalars or tensors, optional) –
Baselines define the starting point from which integral is computed and can be provided as:
a single tensor, if inputs is a single tensor, with exactly the same dimensions as inputs or the first dimension is one and the remaining dimensions match with inputs.
a single scalar, if inputs is a single tensor, which will be broadcasted for each input value in input tensor.
a tuple of tensors or scalars, the baseline corresponding to each tensor in the inputs’ tuple can be:
either a tensor with matching dimensions to corresponding tensor in the inputs’ tuple or the first dimension is one and the remaining dimensions match with the corresponding input tensor.
or a scalar, corresponding to a tensor in the inputs’ tuple. This scalar value is broadcasted for corresponding input tensor.
In the cases when baselines is not provided, we internally use zero scalar corresponding to each input tensor.
Default: None
additional_forward_args¶ (any, optional) – If the forward function requires additional arguments other than the inputs for which attributions should not be computed, this argument can be provided. It must be either a single additional argument of a Tensor or arbitrary (non-tuple) type or a tuple containing multiple additional arguments including tensors or any arbitrary python types. These arguments are provided to forward_func in order following the arguments in inputs. For a tensor, the first dimension of the tensor must correspond to the number of examples. It will be repeated for each of n_steps along the integrated path. For all other types, the given argument is used for all forward evaluations. Note that attributions are not computed with respect to these arguments. Default: None
target¶ (int, tuple, tensor or list, optional) –
Output indices for which gradients are computed (for classification cases, this is usually the target class). If the network returns a scalar value per example, no target index is necessary. For general 2D outputs, targets can be either:
a single integer or a tensor containing a single integer, which is applied to all input examples
a list of integers or a 1D tensor, with length matching the number of examples in inputs (dim 0). Each integer is applied as the target for the corresponding example.
For outputs with > 2 dimensions, targets can be either:
A single tuple, which contains #output_dims - 1 elements. This target index is applied to all examples.
A list of tuples with length equal to the number of examples in inputs (dim 0), and each tuple containing #output_dims - 1 elements. Each tuple is applied as the target for the corresponding example.
Default: None
n_samples¶ (int, optional) – The number of randomly generated examples per sample in the input batch. Random examples are generated by adding gaussian random noise to each sample. Default: 1
n_samples_batch_size¶ (int, optional) – The number of the n_samples that will be processed together. With the help of this parameter we can avoid out of memory situation and reduce the number of randomly generated examples per sample in each batch. Default: None if n_samples_batch_size is not provided. In this case all n_samples will be processed together.
stdevs¶ (float, or a tuple of floats optional) – The standard deviation of gaussian noise with zero mean that is added to each input in the batch. If stdevs is a single float value then that same value is used for all inputs. If it is a tuple, then it must have the same length as the inputs tuple. In this case, each stdev value in the stdevs tuple corresponds to the input with the same index in the inputs tuple. Default: 0.0
draw_baseline_from_distrib¶ (bool, optional) – Indicates whether to randomly draw baseline samples from the baselines distribution provided as an input tensor. Default: False
topk¶ – Proportion of input to be dropped. Must be between 0 and 1. Default: 0.2
mask_largest¶ – Whether to mask the topk attribution or to only keep the topk attribution. Default: True
weight_fn¶ (Callable) – Function to compute metrics weighting using original inputs and pertubed inputs. None if note provided. Default: None
- Returns:
The mean square error metric.
- Return type:
(float)
Examples
>>> import torch as th >>> from captum.attr import Saliency >>> from tint.metrics import mse >>> from tint.models import MLP >>> inputs = th.rand(8, 7, 5) >>> mlp = MLP([5, 3, 1]) >>> explainer = Saliency(mlp) >>> attr = explainer.attribute(inputs, target=0) >>> mae_ = mse(mlp, inputs, attr, target=0)
- tint.metrics.sufficiency(forward_func: Callable, inputs: TensorOrTupleOfTensorsGeneric, attributions: TensorOrTupleOfTensorsGeneric, baselines: Union[None, Tensor, int, float, Tuple[Union[Tensor, int, float], ...]] = None, additional_forward_args: Any = None, target: Union[None, int, Tuple[int, ...], Tensor, List[Tuple[int, ...]], List[int]] = None, n_samples: int = 1, n_samples_batch_size: int = None, stdevs: Union[float, Tuple[float, ...]] = 0.0, draw_baseline_from_distrib: bool = False, topk: float = 0.2, weight_fn: Callable[[Tuple[Tensor, ...], Tuple[Tensor, ...]], Tensor] = None) float[source]¶
Sufficiency metric.
This sufficiency measures by how much the predicted class probability changes when keeping only the topk most important features. Lower is better.
- Parameters:
forward_func¶ (callable) – The forward function of the model or any modification of it.
inputs¶ (tensor or tuple of tensors) – Input for which occlusion attributions are computed. If forward_func takes a single tensor as input, a single input tensor should be provided. If forward_func takes multiple tensors as input, a tuple of the input tensors should be provided. It is assumed that for all given input tensors, dimension 0 corresponds to the number of examples (aka batch size), and if multiple input tensors are provided, the examples must be aligned appropriately.
attributions¶ (tensor or tuple of tensors) – The attributions with respect to each input feature. Attributions will always be the same size as the provided inputs, with each value providing the attribution of the corresponding input index. If a single tensor is provided as inputs, a single tensor is returned. If a tuple is provided for inputs, a tuple of corresponding sized tensors is returned.
baselines¶ (scalar, tensor, tuple of scalars or tensors, optional) –
Baselines define the starting point from which integral is computed and can be provided as:
a single tensor, if inputs is a single tensor, with exactly the same dimensions as inputs or the first dimension is one and the remaining dimensions match with inputs.
a single scalar, if inputs is a single tensor, which will be broadcasted for each input value in input tensor.
a tuple of tensors or scalars, the baseline corresponding to each tensor in the inputs’ tuple can be:
either a tensor with matching dimensions to corresponding tensor in the inputs’ tuple or the first dimension is one and the remaining dimensions match with the corresponding input tensor.
or a scalar, corresponding to a tensor in the inputs’ tuple. This scalar value is broadcasted for corresponding input tensor.
In the cases when baselines is not provided, we internally use zero scalar corresponding to each input tensor.
Default: None
additional_forward_args¶ (any, optional) – If the forward function requires additional arguments other than the inputs for which attributions should not be computed, this argument can be provided. It must be either a single additional argument of a Tensor or arbitrary (non-tuple) type or a tuple containing multiple additional arguments including tensors or any arbitrary python types. These arguments are provided to forward_func in order following the arguments in inputs. For a tensor, the first dimension of the tensor must correspond to the number of examples. It will be repeated for each of n_steps along the integrated path. For all other types, the given argument is used for all forward evaluations. Note that attributions are not computed with respect to these arguments. Default: None
target¶ (int, tuple, tensor or list, optional) –
Output indices for which gradients are computed (for classification cases, this is usually the target class). If the network returns a scalar value per example, no target index is necessary. For general 2D outputs, targets can be either:
a single integer or a tensor containing a single integer, which is applied to all input examples
a list of integers or a 1D tensor, with length matching the number of examples in inputs (dim 0). Each integer is applied as the target for the corresponding example.
For outputs with > 2 dimensions, targets can be either:
A single tuple, which contains #output_dims - 1 elements. This target index is applied to all examples.
A list of tuples with length equal to the number of examples in inputs (dim 0), and each tuple containing #output_dims - 1 elements. Each tuple is applied as the target for the corresponding example.
Default: None
n_samples¶ (int, optional) – The number of randomly generated examples per sample in the input batch. Random examples are generated by adding gaussian random noise to each sample. Default: 1
n_samples_batch_size¶ (int, optional) – The number of the n_samples that will be processed together. With the help of this parameter we can avoid out of memory situation and reduce the number of randomly generated examples per sample in each batch. Default: None if n_samples_batch_size is not provided. In this case all n_samples will be processed together.
stdevs¶ (float, or a tuple of floats optional) – The standard deviation of gaussian noise with zero mean that is added to each input in the batch. If stdevs is a single float value then that same value is used for all inputs. If it is a tuple, then it must have the same length as the inputs tuple. In this case, each stdev value in the stdevs tuple corresponds to the input with the same index in the inputs tuple. Default: 0.0
draw_baseline_from_distrib¶ (bool, optional) – Indicates whether to randomly draw baseline samples from the baselines distribution provided as an input tensor. Default: False
topk¶ – Proportion of input to be dropped. Must be between 0 and 1. Default: 0.2
weight_fn¶ (Callable) – Function to compute metrics weighting using original inputs and pertubed inputs. None if note provided. Default: None
- Returns:
The sufficiency metric.
- Return type:
(float)
References
ERASER: A Benchmark to Evaluate Rationalized NLP Models
Examples
>>> import torch as th >>> from captum.attr import Saliency >>> from tint.metrics import sufficiency >>> from tint.models import MLP >>> inputs = th.rand(8, 7, 5) >>> mlp = MLP([5, 3, 1]) >>> explainer = Saliency(mlp) >>> attr = explainer.attribute(inputs, target=0) >>> suff = sufficiency(mlp, inputs, attr, target=0)