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 Creates K-Means++ center initializer instance.
  
  @param[in] data (array_like): Points where each point is represented by list of coordinates.
  @param[in] amount_centers (uint): Amount of centers that should be initialized.
  @param[in] amount_candidates (uint): Amount of candidates that is considered as a center, if the farthest points
              (with the highest probability) should be considered as centers then special constant should be used
              'FARTHEST_CENTER_CANDIDATE'. By default the amount of candidates is 3.
  @param[in] **kwargs: Arbitrary keyword arguments (available arguments: `random_state`, `data_type`, `metric`).
  
  <b>Keyword Args:</b><br>
      - random_state (int): Seed for random state (by default is `None`, current system time is used).
      - data_type (str): Data type of input sample `data` (`points`, `distance_matrix`).
      - metric (distance_metric): Metric that is used for distance calculation between two points.
  
  @see FARTHEST_CENTER_CANDIDATE
docstr_tok: ["!","@","brief","Creates","K-Means++","center","initializer","instance",".","@","param","[","in","]","data","(","array_like",")",":","Points","where","each","point","is","represented","by","list","of","coordinates",".","@","param","[","in","]","amount_centers","(","uint",")",":","Amount","of","centers","that","should","be","initialized",".","@","param","[","in","]","amount_candidates","(","uint",")",":","Amount","of","candidates","that","is","considered","as","a","center",",","if","the","farthest","points","(","with","the","highest","probability",")","should","be","considered","as","centers","then","special","constant","should","be","used","'FARTHEST_CENTER_CANDIDATE","'",".","By","default","the","amount","of","candidates","is","3",".","@","param","[","in","]","*","*","kwargs",":","Arbitrary","keyword","arguments","(","available","arguments",":","`","random_state","`",",","`","data_type","`",",","`","metric","`",")",".","<","b",">","Keyword","Args",":","<","\/b",">","<","br",">","-","random_state","(","int",")",":","Seed","for","random","state","(","by","default","is","`","None","`",",","current","system","time","is","used",")",".","-","data_type","(","str",")",":","Data","type","of","input","sample","`","data","`","(","`","points","`",",","`","distance_matrix","`",")",".","-","metric","(","distance_metric",")",":","Metric","that","is","used","for","distance","calculation","between","two","points",".","@","see","FARTHEST_CENTER_CANDIDATE"]
code: def __init__(
      self, data, amount_centers, amount_candidates=None, **kwargs
  ):
      """!
      @brief Creates K-Means++ center initializer instance.
  
      @param[in] data (array_like): Points where each point is represented by list of coordinates.
      @param[in] amount_centers (uint): Amount of centers that should be initialized.
      @param[in] amount_candidates (uint): Amount of candidates that is considered as a center, if the farthest points
                  (with the highest probability) should be considered as centers then special constant should be used
                  'FARTHEST_CENTER_CANDIDATE'. By default the amount of candidates is 3.
      @param[in] **kwargs: Arbitrary keyword arguments (available arguments: `random_state`, `data_type`, `metric`).
  
      <b>Keyword Args:</b><br>
          - random_state (int): Seed for random state (by default is `None`, current system time is used).
          - data_type (str): Data type of input sample `data` (`points`, `distance_matrix`).
          - metric (distance_metric): Metric that is used for distance calculation between two points.
  
      @see FARTHEST_CENTER_CANDIDATE
  
      """
  
      self.__data = numpy.array(data)
      self.__amount = amount_centers
      self.__free_indexes = set(range(len(self.__data)))
  
      if amount_candidates is None:
          self.__candidates = 3
          if self.__candidates > len(self.__data):
              self.__candidates = len(self.__data)
      else:
          self.__candidates = amount_candidates
  
      random_seed = kwargs.get("random_state", None)
      numpy.random.seed(random_seed)
      random.seed(random_seed)
  
      self.__metric = kwargs.get(
          "metric", distance_metric(type_metric.EUCLIDEAN_SQUARE)
      )
      self.__data_type = kwargs.get("data_type", "points")
  
      self.__metric.enable_numpy_usage()
      self.__check_parameters()
  
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 1 to create a new kmeans_plusplus_initializer object  with example: obj = kmeans_plusplus_initializer(data, amount_centers, amount_candidates)