class_docstr: A partial t-SNE embedding.
  
  A partial embedding is created when we take an existing
  :class:`TSNEEmbedding` and embed new samples into the embedding space. It
  differs from the typical embedding in that it is not possible to add new
  samples to a partial embedding and would generally be a bad idea.
  
  Please see the :ref:`parameter-guide` for more information.
  
  Parameters
  ----------
  embedding: np.ndarray
      Initial positions for each data point.
  
  reference_embedding: TSNEEmbedding
      The embedding into which the new samples are to be added.
  
  P : array_like
      An :math:`N \times M` affinity matrix containing the affinities from
      each new data point :math:`n` to each data point in the existing
      embedding :math:`m`.
  
  learning_rate: Union[str, float]
      The learning rate for t-SNE optimization. When ``learning_rate="auto"``
      the appropriate learning rate is selected according to N / exaggeration
      as determined in Belkina et al. (2019), Nature Communications. Note that
      this will result in a different learning rate during the early
      exaggeration phase and afterwards. This should *not* be used when 
      adding samples into existing embeddings, where the learning rate often
      needs to be much lower to obtain convergence.
  
  exaggeration: float
      The exaggeration factor is used to increase the attractive forces of
      nearby points, producing more compact clusters.
  
  momentum: float
      Momentum accounts for gradient directions from previous iterations,
      resulting in faster convergence.
  
  negative_gradient_method: str
      Specifies the negative gradient approximation method to use. For smaller
      data sets, the Barnes-Hut approximation is appropriate and can be set
      using one of the following aliases: ``bh``, ``BH`` or ``barnes-hut``.
      For larger data sets, the FFT accelerated interpolation method is more
      appropriate and can be set using one of the following aliases: ``fft``,
      ``FFT`` or ``ìnterpolation``. Alternatively, you can use ``auto`` to
      approximately select the faster method.
  
  theta: float
      This is the trade-off parameter between speed and accuracy of the tree
      approximation method. Typical values range from 0.2 to 0.8. The value 0
      indicates that no approximation is to be made and produces exact results
      also producing longer runtime.
  
  n_interpolation_points: int
      Only used when ``negative_gradient_method="fft"`` or its other aliases.
      The number of interpolation points to use within each grid cell for
      interpolation based t-SNE. It is highly recommended leaving this value
      at the default 3.
  
  min_num_intervals: int
      Only used when ``negative_gradient_method="fft"`` or its other aliases.
      The minimum number of grid cells to use, regardless of the
      ``ints_in_interval`` parameter. Higher values provide more accurate
      gradient estimations.
  
  random_state: Union[int, RandomState]
      The random state parameter follows the convention used in scikit-learn.
      If the value is an int, random_state is the seed used by the random
      number generator. If the value is a RandomState instance, then it will
      be used as the random number generator. If the value is None, the random
      number generator is the RandomState instance used by `np.random`.
  
  n_jobs: int
      The number of threads to use while running t-SNE. This follows the
      scikit-learn convention, ``-1`` meaning all processors, ``-2`` meaning
      all but one, etc.
  
  callbacks: Callable[[int, float, np.ndarray] -> bool]
      Callbacks, which will be run every ``callbacks_every_iters`` iterations.
  
  callbacks_every_iters: int
      How many iterations should pass between each time the callbacks are
      invoked.
  
  optimizer: gradient_descent
      Optionally, an existing optimizer can be used for optimization. This is
      useful for keeping momentum gains between different calls to
      :func:`optimize`.
  
  Attributes
  ----------
  kl_divergence: float
      The KL divergence or error of the embedding.
