class_docstr: !
  @brief K-Means++ is an algorithm for choosing the initial centers for algorithms like K-Means or X-Means.
  @details K-Means++ algorithm guarantees an approximation ratio O(log k). Clustering results are depends on
            initial centers in case of K-Means algorithm and even in case of X-Means. This method is used to find
            out optimal initial centers.
  
  Algorithm can be divided into three steps. The first center is chosen from input data randomly with
  uniform distribution at the first step. At the second, probability to being center is calculated for each point:
  [p_{i}=rac{D(x_{i})}{\sum_{j=0}^{N}D(x_{j})}]
  where $D(x_{i})$ is a distance from point $i$ to the closest center. Using this probabilities next center
  is chosen. The last step is repeated until required amount of centers is initialized.
  
  Pyclustering implementation of the algorithm provides feature to consider several candidates on the second
  step, for example:
  
  @code
      amount_centers = 4;
      amount_candidates = 3;
      initializer = kmeans_plusplus_initializer(sample, amount_centers, amount_candidates);
  @endcode
  
  If the farthest points should be used as centers then special constant 'FARTHEST_CENTER_CANDIDATE' should be used
  for that purpose, for example:
  @code
      amount_centers = 4;
      amount_candidates = kmeans_plusplus_initializer.FARTHEST_CENTER_CANDIDATE;
      initializer = kmeans_plusplus_initializer(sample, amount_centers, amount_candidates);
  @endcode
  
  There is an example of initial centers that were calculated by the K-Means++ method:
  
  @image html kmeans_plusplus_initializer_results.png
  
  Code example where initial centers are prepared for K-Means algorithm:
  @code
      from pyclustering.cluster.center_initializer import kmeans_plusplus_initializer
      from pyclustering.cluster.kmeans import kmeans
      from pyclustering.cluster import cluster_visualizer
      from pyclustering.utils import read_sample
      from pyclustering.samples.definitions import SIMPLE_SAMPLES
  
      # Read data 'SampleSimple3' from Simple Sample collection.
      sample = read_sample(SIMPLE_SAMPLES.SAMPLE_SIMPLE3)
  
      # Calculate initial centers using K-Means++ method.
      centers = kmeans_plusplus_initializer(sample, 4, kmeans_plusplus_initializer.FARTHEST_CENTER_CANDIDATE).initialize()
  
      # Display initial centers.
      visualizer = cluster_visualizer()
      visualizer.append_cluster(sample)
      visualizer.append_cluster(centers, marker='*', markersize=10)
      visualizer.show()
  
      # Perform cluster analysis using K-Means algorithm with initial centers.
      kmeans_instance = kmeans(sample, centers)
  
      # Run clustering process and obtain result.
      kmeans_instance.process()
      clusters = kmeans_instance.get_clusters()
  @endcode
  
  Implementation based on paper @cite article::kmeans++::1.
