class_docstr: The Minimal Targeted Counterfactual generator for tabular data.
  
  This generator looks for counterfactuals that are close to the original input
  without using gradients. First, the generator finds counterfactual examples
  from the dataset. Then, it changes features in the original input towards the
  counterfactual input until the decision boundary is found. During the search
  for a closer counterfactual, the algorithm manipulates different subsets of
  features, while keeping other features frozen. Thus, the algorithm tries to
  find the closest counterfactual that differs only in a single feature value,
  two feature values, etc., up to the selected "Maximum number of columns to
  change" configuration parameter. Only scalar and categorical features are
  changed during the search. The features of other types are always assigned the
  values of the original input.
  
  The implementation supports both classification and regression models. In case
  of a regression model, the "Regression threshold" parameter sets a decision
  boundary between the 'true' and 'false' values.
  
  The generator weakly guarantees that the result set of counterfactuals
  is minimal, i.e. for every counterfactual in the set, there exist no other
  counterfactual that differs in the same or smaller set of features and is
  closer to the original input.
class_docstr_tok: ["The","Minimal","Targeted","Counterfactual","generator","for","tabular","data",".","This","generator","looks","for","counterfactuals","that","are","close","to","the","original","input","without","using","gradients",".","First",",","the","generator","finds","counterfactual","examples","from","the","dataset",".","Then",",","it","changes","features","in","the","original","input","towards","the","counterfactual","input","until","the","decision","boundary","is","found",".","During","the","search","for","a","closer","counterfactual",",","the","algorithm","manipulates","different","subsets","of","features",",","while","keeping","other","features","frozen",".","Thus",",","the","algorithm","tries","to","find","the","closest","counterfactual","that","differs","only","in","a","single","feature","value",",","two","feature","values",",","etc.",",","up","to","the","selected","``","Maximum","number","of","columns","to","change","''","configuration","parameter",".","Only","scalar","and","categorical","features","are","changed","during","the","search",".","The","features","of","other","types","are","always","assigned","the","values","of","the","original","input",".","The","implementation","supports","both","classification","and","regression","models",".","In","case","of","a","regression","model",",","the","``","Regression","threshold","''","parameter","sets","a","decision","boundary","between","the","'true","'","and","'false","'","values",".","The","generator","weakly","guarantees","that","the","result","set","of","counterfactuals","is","minimal",",","i.e",".","for","every","counterfactual","in","the","set",",","there","exist","no","other","counterfactual","that","differs","in","the","same","or","smaller","set","of","features","and","is","closer","to","the","original","input","."]
docstr: Finds a hot-flip example for a given target example and DS example.
  
  Args:
    ref_example: target example for which the counterfactuals should be found.
    ds_example: a dataset example that should be used as a starting point for
      the search.
    features_to_consider: the list of feature keys that can be changed during
      the search.
    model: model to use for getting predictions.
    target_pred: model prediction that corresponds to `ref_example`.
    pred_key: the name of the field in model predictions that contains the
      prediction value for the counterfactual search.
    dataset: a dataset object that contains `ds_example`.
    interpolate: if True, the method tries to find a closer counterfactual
      using interpolation.
    regression_threshold: the threshold to use if `model` is a regression
      model. This parameter is ignored for classification models.
  
  Returns:
    A hot-flip counterfactual that satisfy the criteria.
docstr_tok: ["Finds","a","hot-flip","example","for","a","given","target","example","and","DS","example",".","Args",":","ref_example",":","target","example","for","which","the","counterfactuals","should","be","found",".","ds_example",":","a","dataset","example","that","should","be","used","as","a","starting","point","for","the","search",".","features_to_consider",":","the","list","of","feature","keys","that","can","be","changed","during","the","search",".","model",":","model","to","use","for","getting","predictions",".","target_pred",":","model","prediction","that","corresponds","to","`","ref_example","`",".","pred_key",":","the","name","of","the","field","in","model","predictions","that","contains","the","prediction","value","for","the","counterfactual","search",".","dataset",":","a","dataset","object","that","contains","`","ds_example","`",".","interpolate",":","if","True",",","the","method","tries","to","find","a","closer","counterfactual","using","interpolation",".","regression_threshold",":","the","threshold","to","use","if","`","model","`","is","a","regression","model",".","This","parameter","is","ignored","for","classification","models",".","Returns",":","A","hot-flip","counterfactual","that","satisfy","the","criteria","."]
code: def _find_hot_flip(
      self,
      ref_example: JsonDict,
      ds_example: JsonDict,
      features_to_consider: list[str],
      model: lit_model.Model,
      target_pred: JsonDict,
      pred_key: str,
      dataset: lit_dataset.Dataset,
      interpolate: bool,
      regression_threshold: Optional[float] = None,
  ) -> Optional[JsonDict]:
      """Finds a hot-flip example for a given target example and DS example.
  
      Args:
        ref_example: target example for which the counterfactuals should be found.
        ds_example: a dataset example that should be used as a starting point for
          the search.
        features_to_consider: the list of feature keys that can be changed during
          the search.
        model: model to use for getting predictions.
        target_pred: model prediction that corresponds to `ref_example`.
        pred_key: the name of the field in model predictions that contains the
          prediction value for the counterfactual search.
        dataset: a dataset object that contains `ds_example`.
        interpolate: if True, the method tries to find a closer counterfactual
          using interpolation.
        regression_threshold: the threshold to use if `model` is a regression
          model. This parameter is ignored for classification models.
  
      Returns:
        A hot-flip counterfactual that satisfy the criteria.
      """
      # All features other than `features_to_consider` should be assigned the
      # value of the target example.
      candidate_example = dict(ds_example)
      for field_name in ref_example:
          if (
              field_name not in features_to_consider
              and field_name in model.input_spec()
          ):
              candidate_example[field_name] = ref_example[field_name]
  
      flip, predicted_value = self._is_flip(
          model=model,
          cf_example=candidate_example,
          orig_output=target_pred,
          pred_key=pred_key,
          regression_thresh=regression_threshold,
      )
  
      if not flip:
          return None
  
      # Find closest flip by moving scalar values closer to the target.
      closest_flip = None
      if interpolate:
          closest_flip = self._find_closer_flip_using_interpolation(
              ref_example,
              candidate_example,
              target_pred,
              pred_key,
              model,
              dataset,
              regression_threshold,
          )
      # If we found a closer flip through interpolation then use it,
      # otherwise use the previously found flip.
      if closest_flip is not None:
          return closest_flip
      else:
          self._find_dataset_parent_and_set(
              model_output_spec=model.output_spec(),
              pred_key=pred_key,
              dataset_spec=dataset.spec(),
              example=candidate_example,
              predicted_value=predicted_value,
          )
          return candidate_example
  
imports: import collections
  from typing import Any, cast, Optional
  from absl import logging
  from lit_nlp.api import components
  from lit_nlp.api import dataset
  from lit_nlp.api import model
  from lit_nlp.api import types
  from lit_nlp.components import cf_utils
  from lit_nlp.lib import caching
  from lit_nlp.lib import utils
  import numpy
label_desc: Use image node_id 5 for calling the TabularMTC obj's underlying member method code with example usage: obj._find_hot_flip(ref_example, ds_example, features_to_consider, model, target_pred, pred_key, dataset, interpolate, regression_threshold) and returns: None, closest_flip, candidate_example