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: Embed new points into the existing embedding.
  
  This procedure optimizes each point only with respect to the existing
  embedding i.e. it ignores any interactions between the points in ``X``
  among themselves.
  
  Please see the :ref:`parameter-guide` for more information.
  
  Parameters
  ----------
  X: np.ndarray
      The data matrix to be added to the existing embedding.
  
  perplexity: float
      Perplexity can be thought of as the continuous :math:`k` number of
      nearest neighbors, for which t-SNE will attempt to preserve
      distances. However, when transforming, we only consider neighbors in
      the existing embedding i.e. each data point is placed into the
      embedding, independently of other new data points.
  
  initialization: Union[np.ndarray, str]
      The initial point positions to be used in the embedding space. Can
      be a precomputed numpy array, ``median``, ``weighted`` or
      ``random``. In all cases, ``median`` of ``weighted`` should be
      preferred.
  
  k: int
      The number of nearest neighbors to consider when initially placing
      the point onto the embedding. This is different from ``perpelxity``
      because perplexity affects optimization while this only affects the
      initial point positions.
  
  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.
  
  early_exaggeration_iter: int
      The number of iterations to run in the *early exaggeration* phase.
  
  early_exaggeration: float
      The exaggeration factor to use during the *early exaggeration* phase.
      Typical values range from 4 to 32.
  
  n_iter: int
      The number of iterations to run in the normal optimization regime.
  
  exaggeration: float
      The exaggeration factor to use during the normal optimization phase.
      This can be used to form more densely packed clusters and is useful
      for large data sets.
  
  initial_momentum: float
      The momentum to use during the *early exaggeration* phase.
  
  final_momentum: float
      The momentum to use during the normal optimization phase.
  
  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.
  
  Returns
  -------
  PartialTSNEEmbedding
      The positions of the new points in the embedding space.
code: def transform(
      self,
      X,
      perplexity=5,
      initialization="median",
      k=25,
      learning_rate=0.1,
      early_exaggeration=4,
      early_exaggeration_iter=0,
      exaggeration=1.5,
      n_iter=250,
      initial_momentum=0.8,
      final_momentum=0.8,
      max_grad_norm=0.25,
      max_step_norm=None,
  ):
      """Embed new points into the existing embedding.
  
      This procedure optimizes each point only with respect to the existing
      embedding i.e. it ignores any interactions between the points in ``X``
      among themselves.
  
      Please see the :ref:`parameter-guide` for more information.
  
      Parameters
      ----------
      X: np.ndarray
          The data matrix to be added to the existing embedding.
  
      perplexity: float
          Perplexity can be thought of as the continuous :math:`k` number of
          nearest neighbors, for which t-SNE will attempt to preserve
          distances. However, when transforming, we only consider neighbors in
          the existing embedding i.e. each data point is placed into the
          embedding, independently of other new data points.
  
      initialization: Union[np.ndarray, str]
          The initial point positions to be used in the embedding space. Can
          be a precomputed numpy array, ``median``, ``weighted`` or
          ``random``. In all cases, ``median`` of ``weighted`` should be
          preferred.
  
      k: int
          The number of nearest neighbors to consider when initially placing
          the point onto the embedding. This is different from ``perpelxity``
          because perplexity affects optimization while this only affects the
          initial point positions.
  
      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.
  
      early_exaggeration_iter: int
          The number of iterations to run in the *early exaggeration* phase.
  
      early_exaggeration: float
          The exaggeration factor to use during the *early exaggeration* phase.
          Typical values range from 4 to 32.
  
      n_iter: int
          The number of iterations to run in the normal optimization regime.
  
      exaggeration: float
          The exaggeration factor to use during the normal optimization phase.
          This can be used to form more densely packed clusters and is useful
          for large data sets.
  
      initial_momentum: float
          The momentum to use during the *early exaggeration* phase.
  
      final_momentum: float
          The momentum to use during the normal optimization phase.
  
      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.
  
      Returns
      -------
      PartialTSNEEmbedding
          The positions of the new points in the embedding space.
  
      """
  
      # Since the standard usage of t-SNE uses perplexities, check if the
      # currently used affinity class supports either the `perplexity` or
      # `perplexities` parameters.
      affinity_signature = inspect.signature(self.affinities.to_new)
      if "perplexity" in affinity_signature.parameters:
          affinity_params = {"perplexity": perplexity}
      elif "perplexities" in affinity_signature.parameters:
          affinity_params = {"perplexities": perplexity}
      else:
          raise TypeError(
              f"`transform` currently does not support "
              f"{self.affinities.__class__.__name__} affinities. Please use "
              f"`prepare_partial` and `optimize` to add points to the embedding."
          )
  
      # Center the current embedding
      self -= (np.max(self, axis=0) + np.min(self, axis=0)) / 2
  
      embedding = self.prepare_partial(
          X, initialization=initialization, k=k, **affinity_params
      )
  
      try:
          embedding.optimize(
              n_iter=early_exaggeration_iter,
              learning_rate=learning_rate,
              exaggeration=early_exaggeration,
              momentum=initial_momentum,
              inplace=True,
              propagate_exception=True,
              max_grad_norm=max_grad_norm,
              max_step_norm=max_step_norm,
          )
          embedding.optimize(
              n_iter=n_iter,
              learning_rate=learning_rate,
              exaggeration=exaggeration,
              momentum=final_momentum,
              inplace=True,
              propagate_exception=True,
              max_grad_norm=max_grad_norm,
              max_step_norm=max_step_norm,
          )
  
      except OptimizationInterrupt as ex:
          log.info("Optimization was interrupted with callback.")
          embedding = ex.final_embedding
  
      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 3 for calling the TSNEEmbedding obj's underlying member method code with example usage: obj.transform(X, perplexity, initialization, k, learning_rate, early_exaggeration, early_exaggeration_iter, exaggeration, n_iter, initial_momentum, final_momentum, max_grad_norm, max_step_norm) and returns: embedding