class_docstr: A selection approach based on a mixture of submodular functions.
  
  A convenient property of submodular functions is that any linear 
  combination of submodular functions is still submodular. More generally, 
  the linear combination of any number of submodular functions (assuming 
  non-negative weights) is still a submodular function. Because of this, 
  a mixture of submodular functions can be optimized using the same 
  algorithms as an individual submodular function. Mixtures can be 
  useful in situations where there are different important aspects 
  of data that are each submodular.
  
  The general form of a mixture function is 
  
  .. math::
          f(X) = \sum\limits_{i=1}^{M} \alpha_{i} g_{i}(X) 
  
  where :math:`f` indicates the mixture function, :math:`M` is the number of 
  functions in the mixture, :math:`X` is a subset, :math:`\alpha_{i}` is the 
  weight of the :math:`i`-th function and :math:`g_{i}` is the :math:`i`-th 
  function.
  
  .. note::
          There must be at least two components to the mixture, and all 
          :math:`\alpha` must be non-negative.
  
  This class can also be used to add regularizers to the selection procedure.
  If a submodular function is mixed with another submodular function that
  acts as a regularizer, such as feature based selection mixed with a
  custom function measuring some property of the selected subset.
  
  Parameters
  ----------
  n_samples : int
          The number of samples to return.
  
  functions : list
          The list of submodular functions to mix together. The submodular
          functions should be instantiated.
  
  weights : list, numpy.ndarray or None, optional
          The relative weight of each submodular function. This is the value
          that the gain from each submodular function is multiplied by before
          being added together. The default is equal weight for each function.
  
  initial_subset : list, numpy.ndarray or None, optional
          If provided, this should be a list of indices into the data matrix
          to use as the initial subset, or a group of examples that may not be
          in the provided data should beused as the initial subset. If indices, 
          the provided array should be one-dimensional. If a group of examples,
          the data should be 2 dimensional.
  
  optimizer : string or optimizers.BaseOptimizer, optional
          The optimization approach to use for the selection. Default is
          'two-stage', which makes selections using the naive greedy algorithm
          initially and then switches to the lazy greedy algorithm. Must be
          one of
  
                  'random' : randomly select elements (dummy optimizer)
                  'modular' : approximate the function using its modular upper bound
                  'naive' : the naive greedy algorithm
                  'lazy' : the lazy (or accelerated) greedy algorithm
                  'approximate-lazy' : the approximate lazy greedy algorithm
                  'two-stage' : starts with naive and switches to lazy
                  'stochastic' : the stochastic greedy algorithm
                  'sample' : randomly take a subset and perform selection on that
                  'greedi' : the GreeDi distributed algorithm
                  'bidirectional' : the bidirectional greedy algorithm
  
          Default is 'two-stage'.
  
  optimizer_kwds : dict or None
          A dictionary of arguments to pass into the optimizer object. The keys
          of this dictionary should be the names of the parameters in the optimizer
          and the values in the dictionary should be the values that these
          parameters take. Default is None.
  
  reservoir : numpy.ndarray or None
          The reservoir to use when calculating gains in the sieve greedy
          streaming optimization algorithm in the `partial_fit` method.
          Currently only used for graph-based functions. If a numpy array
          is passed in, it will be used as the reservoir. If None is passed in,
          will use reservoir sampling to collect a reservoir. Default is None.
  
  max_reservoir_size : int 
          The maximum size that the reservoir can take. If a reservoir is passed
          in, this value is set to the size of that array. Default is 1000.
  
  n_jobs : int
          The number of threads to use when performing computation in parallel.
          Currently, this parameter is exposed but does not actually do anything.
          This will be fixed soon.
  
  random_state : int or RandomState or None, optional
          The random seed to use for the random selection process. Only used
          for stochastic greedy.
  
  verbose : bool, optional
          Whether to print output during the selection process.
  
  Attributes
  ----------
  pq : PriorityQueue
          The priority queue used to implement the lazy greedy algorithm.
  
  n_samples : int
          The number of samples to select.
  
  submodular_functions : list
          A concave function for transforming feature values, often referred to as
          phi in the literature.
  
  weights : numpy.ndarray
          The weights of each submodular function.
  
  ranking : numpy.array int
          The selected samples in the order of their gain with the first number in
          the ranking corresponding to the index of the first sample that was
          selected by the greedy procedure.
  
  gains : numpy.array float
          The gain of each sample in the returned set when it was added to the
          growing subset. The first number corresponds to the gain of the first
          added sample, the second corresponds to the gain of the second added
          sample, and so forth.
