class_docstr: Information Theoretic Metric Learning (ITML)
  
  `ITML` minimizes the (differential) relative entropy, aka Kullback-Leibler
  divergence, between two multivariate Gaussians subject to constraints on the
  associated Mahalanobis distance, which can be formulated into a Bregman
  optimization problem by minimizing the LogDet divergence subject to
  linear constraints. This algorithm can handle a wide variety of constraints
  and can optionally incorporate a prior on the distance function. Unlike some
  other methods, `ITML` does not rely on an eigenvalue computation or
  semi-definite programming.
  
  Read more in the :ref:`User Guide <itml>`.
  
  Parameters
  ----------
  gamma : float, optional (default=1.0)
    Value for slack variables
  
  max_iter : int, optional (default=1000)
    Maximum number of iteration of the optimization procedure.
  
  tol : float, optional (default=1e-3)
    Convergence tolerance.
  
  prior : string or numpy array, optional (default='identity')
    The Mahalanobis matrix to use as a prior. Possible options are
    'identity', 'covariance', 'random', and a numpy array of shape
    (n_features, n_features). For ITML, the prior should be strictly
    positive definite (PD).
  
    'identity'
      An identity matrix of shape (n_features, n_features).
  
    'covariance'
      The inverse covariance matrix.
  
    'random'
      The prior will be a random SPD matrix of shape
      `(n_features, n_features)`, generated using
      `sklearn.datasets.make_spd_matrix`.
  
    numpy array
      A positive definite (PD) matrix of shape
      (n_features, n_features), that will be used as such to set the
      prior.
  
  verbose : bool, optional (default=False)
    If True, prints information while learning
  
  preprocessor : array-like, shape=(n_samples, n_features) or callable
    The preprocessor to call to get tuples from indices. If array-like,
    tuples will be formed like this: X[indices].
  
  random_state : int or numpy.RandomState or None, optional (default=None)
    A pseudo random number generator object or a seed for it if int. If
    ``prior='random'``, ``random_state`` is used to set the prior.
  
  convergence_threshold : Renamed to tol. Will be deprecated in 0.7.0
  
  Attributes
  ----------
  bounds_ : `numpy.ndarray`, shape=(2,)
    Bounds on similarity, aside slack variables, s.t.
    ``d(a, b) < bounds_[0]`` for all given pairs of similar points ``a``
    and ``b``, and ``d(c, d) > bounds_[1]`` for all given pairs of
    dissimilar points ``c`` and ``d``, with ``d`` the learned distance. If
    not provided at initialization, bounds_[0] and bounds_[1] are set at
    train time to the 5th and 95th percentile of the pairwise distances among
    all points present in the input `pairs`.
  
  n_iter_ : `int`
    The number of iterations the solver has run.
  
  components_ : `numpy.ndarray`, shape=(n_features, n_features)
    The linear transformation ``L`` deduced from the learned Mahalanobis
    metric (See function `components_from_metric`.)
  
  threshold_ : `float`
    If the distance metric between two points is lower than this threshold,
    points will be classified as similar, otherwise they will be
    classified as dissimilar.
  
  Examples
  --------
  >>> from metric_learn import ITML
  >>> pairs = [[[1.2, 7.5], [1.3, 1.5]],
  >>>         [[6.4, 2.6], [6.2, 9.7]],
  >>>         [[1.3, 4.5], [3.2, 4.6]],
  >>>         [[6.2, 5.5], [5.4, 5.4]]]
  >>> y = [1, 1, -1, -1]
  >>> # in this task we want points where the first feature is close to be
  >>> # closer to each other, no matter how close the second feature is
  >>> itml = ITML()
  >>> itml.fit(pairs, y)
  
  References
  ----------
  .. [1] Jason V. Davis, et al. `Information-theoretic Metric Learning
         <http://www.prateekjain.org/publications/all_papers         /DavisKJSD07_ICML.pdf>`_. ICML 2007.
