text: """
  Functions for explaining text classifiers.
  """
  from functools import partial
  import itertools
  import json
  from math import ceil
  import re
  
  import numpy as np
  import scipy as sp
  import sklearn
  from sklearn.utils import check_random_state
  
  from . import explanation
  from . import lime_base
  
  
  class TextDomainMapper(explanation.DomainMapper):
      """Maps feature ids to words or word-positions"""
  
      def __init__(self, indexed_string):
          """Initializer.
  
          Args:
              indexed_string: lime_text.IndexedString, original string
          """
          self.indexed_string = indexed_string
  
      def map_exp_ids(self, exp, positions=False):
          """Maps ids to words or word-position strings.
  
          Args:
              exp: list of tuples [(id, weight), (id,weight)]
              positions: if True, also return word positions
  
          Returns:
              list of tuples (word, weight), or (word_positions, weight) if
              examples: ('bad', 1) or ('bad_3-6-12', 1)
          """
          if positions:
              exp = [('%s_%s' % (
                  self.indexed_string.word(x[0]),
                  '-'.join(
                      map(str,
                          self.indexed_string.string_position(x[0])))), x[1])
                     for x in exp]
          else:
              exp = [(self.indexed_string.word(x[0]), x[1]) for x in exp]
          return exp
  
      def visualize_instance_html(self, exp, label, div_name, exp_object_name,
                                  text=True, opacity=True):
          """Adds text with highlighted words to visualization.
  
          Args:
               exp: list of tuples [(id, weight), (id,weight)]
               label: label id (integer)
               div_name: name of div object to be used for rendering(in js)
               exp_object_name: name of js explanation object
               text: if False, return empty
               opacity: if True, fade colors according to weight
          """
          if not text:
              return u''
          text = (self.indexed_string.raw_string()
                  .encode('utf-8', 'xmlcharrefreplace').decode('utf-8'))
          text = re.sub(r'[<>&]', '|', text)
          exp = [(self.indexed_string.word(x[0]),
                  self.indexed_string.string_position(x[0]),
                  x[1]) for x in exp]
          all_occurrences = list(itertools.chain.from_iterable(
              [itertools.product([x[0]], x[1], [x[2]]) for x in exp]))
          all_occurrences = [(x[0], int(x[1]), x[2]) for x in all_occurrences]
          ret = '''
              %s.show_raw_text(%s, %d, %s, %s, %s);
              ''' % (exp_object_name, json.dumps(all_occurrences), label,
                     json.dumps(text), div_name, json.dumps(opacity))
          return ret
  
  
  class IndexedString(object):
      """String with various indexes."""
  
      def __init__(self, raw_string, split_expression=r'\W+', bow=True,
                   mask_string=None):
          """Initializer.
  
          Args:
              raw_string: string with raw text in it
              split_expression: Regex string or callable. If regex string, will be used with re.split.
                  If callable, the function should return a list of tokens.
              bow: if True, a word is the same everywhere in the text - i.e. we
                   will index multiple occurrences of the same word. If False,
                   order matters, so that the same word will have different ids
                   according to position.
              mask_string: If not None, replace words with this if bow=False
                  if None, default value is UNKWORDZ
          """
          self.raw = raw_string
          self.mask_string = 'UNKWORDZ' if mask_string is None else mask_string
  
          if callable(split_expression):
              tokens = split_expression(self.raw)
              self.as_list = self._segment_with_tokens(self.raw, tokens)
              tokens = set(tokens)
  
              def non_word(string):
                  return string not in tokens
  
          else:
              # with the split_expression as a non-capturing group (?:), we don't need to filter out
              # the separator character from the split results.
              splitter = re.compile(r'(%s)|$' % split_expression)
              self.as_list = [s for s in splitter.split(self.raw) if s]
              non_word = splitter.match
  
          self.as_np = np.array(self.as_list)
          self.string_start = np.hstack(
              ([0], np.cumsum([len(x) for x in self.as_np[:-1]])))
          vocab = {}
          self.inverse_vocab = []
          self.positions = []
          self.bow = bow
          non_vocab = set()
          for i, word in enumerate(self.as_np):
              if word in non_vocab:
                  continue
              if non_word(word):
                  non_vocab.add(word)
                  continue
              if bow:
                  if word not in vocab:
                      vocab[word] = len(vocab)
                      self.inverse_vocab.append(word)
                      self.positions.append([])
                  idx_word = vocab[word]
                  self.positions[idx_word].append(i)
              else:
                  self.inverse_vocab.append(word)
                  self.positions.append(i)
          if not bow:
              self.positions = np.array(self.positions)
  
      def raw_string(self):
          """Returns the original raw string"""
          return self.raw
  
      def num_words(self):
          """Returns the number of tokens in the vocabulary for this document."""
          return len(self.inverse_vocab)
  
      def word(self, id_):
          """Returns the word that corresponds to id_ (int)"""
          return self.inverse_vocab[id_]
  
      def string_position(self, id_):
          """Returns a np array with indices to id_ (int) occurrences"""
          if self.bow:
              return self.string_start[self.positions[id_]]
          else:
              return self.string_start[[self.positions[id_]]]
  
      def inverse_removing(self, words_to_remove):
          """Returns a string after removing the appropriate words.
  
          If self.bow is false, replaces word with UNKWORDZ instead of removing
          it.
  
          Args:
              words_to_remove: list of ids (ints) to remove
  
          Returns:
              original raw string with appropriate words removed.
          """
          mask = np.ones(self.as_np.shape[0], dtype='bool')
          mask[self.__get_idxs(words_to_remove)] = False
          if not self.bow:
              return ''.join(
                  [self.as_list[i] if mask[i] else self.mask_string
                   for i in range(mask.shape[0])])
          return ''.join([self.as_list[v] for v in mask.nonzero()[0]])
  
      @staticmethod
      def _segment_with_tokens(text, tokens):
          """Segment a string around the tokens created by a passed-in tokenizer"""
          list_form = []
          text_ptr = 0
          for token in tokens:
              inter_token_string = []
              while not text[text_ptr:].startswith(token):
                  inter_token_string.append(text[text_ptr])
                  text_ptr += 1
                  if text_ptr >= len(text):
                      raise ValueError("Tokenization produced tokens that do not belong in string!")
              text_ptr += len(token)
              if inter_token_string:
                  list_form.append(''.join(inter_token_string))
              list_form.append(token)
          if text_ptr < len(text):
              list_form.append(text[text_ptr:])
          return list_form
  
      def __get_idxs(self, words):
          """Returns indexes to appropriate words."""
          if self.bow:
              return list(itertools.chain.from_iterable(
                  [self.positions[z] for z in words]))
          else:
              return self.positions[words]
  
  
  class IndexedCharacters(object):
      """String with various indexes."""
  
      def __init__(self, raw_string, bow=True, mask_string=None):
          """Initializer.
  
          Args:
              raw_string: string with raw text in it
              bow: if True, a char is the same everywhere in the text - i.e. we
                   will index multiple occurrences of the same character. If False,
                   order matters, so that the same word will have different ids
                   according to position.
              mask_string: If not None, replace characters with this if bow=False
                  if None, default value is chr(0)
          """
          self.raw = raw_string
          self.as_list = list(self.raw)
          self.as_np = np.array(self.as_list)
          self.mask_string = chr(0) if mask_string is None else mask_string
          self.string_start = np.arange(len(self.raw))
          vocab = {}
          self.inverse_vocab = []
          self.positions = []
          self.bow = bow
          non_vocab = set()
          for i, char in enumerate(self.as_np):
              if char in non_vocab:
                  continue
              if bow:
                  if char not in vocab:
                      vocab[char] = len(vocab)
                      self.inverse_vocab.append(char)
                      self.positions.append([])
                  idx_char = vocab[char]
                  self.positions[idx_char].append(i)
              else:
                  self.inverse_vocab.append(char)
                  self.positions.append(i)
          if not bow:
              self.positions = np.array(self.positions)
  
      def raw_string(self):
          """Returns the original raw string"""
          return self.raw
  
      def num_words(self):
          """Returns the number of tokens in the vocabulary for this document."""
          return len(self.inverse_vocab)
  
      def word(self, id_):
          """Returns the word that corresponds to id_ (int)"""
          return self.inverse_vocab[id_]
  
      def string_position(self, id_):
          """Returns a np array with indices to id_ (int) occurrences"""
          if self.bow:
              return self.string_start[self.positions[id_]]
          else:
              return self.string_start[[self.positions[id_]]]
  
      def inverse_removing(self, words_to_remove):
          """Returns a string after removing the appropriate words.
  
          If self.bow is false, replaces word with UNKWORDZ instead of removing
          it.
  
          Args:
              words_to_remove: list of ids (ints) to remove
  
          Returns:
              original raw string with appropriate words removed.
          """
          mask = np.ones(self.as_np.shape[0], dtype='bool')
          mask[self.__get_idxs(words_to_remove)] = False
          if not self.bow:
              return ''.join(
                  [self.as_list[i] if mask[i] else self.mask_string
                   for i in range(mask.shape[0])])
          return ''.join([self.as_list[v] for v in mask.nonzero()[0]])
  
      def __get_idxs(self, words):
          """Returns indexes to appropriate words."""
          if self.bow:
              return list(itertools.chain.from_iterable(
                  [self.positions[z] for z in words]))
          else:
              return self.positions[words]
  
  
  class LimeTextExplainer(object):
      """Explains text classifiers.
         Currently, we are using an exponential kernel on cosine distance, and
         restricting explanations to words that are present in documents."""
  
      def __init__(self,
                   kernel_width=25,
                   kernel=None,
                   verbose=False,
                   class_names=None,
                   feature_selection='auto',
                   split_expression=r'\W+',
                   bow=True,
                   mask_string=None,
                   random_state=None,
                   char_level=False):
          """Init function.
  
          Args:
              kernel_width: kernel width for the exponential kernel.
              kernel: similarity kernel that takes euclidean distances and kernel
                  width as input and outputs weights in (0,1). If None, defaults to
                  an exponential kernel.
              verbose: if true, print local prediction values from linear model
              class_names: list of class names, ordered according to whatever the
                  classifier is using. If not present, class names will be '0',
                  '1', ...
              feature_selection: feature selection method. can be
                  'forward_selection', 'lasso_path', 'none' or 'auto'.
                  See function 'explain_instance_with_data' in lime_base.py for
                  details on what each of the options does.
              split_expression: Regex string or callable. If regex string, will be used with re.split.
                  If callable, the function should return a list of tokens.
              bow: if True (bag of words), will perturb input data by removing
                  all occurrences of individual words or characters.
                  Explanations will be in terms of these words. Otherwise, will
                  explain in terms of word-positions, so that a word may be
                  important the first time it appears and unimportant the second.
                  Only set to false if the classifier uses word order in some way
                  (bigrams, etc), or if you set char_level=True.
              mask_string: String used to mask tokens or characters if bow=False
                  if None, will be 'UNKWORDZ' if char_level=False, chr(0)
                  otherwise.
              random_state: an integer or numpy.RandomState that will be used to
                  generate random numbers. If None, the random state will be
                  initialized using the internal numpy seed.
              char_level: an boolean identifying that we treat each character
                  as an independent occurence in the string
          """
  
          if kernel is None:
              def kernel(d, kernel_width):
                  return np.sqrt(np.exp(-(d ** 2) / kernel_width ** 2))
  
          kernel_fn = partial(kernel, kernel_width=kernel_width)
  
          self.random_state = check_random_state(random_state)
          self.base = lime_base.LimeBase(kernel_fn, verbose,
                                         random_state=self.random_state)
          self.class_names = class_names
          self.vocabulary = None
          self.feature_selection = feature_selection
          self.bow = bow
          self.mask_string = mask_string
          self.split_expression = split_expression
          self.char_level = char_level
  
      def explain_instance(self,
                           text_instance,
                           classifier_fn,
                           labels=(1,),
                           top_labels=None,
                           num_features=10,
                           num_samples=5000,
                           distance_metric='cosine',
                           model_regressor=None,
                           max_mask=0.5):
          """Generates explanations for a prediction.
  
          First, we generate neighborhood data by randomly hiding features from
          the instance (see __data_labels_distance_mapping). We then learn
          locally weighted linear models on this neighborhood data to explain
          each of the classes in an interpretable way (see lime_base.py).
  
          Args:
              text_instance: raw text string to be explained.
              classifier_fn: classifier prediction probability function, which
                  takes a list of d strings and outputs a (d, k) numpy array with
                  prediction probabilities, where k is the number of classes.
                  For ScikitClassifiers , this is classifier.predict_proba.
              labels: iterable with labels to be explained.
              top_labels: if not None, ignore labels and produce explanations for
                  the K labels with highest prediction probabilities, where K is
                  this parameter.
              num_features: maximum number of features present in explanation
              num_samples: size of the neighborhood to learn the linear model
              distance_metric: the distance metric to use for sample weighting,
                  defaults to cosine similarity
              model_regressor: sklearn regressor to use in explanation. Defaults
              to Ridge regression in LimeBase. Must have model_regressor.coef_
              and 'sample_weight' as a parameter to model_regressor.fit()
          Returns:
              An Explanation object (see explanation.py) with the corresponding
              explanations.
          """
  
          indexed_string = (IndexedCharacters(
              text_instance, bow=self.bow, mask_string=self.mask_string)
                            if self.char_level else
                            IndexedString(text_instance, bow=self.bow,
                                          split_expression=self.split_expression,
                                          mask_string=self.mask_string))
          domain_mapper = TextDomainMapper(indexed_string)
          data, yss, distances = self.__data_labels_distances(
              indexed_string, classifier_fn, num_samples,
              distance_metric=distance_metric,max_mask=max_mask)
          if self.class_names is None:
              self.class_names = [str(x) for x in range(yss[0].shape[0])]
          ret_exp = explanation.Explanation(domain_mapper=domain_mapper,
                                            class_names=self.class_names,
                                            random_state=self.random_state)
          ret_exp.predict_proba = yss[0]
          if top_labels:
              labels = np.argsort(yss[0])[-top_labels:]
              ret_exp.top_labels = list(labels)
              ret_exp.top_labels.reverse()
          for label in labels:
              (ret_exp.intercept[label],
               ret_exp.local_exp[label],
               ret_exp.score[label],
               ret_exp.local_pred[label]) = self.base.explain_instance_with_data(
                  data, yss, distances, label, num_features,
                  model_regressor=model_regressor,
                  feature_selection=self.feature_selection)
          return ret_exp
  
      def __data_labels_distances(self,
                                  indexed_string,
                                  classifier_fn,
                                  num_samples,
                                  max_mask,
                                  distance_metric='cosine'):
          """Generates a neighborhood around a prediction.
  
          Generates neighborhood data by randomly removing words from
          the instance, and predicting with the classifier. Uses cosine distance
          to compute distances between original and perturbed instances.
          Args:
              indexed_string: document (IndexedString) to be explained,
              classifier_fn: classifier prediction probability function, which
                  takes a string and outputs prediction probabilities. For
                  ScikitClassifier, this is classifier.predict_proba.
              num_samples: size of the neighborhood to learn the linear model
              distance_metric: the distance metric to use for sample weighting,
                  defaults to cosine similarity.
  
  
          Returns:
              A tuple (data, labels, distances), where:
                  data: dense num_samples * K binary matrix, where K is the
                      number of tokens in indexed_string. The first row is the
                      original instance, and thus a row of ones.
                  labels: num_samples * L matrix, where L is the number of target
                      labels
                  distances: cosine distance between the original instance and
                      each perturbed instance (computed in the binary 'data'
                      matrix), times 100.
          """
  
          def distance_fn(x):
              return sklearn.metrics.pairwise.pairwise_distances(
                  x, x[0], metric=distance_metric).ravel() * 100
  
          doc_size = indexed_string.num_words()
          if int(ceil((doc_size + 1)*max_mask))<1:
              sample = np.zeros(shape=num_samples-1,dtype=int)
          elif int(ceil((doc_size + 1)*max_mask))==1: 
              sample = np.ones(shape=num_samples-1,dtype=int)
          else:
              sample = self.random_state.randint(1, int(ceil((doc_size + 1)*max_mask)), num_samples - 1)
          data = np.ones((num_samples, doc_size))
          data[0] = np.ones(doc_size)
          features_range = range(doc_size)
          inverse_data = [indexed_string.raw_string()]
          for i, size in enumerate(sample, start=1):
              inactive = self.random_state.choice(features_range, size,
                                                  replace=False)
              data[i, inactive] = 0
              inverse_data.append(indexed_string.inverse_removing(inactive))
          labels = classifier_fn(inverse_data)
          distances = distance_fn(sp.sparse.csr_matrix(data))
          return data, labels, distances
  