class_docstr: Class for k-means clustering on manifolds.
  
  K-means algorithm using Riemannian manifolds.
  
  Parameters
  ----------
  space : Manifold
      Equipped manifold.
  n_clusters : int
      Number of clusters (k value of the k-means).
      Optional, default: 8.
  init : str or callable or array-like, shape=[n_clusters, n_features]
      How to initialize cluster centers at the beginning of the algorithm. The
      choice 'random' will select training points as initial cluster centers
      uniformly at random. The choice 'kmeans++' selects cluster centers
      heuristically to improve the convergence rate. When providing an array
      of shape ``(n_clusters, n_features)``, the cluster centers are chosen as the
      rows of that array. When providing a callable, it receives as arguments
      the argument ``X`` to :meth:`fit` and the number of cluster centers
      ``n_clusters`` and is expected to return an array as above.
      Optional, default: 'random'.
  tol : float
      Convergence factor. Convergence is achieved when the difference of mean
      distance between two steps is lower than tol.
      Optional, default: 1e-2.
  max_iter : int
      Maximum number of iterations.
      Optional, default: 100
  verbose : int
      If verbose > 0, information will be printed during learning.
      Optional, default: 0.
  
  Notes
  -----
  * Required metric methods: `dist`.
  
  Example
  -------
  Available example on the Poincaré Ball and Hypersphere manifolds
  :mod:`examples.plot_kmeans_manifolds`
class_docstr_tok: ["Class","for","k-means","clustering","on","manifolds",".","K-means","algorithm","using","Riemannian","manifolds",".","Parameters","--","--","--","--","--","space",":","Manifold","Equipped","manifold",".","n_clusters",":","int","Number","of","clusters","(","k","value","of","the","k-means",")",".","Optional",",","default",":","8.","init",":","str","or","callable","or","array-like",",","shape=","[","n_clusters",",","n_features","]","How","to","initialize","cluster","centers","at","the","beginning","of","the","algorithm",".","The","choice","'random","'","will","select","training","points","as","initial","cluster","centers","uniformly","at","random",".","The","choice","'kmeans++","'","selects","cluster","centers","heuristically","to","improve","the","convergence","rate",".","When","providing","an","array","of","shape","``","(","n_clusters",",","n_features",")","``",",","the","cluster","centers","are","chosen","as","the","rows","of","that","array",".","When","providing","a","callable",",","it","receives","as","arguments","the","argument","``","X","``","to",":","meth",":","`","fit","`","and","the","number","of","cluster","centers","``","n_clusters","``","and","is","expected","to","return","an","array","as","above",".","Optional",",","default",":","'random","'",".","tol",":","float","Convergence","factor",".","Convergence","is","achieved","when","the","difference","of","mean","distance","between","two","steps","is","lower","than","tol",".","Optional",",","default",":","1e-2",".","max_iter",":","int","Maximum","number","of","iterations",".","Optional",",","default",":","100","verbose",":","int","If","verbose",">","0",",","information","will","be","printed","during","learning",".","Optional",",","default",":","0",".","Notes","--","--","-","*","Required","metric","methods",":","`","dist","`",".","Example","--","--","--","-","Available","example","on","the","Poincar\u00e9","Ball","and","Hypersphere","manifolds",":","mod",":","`","examples.plot_kmeans_manifolds","`"]
docstr: Provide cluster centers and data labels.
  
  Alternate between computing the mean of each cluster
  and labelling data according to the new positions of the cluster centers.
  
  Parameters
  ----------
  X : array-like, shape=[n_samples, n_features]
      Training data, where n_samples is the number of samples and
      n_features is the number of features.
  
  Returns
  -------
  self : object
      Returns self.
docstr_tok: ["Provide","cluster","centers","and","data","labels",".","Alternate","between","computing","the","mean","of","each","cluster","and","labelling","data","according","to","the","new","positions","of","the","cluster","centers",".","Parameters","--","--","--","--","--","X",":","array-like",",","shape=","[","n_samples",",","n_features","]","Training","data",",","where","n_samples","is","the","number","of","samples","and","n_features","is","the","number","of","features",".","Returns","--","--","--","-","self",":","object","Returns","self","."]
code: def fit(self, X):
      """Provide cluster centers and data labels.
  
      Alternate between computing the mean of each cluster
      and labelling data according to the new positions of the cluster centers.
  
      Parameters
      ----------
      X : array-like, shape=[n_samples, n_features]
          Training data, where n_samples is the number of samples and
          n_features is the number of features.
  
      Returns
      -------
      self : object
          Returns self.
      """
      n_samples = X.shape[0]
      if self.verbose > 0:
          logging.info("Initializing...")
  
      cluster_centers = self._pick_init_cluster_centers(X)
      self.init_cluster_centers_ = gs.copy(cluster_centers)
  
      dists = [
          gs.to_ndarray(
              self.space.metric.dist(cluster_centers[i], X), 2, 1
          )
          for i in range(self.n_clusters)
      ]
      dists = gs.hstack(dists)
      self.labels_ = gs.argmin(dists, 1)
  
      for index in range(self.max_iter):
          if self.verbose > 0:
              logging.info(f"Iteration {index}...")
  
          old_cluster_centers = gs.copy(cluster_centers)
          for i in range(self.n_clusters):
              fold = X[self.labels_ == i]
  
              if len(fold) > 0:
                  self.mean_estimator.fit(fold)
                  cluster_centers[i] = self.mean_estimator.estimate_
              else:
                  cluster_centers[i] = X[randint(0, n_samples - 1)]
  
          dists = [
              gs.to_ndarray(
                  self.space.metric.dist(cluster_centers[i], X), 2, 1
              )
              for i in range(self.n_clusters)
          ]
          dists = gs.hstack(dists)
          self.labels_ = gs.argmin(dists, 1)
          dists_to_closest_cluster_center = gs.amin(dists, 1)
          self.inertia_ = gs.sum(dists_to_closest_cluster_center**2)
          cluster_centers_distances = self.space.metric.dist(
              old_cluster_centers, cluster_centers
          )
          if self.verbose > 0:
              logging.info(
                  f"Convergence criterion at the end of iteration {index} "
                  f"is {gs.mean(cluster_centers_distances)}."
              )
  
          if gs.mean(cluster_centers_distances) < self.tol:
              if self.verbose > 0:
                  logging.info(
                      f"Convergence reached after {index} iterations."
                  )
  
              break
      else:
          logging.warning(
              f"K-means maximum number of iterations {self.max_iter} reached. "
              "The mean may be inaccurate."
          )
  
      self.cluster_centers_ = cluster_centers
  
      return self
  
file_path: geomstats/geomstats/learning/kmeans.py
imports: import logging
  from random import randint
  from scipy.stats import rv_discrete
  from sklearn.base import BaseEstimator, ClusterMixin
  import geomstats.backend
  from geomstats.learning._template import TransformerMixin
  from geomstats.learning.frechet_mean import FrechetMean
label_desc: Use image node_id 3 for calling the RiemannianKMeans obj's underlying member method code with example usage: obj.fit(X) and returns: self