class_docstr_tok: ["A","selection","approach","based","on","a","mixture","of","submodular","functions",".","A","convenient","property","of","submodular","functions","is","that","any","linear","combination","of","submodular","functions","is","still","submodular",".","More","generally",",","the","linear","combination","of","any","number","of","submodular","functions","(","assuming","non-negative","weights",")","is","still","a","submodular","function",".","Because","of","this",",","a","mixture","of","submodular","functions","can","be","optimized","using","the","same","algorithms","as","an","individual","submodular","function",".","Mixtures","can","be","useful","in","situations","where","there","are","different","important","aspects","of","data","that","are","each","submodular",".","The","general","form","of","a","mixture","function","is","..","math",":",":","f","(","X",")","=","\\sum\\limits_","{","i=1","}","^","{","M","}","\\alpha_","{","i","}","g_","{","i","}","(","X",")","where",":","math",":","`","f","`","indicates","the","mixture","function",",",":","math",":","`","M","`","is","the","number","of","functions","in","the","mixture",",",":","math",":","`","X","`","is","a","subset",",",":","math",":","`","\\alpha_","{","i","}","`","is","the","weight","of","the",":","math",":","`","i","`","-th","function","and",":","math",":","`","g_","{","i","}","`","is","the",":","math",":","`","i","`","-th","function",".","..","note",":",":","There","must","be","at","least","two","components","to","the","mixture",",","and","all",":","math",":","`","\\alpha","`","must","be","non-negative",".","This","class","can","also","be","used","to","add","regularizers","to","the","selection","procedure",".","If","a","submodular","function","is","mixed","with","another","submodular","function","that","acts","as","a","regularizer",",","such","as","feature","based","selection","mixed","with","a","custom","function","measuring","some","property","of","the","selected","subset",".","Parameters","--","--","--","--","--","n_samples",":","int","The","number","of","samples","to","return",".","functions",":","list","The","list","of","submodular","functions","to","mix","together",".","The","submodular","functions","should","be","instantiated",".","weights",":","list",",","numpy.ndarray","or","None",",","optional","The","relative","weight","of","each","submodular","function",".","This","is","the","value","that","the","gain","from","each","submodular","function","is","multiplied","by","before","being","added","together",".","The","default","is","equal","weight","for","each","function",".","initial_subset",":","list",",","numpy.ndarray","or","None",",","optional","If","provided",",","this","should","be","a","list","of","indices","into","the","data","matrix","to","use","as","the","initial","subset",",","or","a","group","of","examples","that","may","not","be","in","the","provided","data","should","beused","as","the","initial","subset",".","If","indices",",","the","provided","array","should","be","one-dimensional",".","If","a","group","of","examples",",","the","data","should","be","2","dimensional",".","optimizer",":","string","or","optimizers.BaseOptimizer",",","optional","The","optimization","approach","to","use","for","the","selection",".","Default","is","'two-stage","'",",","which","makes","selections","using","the","naive","greedy","algorithm","initially","and","then","switches","to","the","lazy","greedy","algorithm",".","Must","be","one","of","'random","'",":","randomly","select","elements","(","dummy","optimizer",")","'modular","'",":","approximate","the","function","using","its","modular","upper","bound","'naive","'",":","the","naive","greedy","algorithm","'lazy","'",":","the","lazy","(","or","accelerated",")","greedy","algorithm","'approximate-lazy","'",":","the","approximate","lazy","greedy","algorithm","'two-stage","'",":","starts","with","naive","and","switches","to","lazy","'stochastic","'",":","the","stochastic","greedy","algorithm","'sample","'",":","randomly","take","a","subset","and","perform","selection","on","that","'greedi","'",":","the","GreeDi","distributed","algorithm","'bidirectional","'",":","the","bidirectional","greedy","algorithm","Default","is","'two-stage","'",".","optimizer_kwds",":","dict","or","None","A","dictionary","of","arguments","to","pass","into","the","optimizer","object",".","The","keys","of","this","dictionary","should","be","the","names","of","the","parameters","in","the","optimizer","and","the","values","in","the","dictionary","should","be","the","values","that","these","parameters","take",".","Default","is","None",".","reservoir",":","numpy.ndarray","or","None","The","reservoir","to","use","when","calculating","gains","in","the","sieve","greedy","streaming","optimization","algorithm","in","the","`","partial_fit","`","method",".","Currently","only","used","for","graph-based","functions",".","If","a","numpy","array","is","passed","in",",","it","will","be","used","as","the","reservoir",".","If","None","is","passed","in",",","will","use","reservoir","sampling","to","collect","a","reservoir",".","Default","is","None",".","max_reservoir_size",":","int","The","maximum","size","that","the","reservoir","can","take",".","If","a","reservoir","is","passed","in",",","this","value","is","set","to","the","size","of","that","array",".","Default","is","1000.","n_jobs",":","int","The","number","of","threads","to","use","when","performing","computation","in","parallel",".","Currently",",","this","parameter","is","exposed","but","does","not","actually","do","anything",".","This","will","be","fixed","soon",".","random_state",":","int","or","RandomState","or","None",",","optional","The","random","seed","to","use","for","the","random","selection","process",".","Only","used","for","stochastic","greedy",".","verbose",":","bool",",","optional","Whether","to","print","output","during","the","selection","process",".","Attributes","--","--","--","--","--","pq",":","PriorityQueue","The","priority","queue","used","to","implement","the","lazy","greedy","algorithm",".","n_samples",":","int","The","number","of","samples","to","select",".","submodular_functions",":","list","A","concave","function","for","transforming","feature","values",",","often","referred","to","as","phi","in","the","literature",".","weights",":","numpy.ndarray","The","weights","of","each","submodular","function",".","ranking",":","numpy.array","int","The","selected","samples","in","the","order","of","their","gain","with","the","first","number","in","the","ranking","corresponding","to","the","index","of","the","first","sample","that","was","selected","by","the","greedy","procedure",".","gains",":","numpy.array","float","The","gain","of","each","sample","in","the","returned","set","when","it","was","added","to","the","growing","subset",".","The","first","number","corresponds","to","the","gain","of","the","first","added","sample",",","the","second","corresponds","to","the","gain","of","the","second","added","sample",",","and","so","forth","."]
docstr: This function will return the gain that each example would give.
  
  This function will return the gains that each example would give if
  added to the selected set. When a matrix of examples is given, a
  vector will be returned showing the gain for each example. When
  a single element is passed in, it will return a singe value.