class_docstr_tok: ["A","partial","t-SNE","embedding",".","A","partial","embedding","is","created","when","we","take","an","existing",":","class",":","`","TSNEEmbedding","`","and","embed","new","samples","into","the","embedding","space",".","It","differs","from","the","typical","embedding","in","that","it","is","not","possible","to","add","new","samples","to","a","partial","embedding","and","would","generally","be","a","bad","idea",".","Please","see","the",":","ref",":","`","parameter-guide","`","for","more","information",".","Parameters","--","--","--","--","--","embedding",":","np.ndarray","Initial","positions","for","each","data","point",".","reference_embedding",":","TSNEEmbedding","The","embedding","into","which","the","new","samples","are","to","be","added",".","P",":","array_like","An",":","math",":","`","N","\\times","M","`","affinity","matrix","containing","the","affinities","from","each","new","data","point",":","math",":","`","n","`","to","each","data","point","in","the","existing","embedding",":","math",":","`","m","`",".","learning_rate",":","Union","[","str",",","float","]","The","learning","rate","for","t-SNE","optimization",".","When","``","learning_rate=","''","auto","''","``","the","appropriate","learning","rate","is","selected","according","to","N","\/","exaggeration","as","determined","in","Belkina","et","al",".","(","2019",")",",","Nature","Communications",".","Note","that","this","will","result","in","a","different","learning","rate","during","the","early","exaggeration","phase","and","afterwards",".","This","should","*","not","*","be","used","when","adding","samples","into","existing","embeddings",",","where","the","learning","rate","often","needs","to","be","much","lower","to","obtain","convergence",".","exaggeration",":","float","The","exaggeration","factor","is","used","to","increase","the","attractive","forces","of","nearby","points",",","producing","more","compact","clusters",".","momentum",":","float","Momentum","accounts","for","gradient","directions","from","previous","iterations",",","resulting","in","faster","convergence",".","negative_gradient_method",":","str","Specifies","the","negative","gradient","approximation","method","to","use",".","For","smaller","data","sets",",","the","Barnes-Hut","approximation","is","appropriate","and","can","be","set","using","one","of","the","following","aliases",":","``","bh","``",",","``","BH","``","or","``","barnes-hut","``",".","For","larger","data","sets",",","the","FFT","accelerated","interpolation","method","is","more","appropriate","and","can","be","set","using","one","of","the","following","aliases",":","``","fft","``",",","``","FFT","``","or","``","\u00ecnterpolation","``",".","Alternatively",",","you","can","use","``","auto","``","to","approximately","select","the","faster","method",".","theta",":","float","This","is","the","trade-off","parameter","between","speed","and","accuracy","of","the","tree","approximation","method",".","Typical","values","range","from","0.2","to","0.8",".","The","value","0","indicates","that","no","approximation","is","to","be","made","and","produces","exact","results","also","producing","longer","runtime",".","n_interpolation_points",":","int","Only","used","when","``","negative_gradient_method=","''","fft","''","``","or","its","other","aliases",".","The","number","of","interpolation","points","to","use","within","each","grid","cell","for","interpolation","based","t-SNE",".","It","is","highly","recommended","leaving","this","value","at","the","default","3.","min_num_intervals",":","int","Only","used","when","``","negative_gradient_method=","''","fft","''","``","or","its","other","aliases",".","The","minimum","number","of","grid","cells","to","use",",","regardless","of","the","``","ints_in_interval","``","parameter",".","Higher","values","provide","more","accurate","gradient","estimations",".","random_state",":","Union","[","int",",","RandomState","]","The","random","state","parameter","follows","the","convention","used","in","scikit-learn",".","If","the","value","is","an","int",",","random_state","is","the","seed","used","by","the","random","number","generator",".","If","the","value","is","a","RandomState","instance",",","then","it","will","be","used","as","the","random","number","generator",".","If","the","value","is","None",",","the","random","number","generator","is","the","RandomState","instance","used","by","`","np.random","`",".","n_jobs",":","int","The","number","of","threads","to","use","while","running","t-SNE",".","This","follows","the","scikit-learn","convention",",","``","-1","``","meaning","all","processors",",","``","-2","``","meaning","all","but","one",",","etc",".","callbacks",":","Callable","[","[","int",",","float",",","np.ndarray","]","-",">","bool","]","Callbacks",",","which","will","be","run","every","``","callbacks_every_iters","``","iterations",".","callbacks_every_iters",":","int","How","many","iterations","should","pass","between","each","time","the","callbacks","are","invoked",".","optimizer",":","gradient_descent","Optionally",",","an","existing","optimizer","can","be","used","for","optimization",".","This","is","useful","for","keeping","momentum","gains","between","different","calls","to",":","func",":","`","optimize","`",".","Attributes","--","--","--","--","--","kl_divergence",":","float","The","KL","divergence","or","error","of","the","embedding","."]
docstr: Run optmization on the embedding for a given number of steps.
  
  Parameters
  ----------
  n_iter: int
      The number of optimization iterations.
  
  learning_rate: Union[str, float]
      The learning rate for t-SNE optimization. When
      ``learning_rate="auto"`` the appropriate learning rate is selected
      according to N / exaggeration as determined in Belkina et al.
      (2019), Nature Communications. Note that this will result in a
      different learning rate during the early exaggeration phase and
      afterwards. This should *not* be used when adding samples into
      existing embeddings, where the learning rate often needs to be much
      lower to obtain convergence.
  
  exaggeration: float
      The exaggeration factor is used to increase the attractive forces of
      nearby points, producing more compact clusters.
  
  momentum: float
      Momentum accounts for gradient directions from previous iterations,
      resulting in faster convergence.
  
  negative_gradient_method: str
      Specifies the negative gradient approximation method to use. For
      smaller data sets, the Barnes-Hut approximation is appropriate and
      can be set using one of the following aliases: ``bh``, ``BH`` or
      ``barnes-hut``. For larger data sets, the FFT accelerated
      interpolation method is more appropriate and can be set using one of
      the following aliases: ``fft``, ``FFT`` or ``ìnterpolation``.
      Alternatively, you can use ``auto`` to approximately select the
      faster method.
  
  theta: float
      This is the trade-off parameter between speed and accuracy of the
      tree approximation method. Typical values range from 0.2 to 0.8. The
      value 0 indicates that no approximation is to be made and produces
      exact results also producing longer runtime.
  
  n_interpolation_points: int
      Only used when ``negative_gradient_method="fft"`` or its other
      aliases. The number of interpolation points to use within each grid
      cell for interpolation based t-SNE. It is highly recommended leaving
      this value at the default 3.
  
  min_num_intervals: int
      Only used when ``negative_gradient_method="fft"`` or its other
      aliases. The minimum number of grid cells to use, regardless of the
      ``ints_in_interval`` parameter. Higher values provide more accurate
      gradient estimations.
  
  inplace: bool
      Whether or not to create a copy of the embedding or to perform
      updates inplace.
  
  propagate_exception: bool
      The optimization process can be interrupted using callbacks. This
      flag indicates whether we should propagate that exception or to
      simply stop optimization and return the resulting embedding.
  
  n_jobs: int
      The number of threads to use while running t-SNE. This follows the
      scikit-learn convention, ``-1`` meaning all processors, ``-2``
      meaning all but one, etc.
  
  callbacks: Callable[[int, float, np.ndarray] -> bool]
      Callbacks, which will be run every ``callbacks_every_iters``
      iterations.
  
  callbacks_every_iters: int
      How many iterations should pass between each time the callbacks are
      invoked.
  
  Returns
  -------
  PartialTSNEEmbedding
      An optimized partial t-SNE embedding.
  
  Raises
  ------
  OptimizationInterrupt
      If a callback stops the optimization and the ``propagate_exception``
      flag is set, then an exception is raised.
