class_docstr: A t-SNE embedding.
  
  Please see the :ref:`parameter-guide` for more information.
  
  Parameters
  ----------
  embedding: np.ndarray
      Initial positions for each data point.
  
  affinities: Affinities
      An affinity index which can be used to compute the affinities of new
      points to the points in the existing embedding. The affinity index also
      contains the affinity matrix :math:`P` used during optimization.
  
  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.
  
  dof: float
      Degrees of freedom as described in Kobak et al. "Heavy-tailed kernels
      reveal a finer cluster structure in t-SNE visualisations", 2019.
  
  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``.A lternatively, 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","t-SNE","embedding",".","Please","see","the",":","ref",":","`","parameter-guide","`","for","more","information",".","Parameters","--","--","--","--","--","embedding",":","np.ndarray","Initial","positions","for","each","data","point",".","affinities",":","Affinities","An","affinity","index","which","can","be","used","to","compute","the","affinities","of","new","points","to","the","points","in","the","existing","embedding",".","The","affinity","index","also","contains","the","affinity","matrix",":","math",":","`","P","`","used","during","optimization",".","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",".","dof",":","float","Degrees","of","freedom","as","described","in","Kobak","et","al",".","``","Heavy-tailed","kernels","reveal","a","finer","cluster","structure","in","t-SNE","visualisations","''",",","2019.","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","``",".A","lternatively",",","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.
  
  Please see the :ref:`parameter-guide` for more information.
  
  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.
  
  dof: float
      Degrees of freedom as described in Kobak et al. "Heavy-tailed kernels
      reveal a finer cluster structure in t-SNE visualisations", 2019.
  
  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.
  
  max_grad_norm: float
      Maximum gradient norm. If the norm exceeds this value, it will be
      clipped. This is most beneficial when adding points into an existing
      embedding and the new points overlap with the reference points,
      leading to large gradients. This can make points "shoot off" from
      the embedding, causing the interpolation method to compute a very
      large grid, and leads to worse results.
  
  max_step_norm: float
      Maximum update norm. If the norm exceeds this value, it will be
      clipped. This prevents points from "shooting off" from
      the 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
  -------
  TSNEEmbedding
      An optimized 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.
  
      Please see the :ref:`parameter-guide` for more information.
  
      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.
  
      dof: float
          Degrees of freedom as described in Kobak et al. "Heavy-tailed kernels
          reveal a finer cluster structure in t-SNE visualisations", 2019.
  
      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.
  
      max_grad_norm: float
          Maximum gradient norm. If the norm exceeds this value, it will be
          clipped. This is most beneficial when adding points into an existing
          embedding and the new points overlap with the reference points,
          leading to large gradients. This can make points "shoot off" from
          the embedding, causing the interpolation method to compute a very
          large grid, and leads to worse results.
  
      max_step_norm: float
          Maximum update norm. If the norm exceeds this value, it will be
          clipped. This prevents points from "shooting off" from
          the 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
      -------
      TSNEEmbedding
          An optimized 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 = TSNEEmbedding(
              np.copy(self),
              self.affinities,
              random_state=self.random_state,
              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, P=self.affinities.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 TSNEEmbedding obj's underlying member method code with example usage: obj.optimize(n_iter, inplace, propagate_exception) and returns: embedding