docstr_tok: ["This","function","will","return","the","gain","that","each","example","would","give",".","This","function","will","return","the","gains","that","each","example","would","give","if","added","to","the","selected","set",".","When","a","matrix","of","examples","is","given",",","a","vector","will","be","returned","showing","the","gain","for","each","example",".","When","a","single","element","is","passed","in",",","it","will","return","a","singe","value","."]
code: def _calculate_gains(self, X, idxs=None):
      """This function will return the gain that each example would give.
  
      This function will return the gains that each example would give if
      added to the selected set. When a matrix of examples is given, a
      vector will be returned showing the gain for each example. When
      a single element is passed in, it will return a singe value."""
  
      idxs = idxs if idxs is not None else self.idxs
      gains = numpy.zeros(idxs.shape[0], dtype="float64")
  
      for i, function in enumerate(self.functions):
          gains += function._calculate_gains(X, idxs) * self.weights[i]
  
      return gains
  
file_path: apricot/apricot/functions/mixture.py
imports: import numpy
  from .base import BaseSelection
  from .base import BaseGraphSelection
  from ..utils import _calculate_pairwise_distances
  from tqdm import tqdm
label_desc: Use image node_id 4 for calling the MixtureSelection obj's underlying member method code with example usage: obj._calculate_gains(X, idxs) and returns: gains