class_docstr: A perturbation based approach to computing attribution, involving
  replacing each input feature with a given baseline / reference, and
  computing the difference in output. By default, each scalar value within
  each input tensor is taken as a feature and replaced independently. Passing
  a feature mask, allows grouping features to be ablated together. This can
  be used in cases such as images, where an entire segment or region
  can be ablated, measuring the importance of the segment (feature group).
  Each input scalar in the group will be given the same attribution value
  equal to the change in target as a result of ablating the entire feature
  group.
  
  The forward function can either return a scalar per example or a tensor
  of a fixed sized tensor (or scalar value) for the full batch, i.e. the
  output does not grow as the batch size increase. If the output is fixed
  we consider this model to be an "aggregation" of the inputs. In the fixed
  sized output mode we require `perturbations_per_eval == 1` and the
  `feature_mask` to be either `None` or for all of them to have 1 as their
  first dimension (i.e. a feature mask requires to be applied to all inputs).
class_docstr_tok: ["A","perturbation","based","approach","to","computing","attribution",",","involving","replacing","each","input","feature","with","a","given","baseline","\/","reference",",","and","computing","the","difference","in","output",".","By","default",",","each","scalar","value","within","each","input","tensor","is","taken","as","a","feature","and","replaced","independently",".","Passing","a","feature","mask",",","allows","grouping","features","to","be","ablated","together",".","This","can","be","used","in","cases","such","as","images",",","where","an","entire","segment","or","region","can","be","ablated",",","measuring","the","importance","of","the","segment","(","feature","group",")",".","Each","input","scalar","in","the","group","will","be","given","the","same","attribution","value","equal","to","the","change","in","target","as","a","result","of","ablating","the","entire","feature","group",".","The","forward","function","can","either","return","a","scalar","per","example","or","a","tensor","of","a","fixed","sized","tensor","(","or","scalar","value",")","for","the","full","batch",",","i.e",".","the","output","does","not","grow","as","the","batch","size","increase",".","If","the","output","is","fixed","we","consider","this","model","to","be","an","``","aggregation","''","of","the","inputs",".","In","the","fixed","sized","output","mode","we","require","`","perturbations_per_eval","==","1","`","and","the","`","feature_mask","`","to","be","either","`","None","`","or","for","all","of","them","to","have","1","as","their","first","dimension","(","i.e",".","a","feature","mask","requires","to","be","applied","to","all","inputs",")","."]
docstr: Ablates given expanded_input tensor with given feature mask, feature range,
  and baselines. expanded_input shape is (`num_features`, `num_examples`, ...)
  with remaining dimensions corresponding to remaining original tensor
  dimensions and `num_features` = `end_feature` - `start_feature`.
  input_mask has same number of dimensions as original input tensor (one less
  than `expanded_input`), and can have first dimension either 1, applying same
  feature mask to all examples, or `num_examples`. baseline is expected to
  be broadcastable to match `expanded_input`.
  
  This method returns the ablated input tensor, which has the same
  dimensionality as `expanded_input` as well as the corresponding mask with
  either the same dimensionality as `expanded_input` or second dimension
  being 1. This mask contains 1s in locations which have been ablated (and
  thus counted towards ablations for that feature) and 0s otherwise.
docstr_tok: ["Ablates","given","expanded_input","tensor","with","given","feature","mask",",","feature","range",",","and","baselines",".","expanded_input","shape","is","(","`","num_features","`",",","`","num_examples","`",",","...",")","with","remaining","dimensions","corresponding","to","remaining","original","tensor","dimensions","and","`","num_features","`","=","`","end_feature","`","-","`","start_feature","`",".","input_mask","has","same","number","of","dimensions","as","original","input","tensor","(","one","less","than","`","expanded_input","`",")",",","and","can","have","first","dimension","either","1",",","applying","same","feature","mask","to","all","examples",",","or","`","num_examples","`",".","baseline","is","expected","to","be","broadcastable","to","match","`","expanded_input","`",".","This","method","returns","the","ablated","input","tensor",",","which","has","the","same","dimensionality","as","`","expanded_input","`","as","well","as","the","corresponding","mask","with","either","the","same","dimensionality","as","`","expanded_input","`","or","second","dimension","being","1",".","This","mask","contains","1s","in","locations","which","have","been","ablated","(","and","thus","counted","towards","ablations","for","that","feature",")","and","0s","otherwise","."]
code: def _construct_ablated_input(
      self,
      expanded_input,
      input_mask,
      baseline,
      start_feature,
      end_feature,
      **kwargs,
  ):
      r"""
      Ablates given expanded_input tensor with given feature mask, feature range,
      and baselines. expanded_input shape is (`num_features`, `num_examples`, ...)
      with remaining dimensions corresponding to remaining original tensor
      dimensions and `num_features` = `end_feature` - `start_feature`.
      input_mask has same number of dimensions as original input tensor (one less
      than `expanded_input`), and can have first dimension either 1, applying same
      feature mask to all examples, or `num_examples`. baseline is expected to
      be broadcastable to match `expanded_input`.
  
      This method returns the ablated input tensor, which has the same
      dimensionality as `expanded_input` as well as the corresponding mask with
      either the same dimensionality as `expanded_input` or second dimension
      being 1. This mask contains 1s in locations which have been ablated (and
      thus counted towards ablations for that feature) and 0s otherwise.
      """
      current_mask = torch.stack(
          [input_mask == j for j in range(start_feature, end_feature)],
          dim=0,
      ).long()
      ablated_tensor = (
          expanded_input * (1 - current_mask).to(expanded_input.dtype)
      ) + (baseline * current_mask.to(expanded_input.dtype))
      return ablated_tensor, current_mask
  
file_path: captum/captum/attr/_core/feature_ablation.py
imports: import math
  from typing import Any, Callable, cast, Tuple, Union
  import torch
  from captum._utils.common import _expand_additional_forward_args, _expand_target, _format_additional_forward_args, _format_feature_mask, _format_output, _is_tuple, _run_forward
  from captum._utils.progress import progress
  from captum._utils.typing import BaselineType, TargetType, TensorOrTupleOfTensorsGeneric
  from captum.attr._utils.attribution import PerturbationAttribution
  from captum.attr._utils.common import _format_input_baseline
  from captum.log import log_usage
  from torch import dtype, Tensor
label_desc: Use image node_id 4 for calling the FeatureAblation obj's underlying member method code with example usage: obj._construct_ablated_input(expanded_input, input_mask, baseline, start_feature, end_feature) and returns: ablated_tensor,  current_mask