class_docstr_tok: ["Information","Theoretic","Metric","Learning","(","ITML",")","`","ITML","`","minimizes","the","(","differential",")","relative","entropy",",","aka","Kullback-Leibler","divergence",",","between","two","multivariate","Gaussians","subject","to","constraints","on","the","associated","Mahalanobis","distance",",","which","can","be","formulated","into","a","Bregman","optimization","problem","by","minimizing","the","LogDet","divergence","subject","to","linear","constraints",".","This","algorithm","can","handle","a","wide","variety","of","constraints","and","can","optionally","incorporate","a","prior","on","the","distance","function",".","Unlike","some","other","methods",",","`","ITML","`","does","not","rely","on","an","eigenvalue","computation","or","semi-definite","programming",".","Read","more","in","the",":","ref",":","`","User","Guide","<","itml",">","`",".","Parameters","--","--","--","--","--","gamma",":","float",",","optional","(","default=1.0",")","Value","for","slack","variables","max_iter",":","int",",","optional","(","default=1000",")","Maximum","number","of","iteration","of","the","optimization","procedure",".","tol",":","float",",","optional","(","default=1e-3",")","Convergence","tolerance",".","prior",":","string","or","numpy","array",",","optional","(","default='identity","'",")","The","Mahalanobis","matrix","to","use","as","a","prior",".","Possible","options","are","'identity","'",",","'covariance","'",",","'random","'",",","and","a","numpy","array","of","shape","(","n_features",",","n_features",")",".","For","ITML",",","the","prior","should","be","strictly","positive","definite","(","PD",")",".","'identity'","An","identity","matrix","of","shape","(","n_features",",","n_features",")",".","'covariance'","The","inverse","covariance","matrix",".","'random'","The","prior","will","be","a","random","SPD","matrix","of","shape","`","(","n_features",",","n_features",")","`",",","generated","using","`","sklearn.datasets.make_spd_matrix","`",".","numpy","array","A","positive","definite","(","PD",")","matrix","of","shape","(","n_features",",","n_features",")",",","that","will","be","used","as","such","to","set","the","prior",".","verbose",":","bool",",","optional","(","default=False",")","If","True",",","prints","information","while","learning","preprocessor",":","array-like",",","shape=","(","n_samples",",","n_features",")","or","callable","The","preprocessor","to","call","to","get","tuples","from","indices",".","If","array-like",",","tuples","will","be","formed","like","this",":","X","[","indices","]",".","random_state",":","int","or","numpy.RandomState","or","None",",","optional","(","default=None",")","A","pseudo","random","number","generator","object","or","a","seed","for","it","if","int",".","If","``","prior='random","'","``",",","``","random_state","``","is","used","to","set","the","prior",".","convergence_threshold",":","Renamed","to","tol",".","Will","be","deprecated","in","0.7.0","Attributes","--","--","--","--","--","bounds_",":","`","numpy.ndarray","`",",","shape=","(","2",",",")","Bounds","on","similarity",",","aside","slack","variables",",","s.t",".","``","d","(","a",",","b",")","<","bounds_","[","0","]","``","for","all","given","pairs","of","similar","points","``","a","``","and","``","b","``",",","and","``","d","(","c",",","d",")",">","bounds_","[","1","]","``","for","all","given","pairs","of","dissimilar","points","``","c","``","and","``","d","``",",","with","``","d","``","the","learned","distance",".","If","not","provided","at","initialization",",","bounds_","[","0","]","and","bounds_","[","1","]","are","set","at","train","time","to","the","5th","and","95th","percentile","of","the","pairwise","distances","among","all","points","present","in","the","input","`","pairs","`",".","n_iter_",":","`","int","`","The","number","of","iterations","the","solver","has","run",".","components_",":","`","numpy.ndarray","`",",","shape=","(","n_features",",","n_features",")","The","linear","transformation","``","L","``","deduced","from","the","learned","Mahalanobis","metric","(","See","function","`","components_from_metric","`",".",")","threshold_",":","`","float","`","If","the","distance","metric","between","two","points","is","lower","than","this","threshold",",","points","will","be","classified","as","similar",",","otherwise","they","will","be","classified","as","dissimilar",".","Examples","--","--","--","--",">",">",">","from","metric_learn","import","ITML",">",">",">","pairs","=","[","[","[","1.2",",","7.5","]",",","[","1.3",",","1.5","]","]",",",">",">",">","[","[","6.4",",","2.6","]",",","[","6.2",",","9.7","]","]",",",">",">",">","[","[","1.3",",","4.5","]",",","[","3.2",",","4.6","]","]",",",">",">",">","[","[","6.2",",","5.5","]",",","[","5.4",",","5.4","]","]","]",">",">",">","y","=","[","1",",","1",",","-1",",","-1","]",">",">",">","#","in","this","task","we","want","points","where","the","first","feature","is","close","to","be",">",">",">","#","closer","to","each","other",",","no","matter","how","close","the","second","feature","is",">",">",">","itml","=","ITML","(",")",">",">",">","itml.fit","(","pairs",",","y",")","References","--","--","--","--","--","..","[","1","]","Jason","V.","Davis",",","et","al",".","`","Information-theoretic","Metric","Learning","<","http",":","\/\/www.prateekjain.org\/publications\/all_papers","\/DavisKJSD07_ICML.pdf",">","`","_",".","ICML","2007","."]
docstr: Learn the ITML model.
  
  The threshold will be calibrated on the trainset using the parameters
  `calibration_params`.
  
  Parameters
  ----------
  pairs: array-like, shape=(n_constraints, 2, n_features) or            (n_constraints, 2)
    3D Array of pairs with each row corresponding to two points,
    or 2D array of indices of pairs if the metric learner uses a
    preprocessor.
  
  y: array-like, of shape (n_constraints,)
    Labels of constraints. Should be -1 for dissimilar pair, 1 for similar.
  
  bounds : array-like of two numbers
    Bounds on similarity, aside slack variables, s.t.
    ``d(a, b) < bounds_[0]`` for all given pairs of similar points ``a``
    and ``b``, and ``d(c, d) > bounds_[1]`` for all given pairs of
    dissimilar points ``c`` and ``d``, with ``d`` the learned distance.
    If not provided at initialization, bounds_[0] and bounds_[1] will be
    set to the 5th and 95th percentile of the pairwise distances among all
    points present in the input `pairs`.
  
  calibration_params : `dict` or `None`
    Dictionary of parameters to give to `calibrate_threshold` for the
    threshold calibration step done at the end of `fit`. If `None` is
    given, `calibrate_threshold` will use the default parameters.
  
  Returns
  -------
  self : object
    Returns the instance.