code: def optimize(
      self,
      n_iter,
      inplace=False,
      propagate_exception=False,
      **gradient_descent_params,
  ):
      """Run optmization on the embedding for a given number of steps.
  
      Parameters
      ----------
      n_iter: int
          The number of optimization iterations.
  
      learning_rate: Union[str, float]
          The learning rate for t-SNE optimization. When
          ``learning_rate="auto"`` the appropriate learning rate is selected
          according to N / exaggeration as determined in Belkina et al.
          (2019), Nature Communications. Note that this will result in a
          different learning rate during the early exaggeration phase and
          afterwards. This should *not* be used when adding samples into
          existing embeddings, where the learning rate often needs to be much
          lower to obtain convergence.
  
      exaggeration: float
          The exaggeration factor is used to increase the attractive forces of
          nearby points, producing more compact clusters.
  
      momentum: float
          Momentum accounts for gradient directions from previous iterations,
          resulting in faster convergence.
  
      negative_gradient_method: str
          Specifies the negative gradient approximation method to use. For
          smaller data sets, the Barnes-Hut approximation is appropriate and
          can be set using one of the following aliases: ``bh``, ``BH`` or
          ``barnes-hut``. For larger data sets, the FFT accelerated
          interpolation method is more appropriate and can be set using one of
          the following aliases: ``fft``, ``FFT`` or ``ìnterpolation``.
          Alternatively, you can use ``auto`` to approximately select the
          faster method.
  
      theta: float
          This is the trade-off parameter between speed and accuracy of the
          tree approximation method. Typical values range from 0.2 to 0.8. The
          value 0 indicates that no approximation is to be made and produces
          exact results also producing longer runtime.
  
      n_interpolation_points: int
          Only used when ``negative_gradient_method="fft"`` or its other
          aliases. The number of interpolation points to use within each grid
          cell for interpolation based t-SNE. It is highly recommended leaving
          this value at the default 3.
  
      min_num_intervals: int
          Only used when ``negative_gradient_method="fft"`` or its other
          aliases. The minimum number of grid cells to use, regardless of the
          ``ints_in_interval`` parameter. Higher values provide more accurate
          gradient estimations.
  
      inplace: bool
          Whether or not to create a copy of the embedding or to perform
          updates inplace.
  
      propagate_exception: bool
          The optimization process can be interrupted using callbacks. This
          flag indicates whether we should propagate that exception or to
          simply stop optimization and return the resulting embedding.
  
      n_jobs: int
          The number of threads to use while running t-SNE. This follows the
          scikit-learn convention, ``-1`` meaning all processors, ``-2``
          meaning all but one, etc.
  
      callbacks: Callable[[int, float, np.ndarray] -> bool]
          Callbacks, which will be run every ``callbacks_every_iters``
          iterations.
  
      callbacks_every_iters: int
          How many iterations should pass between each time the callbacks are
          invoked.
  
      Returns
      -------
      PartialTSNEEmbedding
          An optimized partial t-SNE embedding.
  
      Raises
      ------
      OptimizationInterrupt
          If a callback stops the optimization and the ``propagate_exception``
          flag is set, then an exception is raised.
  
      """
      # Typically we want to return a new embedding and keep the old one intact
      if inplace:
          embedding = self
      else:
          embedding = PartialTSNEEmbedding(
              np.copy(self),
              self.reference_embedding,
              self.P,
              optimizer=self.optimizer.copy(),
              **self.gradient_descent_params,
          )
  
      # If optimization parameters were passed to this funciton, prefer those
      # over the defaults specified in the TSNE object
      optim_params = dict(self.gradient_descent_params)
      optim_params.update(gradient_descent_params)
      optim_params["n_iter"] = n_iter
      _handle_nice_params(embedding, optim_params)
  
      try:
          # Run gradient descent with the embedding optimizer so gains are
          # properly updated and kept
          error, embedding = embedding.optimizer(
              embedding=embedding,
              reference_embedding=self.reference_embedding,
              P=self.P,
              **optim_params,
          )
  
      except OptimizationInterrupt as ex:
          log.info("Optimization was interrupted with callback.")
          if propagate_exception:
              raise ex
          error, embedding = ex.error, ex.final_embedding
  
      embedding.kl_divergence = error
  
      return embedding
  
imports: import inspect
  import logging
  import multiprocessing
  from collections.abc import Iterable
  from types import SimpleNamespace
  from time import time
  import numpy
  from sklearn.base import BaseEstimator
  from openTSNE import _tsne
  from openTSNE import initialization
  from openTSNE.affinity import Affinities, MultiscaleMixture
  from openTSNE.quad_tree import QuadTree
  from openTSNE import utils
label_desc: Use image node_id 2 for calling the PartialTSNEEmbedding obj's underlying member method code with example usage: obj.optimize(n_iter, inplace, propagate_exception) and returns: embedding