class_docstr_tok: ["!","@","brief","K-Means++","is","an","algorithm","for","choosing","the","initial","centers","for","algorithms","like","K-Means","or","X-Means",".","@","details","K-Means++","algorithm","guarantees","an","approximation","ratio","O","(","log","k",")",".","Clustering","results","are","depends","on","initial","centers","in","case","of","K-Means","algorithm","and","even","in","case","of","X-Means",".","This","method","is","used","to","find","out","optimal","initial","centers",".","Algorithm","can","be","divided","into","three","steps",".","The","first","center","is","chosen","from","input","data","randomly","with","uniform","distribution","at","the","first","step",".","At","the","second",",","probability","to","being","center","is","calculated","for","each","point",":","[","p_","{","i","}","=","rac","{","D","(","x_","{","i","}",")","}","{","\\sum_","{","j=0","}","^","{","N","}","D","(","x_","{","j","}",")","}","]","where","$","D","(","x_","{","i","}",")","$","is","a","distance","from","point","$","i","$","to","the","closest","center",".","Using","this","probabilities","next","center","is","chosen",".","The","last","step","is","repeated","until","required","amount","of","centers","is","initialized",".","Pyclustering","implementation","of","the","algorithm","provides","feature","to","consider","several","candidates","on","the","second","step",",","for","example",":","@","code","amount_centers","=","4",";","amount_candidates","=","3",";","initializer","=","kmeans_plusplus_initializer","(","sample",",","amount_centers",",","amount_candidates",")",";","@","endcode","If","the","farthest","points","should","be","used","as","centers","then","special","constant","'FARTHEST_CENTER_CANDIDATE","'","should","be","used","for","that","purpose",",","for","example",":","@","code","amount_centers","=","4",";","amount_candidates","=","kmeans_plusplus_initializer.FARTHEST_CENTER_CANDIDATE",";","initializer","=","kmeans_plusplus_initializer","(","sample",",","amount_centers",",","amount_candidates",")",";","@","endcode","There","is","an","example","of","initial","centers","that","were","calculated","by","the","K-Means++","method",":","@","image","html","kmeans_plusplus_initializer_results.png","Code","example","where","initial","centers","are","prepared","for","K-Means","algorithm",":","@","code","from","pyclustering.cluster.center_initializer","import","kmeans_plusplus_initializer","from","pyclustering.cluster.kmeans","import","kmeans","from","pyclustering.cluster","import","cluster_visualizer","from","pyclustering.utils","import","read_sample","from","pyclustering.samples.definitions","import","SIMPLE_SAMPLES","#","Read","data","'SampleSimple3","'","from","Simple","Sample","collection",".","sample","=","read_sample","(","SIMPLE_SAMPLES.SAMPLE_SIMPLE3",")","#","Calculate","initial","centers","using","K-Means++","method",".","centers","=","kmeans_plusplus_initializer","(","sample",",","4",",","kmeans_plusplus_initializer.FARTHEST_CENTER_CANDIDATE",")",".initialize","(",")","#","Display","initial","centers",".","visualizer","=","cluster_visualizer","(",")","visualizer.append_cluster","(","sample",")","visualizer.append_cluster","(","centers",",","marker=","'","*","'",",","markersize=10",")","visualizer.show","(",")","#","Perform","cluster","analysis","using","K-Means","algorithm","with","initial","centers",".","kmeans_instance","=","kmeans","(","sample",",","centers",")","#","Run","clustering","process","and","obtain","result",".","kmeans_instance.process","(",")","clusters","=","kmeans_instance.get_clusters","(",")","@","endcode","Implementation","based","on","paper","@","cite","article",":",":kmeans++",":",":1","."]
docstr: !
  @brief Calculates initial centers using K-Means++ method.
  
  @param[in] **kwargs: Arbitrary keyword arguments (available arguments: 'return_index').
  
  <b>Keyword Args:</b><br>
      - return_index (bool): If True then returns indexes of points from input data instead of points itself.
  
  @return (list) List of initialized initial centers.
            If argument 'return_index' is False then returns list of points.
            If argument 'return_index' is True then returns list of indexes.
docstr_tok: ["!","@","brief","Calculates","initial","centers","using","K-Means++","method",".","@","param","[","in","]","*","*","kwargs",":","Arbitrary","keyword","arguments","(","available","arguments",":","'return_index","'",")",".","<","b",">","Keyword","Args",":","<","\/b",">","<","br",">","-","return_index","(","bool",")",":","If","True","then","returns","indexes","of","points","from","input","data","instead","of","points","itself",".","@","return","(","list",")","List","of","initialized","initial","centers",".","If","argument","'return_index","'","is","False","then","returns","list","of","points",".","If","argument","'return_index","'","is","True","then","returns","list","of","indexes","."]
code: def initialize(self, **kwargs):
      """!
      @brief Calculates initial centers using K-Means++ method.
  
      @param[in] **kwargs: Arbitrary keyword arguments (available arguments: 'return_index').
  
      <b>Keyword Args:</b><br>
          - return_index (bool): If True then returns indexes of points from input data instead of points itself.
  
      @return (list) List of initialized initial centers.
                If argument 'return_index' is False then returns list of points.
                If argument 'return_index' is True then returns list of indexes.
  
      """
  
      return_index = kwargs.get("return_index", None)
      if return_index is None:
          return_index = self.__data_type == "distance_matrix"
  
      if (return_index is False) and (
          self.__data_type == "distance_matrix"
      ):
          raise ValueError(
              "In case of 'distance_matrix' data type, parameter 'return_index' cannot be 'False'. "
              "Please, use 'return_index=True' in case of 'distance_matrix' data type."
          )
  
      index_point = self.__get_initial_center(True)
      centers = [index_point]
      self.__free_indexes.remove(index_point)
  
      # For each next center
      for _ in range(1, self.__amount):
          index_point = self.__get_next_center(centers)
          centers.append(index_point)
          self.__free_indexes.remove(index_point)
  
      if not return_index:
          centers = [self.__data[index] for index in centers]
  
      return centers
  
file_path: pyclustering/pyclustering/cluster/center_initializer.py
imports: import numpy
  import random
  import warnings
  from pyclustering.utils.metric import distance_metric, type_metric
label_desc: Use image node_id 8 for calling the kmeans_plusplus_initializer obj's underlying member method code with example usage: obj.initialize() and returns: centers