docstr_tok: ["Learn","the","ITML","model",".","The","threshold","will","be","calibrated","on","the","trainset","using","the","parameters","`","calibration_params","`",".","Parameters","--","--","--","--","--","pairs",":","array-like",",","shape=","(","n_constraints",",","2",",","n_features",")","or","(","n_constraints",",","2",")","3D","Array","of","pairs","with","each","row","corresponding","to","two","points",",","or","2D","array","of","indices","of","pairs","if","the","metric","learner","uses","a","preprocessor",".","y",":","array-like",",","of","shape","(","n_constraints",",",")","Labels","of","constraints",".","Should","be","-1","for","dissimilar","pair",",","1","for","similar",".","bounds",":","array-like","of","two","numbers","Bounds","on","similarity",",","aside","slack","variables",",","s.t",".","``","d","(","a",",","b",")","<","bounds_","[","0","]","``","for","all","given","pairs","of","similar","points","``","a","``","and","``","b","``",",","and","``","d","(","c",",","d",")",">","bounds_","[","1","]","``","for","all","given","pairs","of","dissimilar","points","``","c","``","and","``","d","``",",","with","``","d","``","the","learned","distance",".","If","not","provided","at","initialization",",","bounds_","[","0","]","and","bounds_","[","1","]","will","be","set","to","the","5th","and","95th","percentile","of","the","pairwise","distances","among","all","points","present","in","the","input","`","pairs","`",".","calibration_params",":","`","dict","`","or","`","None","`","Dictionary","of","parameters","to","give","to","`","calibrate_threshold","`","for","the","threshold","calibration","step","done","at","the","end","of","`","fit","`",".","If","`","None","`","is","given",",","`","calibrate_threshold","`","will","use","the","default","parameters",".","Returns","--","--","--","-","self",":","object","Returns","the","instance","."]
code: def fit(self, pairs, y, bounds=None, calibration_params=None):
      """Learn the ITML model.
  
      The threshold will be calibrated on the trainset using the parameters
      `calibration_params`.
  
      Parameters
      ----------
      pairs: array-like, shape=(n_constraints, 2, n_features) or \
             (n_constraints, 2)
        3D Array of pairs with each row corresponding to two points,
        or 2D array of indices of pairs if the metric learner uses a
        preprocessor.
  
      y: array-like, of shape (n_constraints,)
        Labels of constraints. Should be -1 for dissimilar pair, 1 for similar.
  
      bounds : array-like of two numbers
        Bounds on similarity, aside slack variables, s.t.
        ``d(a, b) < bounds_[0]`` for all given pairs of similar points ``a``
        and ``b``, and ``d(c, d) > bounds_[1]`` for all given pairs of
        dissimilar points ``c`` and ``d``, with ``d`` the learned distance.
        If not provided at initialization, bounds_[0] and bounds_[1] will be
        set to the 5th and 95th percentile of the pairwise distances among all
        points present in the input `pairs`.
  
      calibration_params : `dict` or `None`
        Dictionary of parameters to give to `calibrate_threshold` for the
        threshold calibration step done at the end of `fit`. If `None` is
        given, `calibrate_threshold` will use the default parameters.
  
      Returns
      -------
      self : object
        Returns the instance.
      """
      calibration_params = (
          calibration_params
          if calibration_params is not None
          else dict()
      )
      self._validate_calibration_params(**calibration_params)
      self._fit(pairs, y, bounds=bounds)
      self.calibrate_threshold(pairs, y, **calibration_params)
      return self
  
imports: import numpy
  from sklearn.metrics import pairwise_distances
  from sklearn.utils.validation import check_array
  from sklearn.base import TransformerMixin
  from .base_metric import _PairsClassifierMixin, MahalanobisMixin
  from .constraints import Constraints, wrap_pairs
  from ._util import components_from_metric, _initialize_metric_mahalanobis
  import warnings
label_desc: Use image node_id 1 for calling the ITML obj's underlying member method code with example usage: obj.fit(pairs, y, bounds, calibration_params) and returns: self