![\"Data-points](\"https://raw.githubusercontent.com/joshlk/k-means-constrained/master/etc/execution_time.png\")
\n\n\n
\n"""k-means-constrained"""\n\n# Authors: Josh Levy-Kramer <josh@levykramer.co.uk>\n# Gael Varoquaux <gael.varoquaux@normalesup.org>\n# Thomas Rueckstiess <ruecksti@in.tum.de>\n# James Bergstra <james.bergstra@umontreal.ca>\n# Jan Schlueter <scikit-learn@jan-schlueter.de>\n# Nelle Varoquaux\n# Peter Prettenhofer <peter.prettenhofer@gmail.com>\n# Olivier Grisel <olivier.grisel@ensta.org>\n# Mathieu Blondel <mathieu@mblondel.org>\n# Robert Layton <robertlayton@gmail.com>\n# License: BSD 3 clause\n\nimport warnings\nimport numpy as np\nimport scipy.sparse as sp\nfrom .sklearn_import.metrics.pairwise import euclidean_distances\nfrom .sklearn_import.utils.extmath import row_norms, squared_norm, cartesian\nfrom .sklearn_import.utils.validation import check_array, check_random_state, as_float_array, check_is_fitted\nfrom joblib import Parallel\nfrom joblib import delayed\n\n# Internal scikit learn methods imported into this project\nfrom k_means_constrained.sklearn_import.cluster._k_means import _centers_dense, _centers_sparse\nfrom k_means_constrained.sklearn_import.cluster.k_means_ import _validate_center_shape, _tolerance, KMeans, \\\n _init_centroids\n\nfrom k_means_constrained.mincostflow_vectorized import SimpleMinCostFlowVectorized\n\n\ndef k_means_constrained(X, n_clusters, size_min=None, size_max=None, init='k-means++',\n n_init=10, max_iter=300, verbose=False,\n tol=1e-4, random_state=None, copy_x=True, n_jobs=1,\n return_n_iter=False):\n """K-Means clustering with minimum and maximum cluster size constraints.\n\n Read more in the :ref:`User Guide <k_means>`.\n\n Parameters\n ----------\n X : array-like, shape (n_samples, n_features)\n The observations to cluster.\n\n size_min : int, optional, default: None\n Constrain the label assignment so that each cluster has a minimum\n size of size_min. If None, no constrains will be applied\n\n size_max : int, optional, default: None\n Constrain the label assignment so that each cluster has a maximum\n size of size_max. If None, no constrains will be applied\n\n n_clusters : int\n The number of clusters to form as well as the number of\n centroids to generate.\n\n init : {'k-means++', 'random', or ndarray, or a callable}, optional\n Method for initialization, default to 'k-means++':\n\n 'k-means++' : selects initial cluster centers for k-mean\n clustering in a smart way to speed up convergence. See section\n Notes in k_init for more details.\n\n 'random': generate k centroids from a Gaussian with mean and\n variance estimated from the data.\n\n If an ndarray is passed, it should be of shape (n_clusters, n_features)\n and gives the initial centers.\n\n If a callable is passed, it should take arguments X, k and\n and a random state and return an initialization.\n\n n_init : int, optional, default: 10\n Number of time the k-means algorithm will be run with different\n centroid seeds. The final results will be the best output of\n n_init consecutive runs in terms of inertia.\n\n max_iter : int, optional, default 300\n Maximum number of iterations of the k-means algorithm to run.\n\n verbose : boolean, optional\n Verbosity mode.\n\n tol : float, optional\n Relative tolerance with regards to Frobenius norm of the difference\n in the cluster centers of two consecutive iterations to declare\n convergence.\n\n random_state : int, RandomState instance or None, optional, default: None\n If int, random_state is the seed used by the random number generator;\n If RandomState instance, random_state is the random number generator;\n If None, the random number generator is the RandomState instance used\n by `np.random`.\n\n copy_x : boolean, optional\n When pre-computing distances it is more numerically accurate to center\n the data first. If copy_x is True, then the original data is not\n modified. If False, the original data is modified, and put back before\n the function returns, but small numerical differences may be introduced\n by subtracting and then adding the data mean.\n\n n_jobs : int\n The number of jobs to use for the computation. This works by computing\n each of the n_init runs in parallel.\n\n If -1 all CPUs are used. If 1 is given, no parallel computing code is\n used at all, which is useful for debugging. For n_jobs below -1,\n (n_cpus + 1 + n_jobs) are used. Thus for n_jobs = -2, all CPUs but one\n are used.\n\n return_n_iter : bool, optional\n Whether or not to return the number of iterations.\n\n Returns\n -------\n centroid : float ndarray with shape (k, n_features)\n Centroids found at the last iteration of k-means.\n\n label : integer ndarray with shape (n_samples,)\n label[i] is the code or index of the centroid the\n i'th observation is closest to.\n\n inertia : float\n The final value of the inertia criterion (sum of squared distances to\n the closest centroid for all observations in the training set).\n\n best_n_iter : int\n Number of iterations corresponding to the best results.\n Returned only if `return_n_iter` is set to True.\n\n """\n if sp.issparse(X):\n raise NotImplementedError("Not implemented for sparse X")\n\n if n_init <= 0:\n raise ValueError("Invalid number of initializations."\n " n_init=%d must be bigger than zero." % n_init)\n random_state = check_random_state(random_state)\n\n if max_iter <= 0:\n raise ValueError('Number of iterations should be a positive number,'\n ' got %d instead' % max_iter)\n\n X = as_float_array(X, copy=copy_x)\n tol = _tolerance(X, tol)\n\n # Validate init array\n if hasattr(init, '__array__'):\n init = check_array(init, dtype=X.dtype.type, copy=True)\n _validate_center_shape(X, n_clusters, init)\n\n if n_init != 1:\n warnings.warn(\n 'Explicit initial center position passed: '\n 'performing only one init in k-means instead of n_init=%d'\n % n_init, RuntimeWarning, stacklevel=2)\n n_init = 1\n\n # subtract of mean of x for more accurate distance computations\n if not sp.issparse(X):\n X_mean = X.mean(axis=0)\n # The copy was already done above\n X -= X_mean\n\n if hasattr(init, '__array__'):\n init -= X_mean\n\n # precompute squared norms of data points\n x_squared_norms = row_norms(X, squared=True)\n\n best_labels, best_inertia, best_centers = None, None, None\n\n if n_jobs == 1:\n # For a single thread, less memory is needed if we just store one set\n # of the best results (as opposed to one set per run per thread).\n for it in range(n_init):\n # run a k-means once\n labels, inertia, centers, n_iter_ = kmeans_constrained_single(\n X, n_clusters,\n size_min=size_min, size_max=size_max,\n max_iter=max_iter, init=init, verbose=verbose, tol=tol,\n x_squared_norms=x_squared_norms, random_state=random_state)\n # determine if these results are the best so far\n if best_inertia is None or inertia < best_inertia:\n best_labels = labels.copy()\n best_centers = centers.copy()\n best_inertia = inertia\n best_n_iter = n_iter_\n else:\n # parallelisation of k-means runs\n seeds = random_state.randint(np.iinfo(np.int32).max, size=n_init)\n results = Parallel(n_jobs=n_jobs, verbose=0)(\n delayed(kmeans_constrained_single)(X, n_clusters,\n size_min=size_min, size_max=size_max,\n max_iter=max_iter, init=init,\n verbose=verbose, tol=tol,\n x_squared_norms=x_squared_norms,\n # Change seed to ensure variety\n random_state=seed)\n for seed in seeds)\n # Get results with the lowest inertia\n labels, inertia, centers, n_iters = zip(*results)\n best = np.argmin(inertia)\n best_labels = labels[best]\n best_inertia = inertia[best]\n best_centers = centers[best]\n best_n_iter = n_iters[best]\n\n if not sp.issparse(X):\n if not copy_x:\n X += X_mean\n best_centers += X_mean\n\n if return_n_iter:\n return best_centers, best_labels, best_inertia, best_n_iter\n else:\n return best_centers, best_labels, best_inertia\n\n\ndef kmeans_constrained_single(X, n_clusters, size_min=None, size_max=None,\n max_iter=300, init='k-means++',\n verbose=False, x_squared_norms=None,\n random_state=None, tol=1e-4):\n """A single run of k-means constrained, assumes preparation completed prior.\n\n Parameters\n ----------\n X : array-like of floats, shape (n_samples, n_features)\n The observations to cluster.\n\n size_min : int, optional, default: None\n Constrain the label assignment so that each cluster has a minimum\n size of size_min. If None, no constrains will be applied\n\n size_max : int, optional, default: None\n Constrain the label assignment so that each cluster has a maximum\n size of size_max. If None, no constrains will be applied\n\n n_clusters : int\n The number of clusters to form as well as the number of\n centroids to generate.\n\n max_iter : int, optional, default 300\n Maximum number of iterations of the k-means algorithm to run.\n\n init : {'k-means++', 'random', or ndarray, or a callable}, optional\n Method for initialization, default to 'k-means++':\n\n 'k-means++' : selects initial cluster centers for k-mean\n clustering in a smart way to speed up convergence. See section\n Notes in k_init for more details.\n\n 'random': generate k centroids from a Gaussian with mean and\n variance estimated from the data.\n\n If an ndarray is passed, it should be of shape (k, p) and gives\n the initial centers.\n\n If a callable is passed, it should take arguments X, k and\n and a random state and return an initialization.\n\n tol : float, optional\n Relative tolerance with regards to Frobenius norm of the difference\n in the cluster centers of two consecutive iterations to declare\n convergence.\n\n verbose : boolean, optional\n Verbosity mode\n\n x_squared_norms : array\n Precomputed x_squared_norms.\n\n random_state : int, RandomState instance or None, optional, default: None\n If int, random_state is the seed used by the random number generator;\n If RandomState instance, random_state is the random number generator;\n If None, the random number generator is the RandomState instance used\n by `np.random`.\n\n Returns\n -------\n centroid : float ndarray with shape (k, n_features)\n Centroids found at the last iteration of k-means.\n\n label : integer ndarray with shape (n_samples,)\n label[i] is the code or index of the centroid the\n i'th observation is closest to.\n\n inertia : float\n The final value of the inertia criterion (sum of squared distances to\n the closest centroid for all observations in the training set).\n\n n_iter : int\n Number of iterations run.\n """\n if sp.issparse(X):\n raise NotImplementedError("Not implemented for sparse X")\n\n random_state = check_random_state(random_state)\n n_samples = X.shape[0]\n\n best_labels, best_inertia, best_centers = None, None, None\n # init\n centers = _init_centroids(X, n_clusters, init, random_state=random_state, x_squared_norms=x_squared_norms)\n if verbose:\n print("Initialization complete")\n\n # Allocate memory to store the distances for each sample to its\n # closer center for reallocation in case of ties\n distances = np.zeros(shape=(n_samples,), dtype=X.dtype)\n\n # Determine min and max sizes if non given\n if size_min is None:\n size_min = 0\n if size_max is None:\n size_max = n_samples # Number of data points\n\n # Check size min and max\n if not ((size_min >= 0) and (size_min <= n_samples)\n and (size_max >= 0) and (size_max <= n_samples)):\n raise ValueError("size_min and size_max must be a positive number smaller "\n "than the number of data points or `None`")\n if size_max < size_min:\n raise ValueError("size_max must be larger than size_min")\n if size_min * n_clusters > n_samples:\n raise ValueError("The product of size_min and n_clusters cannot exceed the number of samples (X)")\n if size_max * n_clusters < n_samples:\n raise ValueError("The product of size_max and n_clusters must be larger than or equal the number of samples (X)")\n\n # iterations\n for i in range(max_iter):\n centers_old = centers.copy()\n # labels assignment is also called the E-step of EM\n labels, inertia = \\\n _labels_constrained(X, centers, size_min, size_max, distances=distances)\n\n # computation of the means is also called the M-step of EM\n if sp.issparse(X):\n centers = _centers_sparse(X, labels, n_clusters, distances)\n else:\n centers = _centers_dense(X, labels, n_clusters, distances)\n\n if verbose:\n print("Iteration %2d, inertia %.3f" % (i, inertia))\n\n if best_inertia is None or inertia < best_inertia:\n best_labels = labels.copy()\n best_centers = centers.copy()\n best_inertia = inertia\n\n center_shift_total = squared_norm(centers_old - centers)\n if center_shift_total <= tol:\n if verbose:\n print("Converged at iteration %d: "\n "center shift %e within tolerance %e"\n % (i, center_shift_total, tol))\n break\n\n if center_shift_total > 0:\n # rerun E-step in case of non-convergence so that predicted labels\n # match cluster centers\n best_labels, best_inertia = \\\n _labels_constrained(X, centers, size_min, size_max, distances=distances)\n\n return best_labels, best_inertia, best_centers, i + 1\n\n\ndef _labels_constrained(X, centers, size_min, size_max, distances):\n """Compute labels using the min and max cluster size constraint\n\n This will overwrite the 'distances' array in-place.\n\n Parameters\n ----------\n X : numpy array, shape (n_sample, n_features)\n Input data.\n\n size_min : int\n Minimum size for each cluster\n\n size_max : int\n Maximum size for each cluster\n\n centers : numpy array, shape (n_clusters, n_features)\n Cluster centers which data is assigned to.\n\n distances : numpy array, shape (n_samples,)\n Pre-allocated array in which distances are stored.\n\n Returns\n -------\n labels : numpy array, dtype=np.int, shape (n_samples,)\n Indices of clusters that samples are assigned to.\n\n inertia : float\n Sum of squared distances of samples to their closest cluster center.\n\n """\n C = centers\n\n # Distances to each centre C. (the `distances` parameter is the distance to the closest centre)\n # K-mean original uses squared distances but this equivalent for constrained k-means\n D = euclidean_distances(X, C, squared=False)\n\n edges, costs, capacities, supplies, n_C, n_X = minimum_cost_flow_problem_graph(X, C, D, size_min, size_max)\n labels = solve_min_cost_flow_graph(edges, costs, capacities, supplies, n_C, n_X)\n\n # cython k-means M step code assumes int32 inputs\n labels = labels.astype(np.int32)\n\n # Change distances in-place\n distances[:] = D[np.arange(D.shape[0]), labels] ** 2 # Square for M step of EM\n inertia = distances.sum()\n\n return labels, inertia\n\n\ndef minimum_cost_flow_problem_graph(X, C, D, size_min, size_max):\n # Setup minimum cost flow formulation graph\n # Vertices indexes:\n # X-nodes: [0, n(x)-1], C-nodes: [n(X), n(X)+n(C)-1], C-dummy nodes:[n(X)+n(C), n(X)+2*n(C)-1],\n # Artificial node: [n(X)+2*n(C), n(X)+2*n(C)+1-1]\n\n # Create indices of nodes\n n_X = X.shape[0]\n n_C = C.shape[0]\n X_ix = np.arange(n_X)\n C_dummy_ix = np.arange(X_ix[-1] + 1, X_ix[-1] + 1 + n_C)\n C_ix = np.arange(C_dummy_ix[-1] + 1, C_dummy_ix[-1] + 1 + n_C)\n art_ix = C_ix[-1] + 1\n\n # Edges\n edges_X_C_dummy = cartesian([X_ix, C_dummy_ix]) # All X's connect to all C dummy nodes (C')\n edges_C_dummy_C = np.stack([C_dummy_ix, C_ix], axis=1) # Each C' connects to a corresponding C (centroid)\n edges_C_art = np.stack([C_ix, art_ix * np.ones(n_C)], axis=1) # All C connect to artificial node\n\n edges = np.concatenate([edges_X_C_dummy, edges_C_dummy_C, edges_C_art])\n\n # Costs\n costs_X_C_dummy = D.reshape(D.size)\n costs = np.concatenate([costs_X_C_dummy, np.zeros(edges.shape[0] - len(costs_X_C_dummy))])\n\n # Capacities - can set for max-k\n capacities_C_dummy_C = size_max * np.ones(n_C)\n cap_non = n_X # The total supply and therefore wont restrict flow\n capacities = np.concatenate([\n np.ones(edges_X_C_dummy.shape[0]),\n capacities_C_dummy_C,\n cap_non * np.ones(n_C)\n ])\n\n # Sources and sinks\n supplies_X = np.ones(n_X)\n supplies_C = -1 * size_min * np.ones(n_C) # Demand node\n supplies_art = -1 * (n_X - n_C * size_min) # Demand node\n supplies = np.concatenate([\n supplies_X,\n np.zeros(n_C), # C_dummies\n supplies_C,\n [supplies_art]\n ])\n\n # All arrays must be of int dtype for `SimpleMinCostFlow`\n edges = edges.astype('int32')\n costs = np.around(costs * 1000, 0).astype('int32') # Times by 1000 to give extra precision\n capacities = capacities.astype('int32')\n supplies = supplies.astype('int32')\n\n return edges, costs, capacities, supplies, n_C, n_X\n\n\ndef solve_min_cost_flow_graph(edges, costs, capacities, supplies, n_C, n_X):\n # Instantiate a SimpleMinCostFlow solver.\n min_cost_flow = SimpleMinCostFlowVectorized()\n\n if (edges.dtype != 'int32') or (costs.dtype != 'int32') \\\n or (capacities.dtype != 'int32') or (supplies.dtype != 'int32'):\n raise ValueError("`edges`, `costs`, `capacities`, `supplies` must all be int dtype")\n\n N_edges = edges.shape[0]\n N_nodes = len(supplies)\n\n # Add each edge with associated capacities and cost\n min_cost_flow.AddArcWithCapacityAndUnitCostVectorized(edges[:, 0], edges[:, 1], capacities, costs)\n\n # Add node supplies\n min_cost_flow.SetNodeSupplyVectorized(np.arange(N_nodes, dtype='int32'), supplies)\n\n # Find the minimum cost flow between node 0 and node 4.\n if min_cost_flow.Solve() != min_cost_flow.OPTIMAL:\n raise Exception('There was an issue with the min cost flow input.')\n\n # Assignment\n labels_M = min_cost_flow.FlowVectorized(np.arange(n_X * n_C, dtype='int32')).reshape(n_X, n_C)\n\n labels = labels_M.argmax(axis=1)\n return labels\n\n\n[docs]class KMeansConstrained(KMeans):\n """K-Means clustering with minimum and maximum cluster size constraints\n\n Parameters\n ----------\n\n n_clusters : int, optional, default: 8\n The number of clusters to form as well as the number of\n centroids to generate.\n\n size_min : int, optional, default: None\n Constrain the label assignment so that each cluster has a minimum\n size of size_min. If None, no constrains will be applied\n\n size_max : int, optional, default: None\n Constrain the label assignment so that each cluster has a maximum\n size of size_max. If None, no constrains will be applied\n\n init : {'k-means++', 'random' or an ndarray}\n Method for initialization, defaults to 'k-means++':\n\n 'k-means++' : selects initial cluster centers for k-mean\n clustering in a smart way to speed up convergence. See section\n Notes in k_init for more details.\n\n 'random': choose k observations (rows) at random from data for\n the initial centroids.\n\n If an ndarray is passed, it should be of shape (n_clusters, n_features)\n and gives the initial centers.\n\n n_init : int, default: 10\n Number of times the k-means algorithm will be run with different\n centroid seeds. The final results will be the best output of\n n_init consecutive runs in terms of inertia.\n\n max_iter : int, default: 300\n Maximum number of iterations of the k-means algorithm for a\n single run.\n\n tol : float, default: 1e-4\n Relative tolerance with regards to Frobenius norm of the difference\n in the cluster centers of two consecutive iterations to declare\n convergence.\n\n verbose : int, default 0\n Verbosity mode.\n\n random_state : int, RandomState instance or None, optional, default: None\n If int, random_state is the seed used by the random number generator;\n If RandomState instance, random_state is the random number generator;\n If None, the random number generator is the RandomState instance used\n by `np.random`.\n\n copy_x : boolean, default True\n When pre-computing distances it is more numerically accurate to center\n the data first. If copy_x is True, then the original data is not\n modified. If False, the original data is modified, and put back before\n the function returns, but small numerical differences may be introduced\n by subtracting and then adding the data mean.\n\n n_jobs : int\n The number of jobs to use for the computation. This works by computing\n each of the n_init runs in parallel.\n\n If -1 all CPUs are used. If 1 is given, no parallel computing code is\n used at all, which is useful for debugging. For n_jobs below -1,\n (n_cpus + 1 + n_jobs) are used. Thus for n_jobs = -2, all CPUs but one\n are used.\n\n Attributes\n ----------\n cluster_centers_ : array, [n_clusters, n_features]\n Coordinates of cluster centers\n\n labels_ :\n Labels of each point\n\n inertia_ : float\n Sum of squared distances of samples to their closest cluster center.\n\n Examples\n --------\n\n >>> from k_means_constrained import KMeansConstrained\n >>> import numpy as np\n >>> X = np.array([[1, 2], [1, 4], [1, 0],\n ... [4, 2], [4, 4], [4, 0]])\n >>> clf = KMeansConstrained(\n ... n_clusters=2,\n ... size_min=2,\n ... size_max=5,\n ... random_state=0\n ... )\n >>> clf.fit_predict(X)\n array([0, 0, 0, 1, 1, 1], dtype=int32)\n >>> clf.cluster_centers_\n array([[ 1., 2.],\n [ 4., 2.]])\n >>> clf.labels_\n array([0, 0, 0, 1, 1, 1], dtype=int32)\n\n Notes\n ------\n K-means problem constrained with a minimum and/or maximum size for each cluster.\n\n The constrained assignment is formulated as a Minimum Cost Flow (MCF) linear network optimisation\n problem. This is then solved using a cost-scaling push-relabel algorithm. The implementation used is\n Google's Operations Research tools's `SimpleMinCostFlow`.\n\n Ref:\n 1. Bradley, P. S., K. P. Bennett, and Ayhan Demiriz. "Constrained k-means clustering."\n Microsoft Research, Redmond (2000): 1-8.\n 2. Google's SimpleMinCostFlow implementation:\n https://github.com/google/or-tools/blob/master/ortools/graph/min_cost_flow.h\n """\n\n def __init__(self, n_clusters=8, size_min=None, size_max=None, init='k-means++', n_init=10, max_iter=300, tol=1e-4,\n verbose=False, random_state=None, copy_x=True, n_jobs=1):\n\n self.size_min = size_min\n self.size_max = size_max\n\n super().__init__(n_clusters=n_clusters, init=init, n_init=n_init, max_iter=max_iter, tol=tol,\n verbose=verbose, random_state=random_state, copy_x=copy_x, n_jobs=n_jobs)\n\n[docs] def fit(self, X, y=None):\n """Compute k-means clustering with given constants.\n\n Parameters\n ----------\n X : array-like, shape=(n_samples, n_features)\n Training instances to cluster.\n\n y : Ignored\n\n """\n if sp.issparse(X):\n raise NotImplementedError("Not implemented for sparse X")\n\n random_state = check_random_state(self.random_state)\n X = self._check_fit_data(X)\n\n self.cluster_centers_, self.labels_, self.inertia_, self.n_iter_ = \\\n k_means_constrained(\n X, n_clusters=self.n_clusters,\n size_min=self.size_min, size_max=self.size_max,\n init=self.init,\n n_init=self.n_init, max_iter=self.max_iter, verbose=self.verbose,\n tol=self.tol, random_state=random_state, copy_x=self.copy_x,\n n_jobs=self.n_jobs,\n return_n_iter=True)\n return self\n\n[docs] def predict(self, X, size_min='init', size_max='init'):\n """\n Predict the closest cluster each sample in X belongs to given the provided constraints.\n The constraints can be temporally overridden when determining which cluster each datapoint is assigned to.\n\n Only computes the assignment step. It does not re-fit the cluster positions.\n\n Parameters\n ----------\n X : array-like, shape = [n_samples, n_features]\n New data to predict.\n\n size_min : int, optional, default: size_min provided with initialisation\n Constrain the label assignment so that each cluster has a minimum\n size of size_min. If None, no constrains will be applied.\n If 'init' the value provided during initialisation of the\n class will be used.\n\n size_max : int, optional, default: size_max provided with initialisation\n Constrain the label assignment so that each cluster has a maximum\n size of size_max. If None, no constrains will be applied.\n If 'init' the value provided during initialisation of the\n class will be used.\n\n Returns\n -------\n labels : array, shape [n_samples,]\n Index of the cluster each sample belongs to.\n """\n\n if sp.issparse(X):\n raise NotImplementedError("Not implemented for sparse X")\n\n if size_min == 'init':\n size_min = self.size_min\n if size_max == 'init':\n size_max = self.size_max\n\n n_clusters = self.n_clusters\n n_samples = X.shape[0]\n\n check_is_fitted(self, 'cluster_centers_')\n\n X = self._check_test_data(X)\n\n # Allocate memory to store the distances for each sample to its\n # closer center for reallocation in case of ties\n distances = np.zeros(shape=(n_samples,), dtype=X.dtype)\n\n # Determine min and max sizes if non given\n if size_min is None:\n size_min = 0\n if size_max is None:\n size_max = n_samples # Number of data points\n\n # Check size min and max\n if not ((size_min >= 0) and (size_min <= n_samples)\n and (size_max >= 0) and (size_max <= n_samples)):\n raise ValueError("size_min and size_max must be a positive number smaller "\n "than the number of data points or `None`")\n if size_max < size_min:\n raise ValueError("size_max must be larger than size_min")\n if size_min * n_clusters > n_samples:\n raise ValueError("The product of size_min and n_clusters cannot exceed the number of samples (X)")\n\n labels, inertia = \\\n _labels_constrained(X, self.cluster_centers_, size_min, size_max, distances=distances)\n\n return labels\n\n[docs] def fit_predict(self, X, y=None):\n """Compute cluster centers and predict cluster index for each sample.\n\n Equivalent to calling fit(X) followed by predict(X) but also more efficient.\n\n Parameters\n ----------\n X : {array-like, sparse matrix}, shape = [n_samples, n_features]\n New data to transform.\n\n Returns\n -------\n labels : array, shape [n_samples,]\n Index of the cluster each sample belongs to.\n """\n return self.fit(X).labels_\n\n"""K-means clustering"""\n\n# Authors: Gael Varoquaux <gael.varoquaux@normalesup.org>\n# Thomas Rueckstiess <ruecksti@in.tum.de>\n# James Bergstra <james.bergstra@umontreal.ca>\n# Jan Schlueter <scikit-learn@jan-schlueter.de>\n# Nelle Varoquaux\n# Peter Prettenhofer <peter.prettenhofer@gmail.com>\n# Olivier Grisel <olivier.grisel@ensta.org>\n# Mathieu Blondel <mathieu@mblondel.org>\n# Robert Layton <robertlayton@gmail.com>\n# License: BSD 3 clause\n\nimport warnings\n\nimport numpy as np\nimport scipy.sparse as sp\nfrom sklearn.base import BaseEstimator, ClusterMixin, TransformerMixin\nfrom sklearn.externals.six import string_types\nfrom sklearn.metrics.pairwise import euclidean_distances\nfrom sklearn.metrics.pairwise import pairwise_distances_argmin_min\nfrom sklearn.utils import check_array\nfrom sklearn.utils import check_random_state\nfrom sklearn.utils.extmath import row_norms, stable_cumsum\nfrom sklearn.utils.sparsefuncs import mean_variance_axis\nfrom sklearn.utils.validation import FLOAT_DTYPES\nfrom sklearn.utils.validation import check_is_fitted\n\nfrom . import _k_means\n\n\n###############################################################################\n# Initialization heuristic\n\n\ndef _k_init(X, n_clusters, x_squared_norms, random_state, n_local_trials=None):\n """Init n_clusters seeds according to k-means++\n\n Parameters\n -----------\n X : array or sparse matrix, shape (n_samples, n_features)\n The data to pick seeds for. To avoid memory copy, the input data\n should be double precision (dtype=np.float64).\n\n n_clusters : integer\n The number of seeds to choose\n\n x_squared_norms : array, shape (n_samples,)\n Squared Euclidean norm of each data point.\n\n random_state : numpy.RandomState\n The generator used to initialize the centers.\n\n n_local_trials : integer, optional\n The number of seeding trials for each center (except the first),\n of which the one reducing inertia the most is greedily chosen.\n Set to None to make the number of trials depend logarithmically\n on the number of seeds (2+log(k)); this is the default.\n\n Notes\n -----\n Selects initial cluster centers for k-mean clustering in a smart way\n to speed up convergence. see: Arthur, D. and Vassilvitskii, S.\n "k-means++: the advantages of careful seeding". ACM-SIAM symposium\n on Discrete algorithms. 2007\n\n Version ported from http://www.stanford.edu/~darthur/kMeansppTest.zip,\n which is the implementation used in the aforementioned paper.\n """\n n_samples, n_features = X.shape\n\n centers = np.empty((n_clusters, n_features), dtype=X.dtype)\n\n assert x_squared_norms is not None, 'x_squared_norms None in _k_init'\n\n # Set the number of local seeding trials if none is given\n if n_local_trials is None:\n # This is what Arthur/Vassilvitskii tried, but did not report\n # specific results for other than mentioning in the conclusion\n # that it helped.\n n_local_trials = 2 + int(np.log(n_clusters))\n\n # Pick first center randomly\n center_id = random_state.randint(n_samples)\n if sp.issparse(X):\n centers[0] = X[center_id].toarray()\n else:\n centers[0] = X[center_id]\n\n # Initialize list of closest distances and calculate current potential\n closest_dist_sq = euclidean_distances(\n centers[0, np.newaxis], X, Y_norm_squared=x_squared_norms,\n squared=True)\n current_pot = closest_dist_sq.sum()\n\n # Pick the remaining n_clusters-1 points\n for c in range(1, n_clusters):\n # Choose center candidates by sampling with probability proportional\n # to the squared distance to the closest existing center\n rand_vals = random_state.random_sample(n_local_trials) * current_pot\n candidate_ids = np.searchsorted(stable_cumsum(closest_dist_sq),\n rand_vals)\n\n # Compute distances to center candidates\n distance_to_candidates = euclidean_distances(\n X[candidate_ids], X, Y_norm_squared=x_squared_norms, squared=True)\n\n # Decide which candidate is the best\n best_candidate = None\n best_pot = None\n best_dist_sq = None\n for trial in range(n_local_trials):\n # Compute potential when including center candidate\n new_dist_sq = np.minimum(closest_dist_sq,\n distance_to_candidates[trial])\n new_pot = new_dist_sq.sum()\n\n # Store result if it is the best local trial so far\n if (best_candidate is None) or (new_pot < best_pot):\n best_candidate = candidate_ids[trial]\n best_pot = new_pot\n best_dist_sq = new_dist_sq\n\n # Permanently add best center candidate found in local tries\n if sp.issparse(X):\n centers[c] = X[best_candidate].toarray()\n else:\n centers[c] = X[best_candidate]\n current_pot = best_pot\n closest_dist_sq = best_dist_sq\n\n return centers\n\n\n###############################################################################\n# K-means batch estimation by EM (expectation maximization)\n\ndef _validate_center_shape(X, n_centers, centers):\n """Check if centers is compatible with X and n_centers"""\n if len(centers) != n_centers:\n raise ValueError('The shape of the initial centers (%s) '\n 'does not match the number of clusters %i'\n % (centers.shape, n_centers))\n if centers.shape[1] != X.shape[1]:\n raise ValueError(\n "The number of features of the initial centers %s "\n "does not match the number of features of the data %s."\n % (centers.shape[1], X.shape[1]))\n\n\ndef _tolerance(X, tol):\n """Return a tolerance which is independent of the dataset"""\n if sp.issparse(X):\n variances = mean_variance_axis(X, axis=0)[1]\n else:\n variances = np.var(X, axis=0)\n return np.mean(variances) * tol\n\n\ndef _labels_inertia_precompute_dense(X, x_squared_norms, centers, distances):\n """Compute labels and inertia using a full distance matrix.\n\n This will overwrite the 'distances' array in-place.\n\n Parameters\n ----------\n X : numpy array, shape (n_sample, n_features)\n Input data.\n\n x_squared_norms : numpy array, shape (n_samples,)\n Precomputed squared norms of X.\n\n centers : numpy array, shape (n_clusters, n_features)\n Cluster centers which data is assigned to.\n\n distances : numpy array, shape (n_samples,)\n Pre-allocated array in which distances are stored.\n\n Returns\n -------\n labels : numpy array, dtype=np.int, shape (n_samples,)\n Indices of clusters that samples are assigned to.\n\n inertia : float\n Sum of distances of samples to their closest cluster center.\n\n """\n n_samples = X.shape[0]\n\n # Breakup nearest neighbor distance computation into batches to prevent\n # memory blowup in the case of a large number of samples and clusters.\n # TODO: Once PR #7383 is merged use check_inputs=False in metric_kwargs.\n labels, mindist = pairwise_distances_argmin_min(\n X=X, Y=centers, metric='euclidean', metric_kwargs={'squared': True})\n # cython k-means code assumes int32 inputs\n labels = labels.astype(np.int32)\n if n_samples == distances.shape[0]:\n # distances will be changed in-place\n distances[:] = mindist\n inertia = mindist.sum()\n return labels, inertia\n\n\ndef _labels_inertia(X, x_squared_norms, centers,\n precompute_distances=True, distances=None):\n """E step of the K-means EM algorithm.\n\n Compute the labels and the inertia of the given samples and centers.\n This will compute the distances in-place.\n\n Parameters\n ----------\n X : float64 array-like or CSR sparse matrix, shape (n_samples, n_features)\n The input samples to assign to the labels.\n\n x_squared_norms : array, shape (n_samples,)\n Precomputed squared euclidean norm of each data point, to speed up\n computations.\n\n centers : float array, shape (k, n_features)\n The cluster centers.\n\n precompute_distances : boolean, default: True\n Precompute distances (faster but takes more memory).\n\n distances : float array, shape (n_samples,)\n Pre-allocated array to be filled in with each sample's distance\n to the closest center.\n\n Returns\n -------\n labels : int array of shape(n)\n The resulting assignment\n\n inertia : float\n Sum of distances of samples to their closest cluster center.\n """\n n_samples = X.shape[0]\n # set the default value of centers to -1 to be able to detect any anomaly\n # easily\n labels = -np.ones(n_samples, np.int32)\n if distances is None:\n distances = np.zeros(shape=(0,), dtype=X.dtype)\n # distances will be changed in-place\n if sp.issparse(X):\n inertia = _k_means._assign_labels_csr(\n X, x_squared_norms, centers, labels, distances=distances)\n else:\n if precompute_distances:\n return _labels_inertia_precompute_dense(X, x_squared_norms,\n centers, distances)\n inertia = _k_means._assign_labels_array(\n X, x_squared_norms, centers, labels, distances=distances)\n return labels, inertia\n\n\ndef _init_centroids(X, k, init, random_state=None, x_squared_norms=None,\n init_size=None):\n """Compute the initial centroids\n\n Parameters\n ----------\n\n X : array, shape (n_samples, n_features)\n\n k : int\n number of centroids\n\n init : {'k-means++', 'random' or ndarray or callable} optional\n Method for initialization\n\n random_state : int, RandomState instance or None, optional, default: None\n If int, random_state is the seed used by the random number generator;\n If RandomState instance, random_state is the random number generator;\n If None, the random number generator is the RandomState instance used\n by `np.random`.\n\n x_squared_norms : array, shape (n_samples,), optional\n Squared euclidean norm of each data point. Pass it if you have it at\n hands already to avoid it being recomputed here. Default: None\n\n init_size : int, optional\n Number of samples to randomly sample for speeding up the\n initialization (sometimes at the expense of accuracy): the\n only algorithm is initialized by running a batch KMeans on a\n random subset of the data. This needs to be larger than k.\n\n Returns\n -------\n centers : array, shape(k, n_features)\n """\n random_state = check_random_state(random_state)\n n_samples = X.shape[0]\n\n if x_squared_norms is None:\n x_squared_norms = row_norms(X, squared=True)\n\n if init_size is not None and init_size < n_samples:\n if init_size < k:\n warnings.warn(\n "init_size=%d should be larger than k=%d. "\n "Setting it to 3*k" % (init_size, k),\n RuntimeWarning, stacklevel=2)\n init_size = 3 * k\n init_indices = random_state.randint(0, n_samples, init_size)\n X = X[init_indices]\n x_squared_norms = x_squared_norms[init_indices]\n n_samples = X.shape[0]\n elif n_samples < k:\n raise ValueError(\n "n_samples=%d should be larger than k=%d" % (n_samples, k))\n\n if isinstance(init, string_types) and init == 'k-means++':\n centers = _k_init(X, k, random_state=random_state,\n x_squared_norms=x_squared_norms)\n elif isinstance(init, string_types) and init == 'random':\n seeds = random_state.permutation(n_samples)[:k]\n centers = X[seeds]\n elif hasattr(init, '__array__'):\n # ensure that the centers have the same dtype as X\n # this is a requirement of fused types of cython\n centers = np.array(init, dtype=X.dtype)\n elif callable(init):\n centers = init(X, k, random_state=random_state)\n centers = np.asarray(centers, dtype=X.dtype)\n else:\n raise ValueError("the init parameter for the k-means should "\n "be 'k-means++' or 'random' or an ndarray, "\n "'%s' (type '%s') was passed." % (init, type(init)))\n\n if sp.issparse(centers):\n centers = centers.toarray()\n\n _validate_center_shape(X, k, centers)\n return centers\n\n\nclass KMeans(BaseEstimator, ClusterMixin, TransformerMixin):\n """K-Means clustering\n\n Read more in the :ref:`User Guide <k_means>`.\n\n Parameters\n ----------\n\n n_clusters : int, optional, default: 8\n The number of clusters to form as well as the number of\n centroids to generate.\n\n init : {'k-means++', 'random' or an ndarray}\n Method for initialization, defaults to 'k-means++':\n\n 'k-means++' : selects initial cluster centers for k-mean\n clustering in a smart way to speed up convergence. See section\n Notes in k_init for more details.\n\n 'random': choose k observations (rows) at random from data for\n the initial centroids.\n\n If an ndarray is passed, it should be of shape (n_clusters, n_features)\n and gives the initial centers.\n\n n_init : int, default: 10\n Number of time the k-means algorithm will be run with different\n centroid seeds. The final results will be the best output of\n n_init consecutive runs in terms of inertia.\n\n max_iter : int, default: 300\n Maximum number of iterations of the k-means algorithm for a\n single run.\n\n tol : float, default: 1e-4\n Relative tolerance with regards to inertia to declare convergence\n\n precompute_distances : {'auto', True, False}\n Precompute distances (faster but takes more memory).\n\n 'auto' : do not precompute distances if n_samples * n_clusters > 12\n million. This corresponds to about 100MB overhead per job using\n double precision.\n\n True : always precompute distances\n\n False : never precompute distances\n\n verbose : int, default 0\n Verbosity mode.\n\n random_state : int, RandomState instance or None, optional, default: None\n If int, random_state is the seed used by the random number generator;\n If RandomState instance, random_state is the random number generator;\n If None, the random number generator is the RandomState instance used\n by `np.random`.\n\n copy_x : boolean, default True\n When pre-computing distances it is more numerically accurate to center\n the data first. If copy_x is True, then the original data is not\n modified. If False, the original data is modified, and put back before\n the function returns, but small numerical differences may be introduced\n by subtracting and then adding the data mean.\n\n n_jobs : int\n The number of jobs to use for the computation. This works by computing\n each of the n_init runs in parallel.\n\n If -1 all CPUs are used. If 1 is given, no parallel computing code is\n used at all, which is useful for debugging. For n_jobs below -1,\n (n_cpus + 1 + n_jobs) are used. Thus for n_jobs = -2, all CPUs but one\n are used.\n\n algorithm : "auto", "full" or "elkan", default="auto"\n K-means algorithm to use. The classical EM-style algorithm is "full".\n The "elkan" variation is more efficient by using the triangle\n inequality, but currently doesn't support sparse data. "auto" chooses\n "elkan" for dense data and "full" for sparse data.\n\n Attributes\n ----------\n cluster_centers_ : array, [n_clusters, n_features]\n Coordinates of cluster centers\n\n labels_ :\n Labels of each point\n\n inertia_ : float\n Sum of distances of samples to their closest cluster center.\n\n Examples\n --------\n\n >>> from sklearn.cluster import KMeans\n >>> import numpy as np\n >>> X = np.array([[1, 2], [1, 4], [1, 0],\n ... [4, 2], [4, 4], [4, 0]])\n >>> kmeans = KMeans(n_clusters=2, random_state=0).fit(X)\n >>> kmeans.labels_\n array([0, 0, 0, 1, 1, 1], dtype=int32)\n >>> kmeans.predict([[0, 0], [4, 4]])\n array([0, 1], dtype=int32)\n >>> kmeans.cluster_centers_\n array([[ 1., 2.],\n [ 4., 2.]])\n\n See also\n --------\n\n MiniBatchKMeans\n Alternative online implementation that does incremental updates\n of the centers positions using mini-batches.\n For large scale learning (say n_samples > 10k) MiniBatchKMeans is\n probably much faster than the default batch implementation.\n\n Notes\n ------\n The k-means problem is solved using Lloyd's algorithm.\n\n The average complexity is given by O(k n T), were n is the number of\n samples and T is the number of iteration.\n\n The worst case complexity is given by O(n^(k+2/p)) with\n n = n_samples, p = n_features. (D. Arthur and S. Vassilvitskii,\n 'How slow is the k-means method?' SoCG2006)\n\n In practice, the k-means algorithm is very fast (one of the fastest\n clustering algorithms available), but it falls in local minima. That's why\n it can be useful to restart it several times.\n\n """\n\n def __init__(self, n_clusters=8, init='k-means++', n_init=10,\n max_iter=300, tol=1e-4, precompute_distances='auto',\n verbose=0, random_state=None, copy_x=True,\n n_jobs=1, algorithm='auto'):\n\n self.n_clusters = n_clusters\n self.init = init\n self.max_iter = max_iter\n self.tol = tol\n self.precompute_distances = precompute_distances\n self.n_init = n_init\n self.verbose = verbose\n self.random_state = random_state\n self.copy_x = copy_x\n self.n_jobs = n_jobs\n self.algorithm = algorithm\n\n def _check_fit_data(self, X):\n """Verify that the number of samples given is larger than k"""\n X = check_array(X, accept_sparse='csr', dtype=[np.float64, np.float32])\n if X.shape[0] < self.n_clusters:\n raise ValueError("n_samples=%d should be >= n_clusters=%d" % (\n X.shape[0], self.n_clusters))\n return X\n\n def _check_test_data(self, X):\n X = check_array(X, accept_sparse='csr', dtype=FLOAT_DTYPES)\n n_samples, n_features = X.shape\n expected_n_features = self.cluster_centers_.shape[1]\n if not n_features == expected_n_features:\n raise ValueError("Incorrect number of features. "\n "Got %d features, expected %d" % (\n n_features, expected_n_features))\n\n return X\n\n def fit(self, X, y=None):\n """Compute k-means clustering.\n\n Parameters\n ----------\n X : array-like or sparse matrix, shape=(n_samples, n_features)\n Training instances to cluster.\n """\n # Added to remove scikit-learn internal dependenceies\n raise NotImplemented\n\n def fit_predict(self, X, y=None):\n """Compute cluster centers and predict cluster index for each sample.\n\n Convenience method; equivalent to calling fit(X) followed by\n predict(X).\n\n Parameters\n ----------\n X : {array-like, sparse matrix}, shape = [n_samples, n_features]\n New data to transform.\n\n Returns\n -------\n labels : array, shape [n_samples,]\n Index of the cluster each sample belongs to.\n """\n return self.fit(X).labels_\n\n def fit_transform(self, X, y=None):\n """Compute clustering and transform X to cluster-distance space.\n\n Equivalent to fit(X).transform(X), but more efficiently implemented.\n\n Parameters\n ----------\n X : {array-like, sparse matrix}, shape = [n_samples, n_features]\n New data to transform.\n\n Returns\n -------\n X_new : array, shape [n_samples, k]\n X transformed in the new space.\n """\n # Currently, this just skips a copy of the data if it is not in\n # np.array or CSR format already.\n # XXX This skips _check_test_data, which may change the dtype;\n # we should refactor the input validation.\n X = self._check_fit_data(X)\n return self.fit(X)._transform(X)\n\n def transform(self, X):\n """Transform X to a cluster-distance space.\n\n In the new space, each dimension is the distance to the cluster\n centers. Note that even if X is sparse, the array returned by\n `transform` will typically be dense.\n\n Parameters\n ----------\n X : {array-like, sparse matrix}, shape = [n_samples, n_features]\n New data to transform.\n\n Returns\n -------\n X_new : array, shape [n_samples, k]\n X transformed in the new space.\n """\n check_is_fitted(self, 'cluster_centers_')\n\n X = self._check_test_data(X)\n return self._transform(X)\n\n def _transform(self, X):\n """guts of transform method; no input validation"""\n return euclidean_distances(X, self.cluster_centers_)\n\n def predict(self, X):\n """Predict the closest cluster each sample in X belongs to.\n\n In the vector quantization literature, `cluster_centers_` is called\n the code book and each value returned by `predict` is the index of\n the closest code in the code book.\n\n Parameters\n ----------\n X : {array-like, sparse matrix}, shape = [n_samples, n_features]\n New data to predict.\n\n Returns\n -------\n labels : array, shape [n_samples,]\n Index of the cluster each sample belongs to.\n """\n check_is_fitted(self, 'cluster_centers_')\n\n X = self._check_test_data(X)\n x_squared_norms = row_norms(X, squared=True)\n return _labels_inertia(X, x_squared_norms, self.cluster_centers_)[0]\n\n def score(self, X, y=None):\n """Opposite of the value of X on the K-means objective.\n\n Parameters\n ----------\n X : {array-like, sparse matrix}, shape = [n_samples, n_features]\n New data.\n\n Returns\n -------\n score : float\n Opposite of the value of X on the K-means objective.\n """\n check_is_fitted(self, 'cluster_centers_')\n\n X = self._check_test_data(X)\n x_squared_norms = row_norms(X, squared=True)\n return -_labels_inertia(X, x_squared_norms, self.cluster_centers_)[1]\n\n\n\nimport warnings\nfrom collections import defaultdict\n\nimport numpy as np\nimport six\n\nfrom k_means_constrained.sklearn_import import __version__\nfrom k_means_constrained.sklearn_import.funcsigs import signature\n\n\nclass BaseEstimator(object):\n """Base class for all estimators in scikit-learn\n\n Notes\n -----\n All estimators should specify all the parameters that can be set\n at the class level in their ``__init__`` as explicit keyword\n arguments (no ``*args`` or ``**kwargs``).\n """\n\n @classmethod\n def _get_param_names(cls):\n """Get parameter names for the estimator"""\n # fetch the constructor or the original constructor before\n # deprecation wrapping if any\n init = getattr(cls.__init__, 'deprecated_original', cls.__init__)\n if init is object.__init__:\n # No explicit constructor to introspect\n return []\n\n # introspect the constructor arguments to find the model parameters\n # to represent\n init_signature = signature(init)\n # Consider the constructor parameters excluding 'self'\n parameters = [p for p in init_signature.parameters.values()\n if p.name != 'self' and p.kind != p.VAR_KEYWORD]\n for p in parameters:\n if p.kind == p.VAR_POSITIONAL:\n raise RuntimeError("scikit-learn estimators should always "\n "specify their parameters in the signature"\n " of their __init__ (no varargs)."\n " %s with constructor %s doesn't "\n " follow this convention."\n % (cls, init_signature))\n # Extract and sort argument names excluding 'self'\n return sorted([p.name for p in parameters])\n\n def get_params(self, deep=True):\n """Get parameters for this estimator.\n\n Parameters\n ----------\n deep : boolean, optional\n If True, will return the parameters for this estimator and\n contained subobjects that are estimators.\n\n Returns\n -------\n params : mapping of string to any\n Parameter names mapped to their values.\n """\n out = dict()\n for key in self._get_param_names():\n # We need deprecation warnings to always be on in order to\n # catch deprecated param values.\n # This is set in utils/__init__.py but it gets overwritten\n # when running under python3 somehow.\n warnings.simplefilter("always", DeprecationWarning)\n try:\n with warnings.catch_warnings(record=True) as w:\n value = getattr(self, key, None)\n if len(w) and w[0].category == DeprecationWarning:\n # if the parameter is deprecated, don't show it\n continue\n finally:\n warnings.filters.pop(0)\n\n # XXX: should we rather test if instance of estimator?\n if deep and hasattr(value, 'get_params'):\n deep_items = value.get_params().items()\n out.update((key + '__' + k, val) for k, val in deep_items)\n out[key] = value\n return out\n\n def set_params(self, **params):\n """Set the parameters of this estimator.\n\n The method works on simple estimators as well as on nested objects\n (such as pipelines). The latter have parameters of the form\n ``<component>__<parameter>`` so that it's possible to update each\n component of a nested object.\n\n Returns\n -------\n self\n """\n if not params:\n # Simple optimization to gain speed (inspect is slow)\n return self\n valid_params = self.get_params(deep=True)\n\n nested_params = defaultdict(dict) # grouped by prefix\n for key, value in params.items():\n key, delim, sub_key = key.partition('__')\n if key not in valid_params:\n raise ValueError('Invalid parameter %s for estimator %s. '\n 'Check the list of available parameters '\n 'with `estimator.get_params().keys()`.' %\n (key, self))\n\n if delim:\n nested_params[key][sub_key] = value\n else:\n setattr(self, key, value)\n\n for key, sub_params in nested_params.items():\n valid_params[key].set_params(**sub_params)\n\n return self\n\n def __repr__(self):\n class_name = self.__class__.__name__\n return '%s(%s)' % (class_name, _pprint(self.get_params(deep=False),\n offset=len(class_name),),)\n\n def __getstate__(self):\n try:\n state = super(BaseEstimator, self).__getstate__()\n except AttributeError:\n state = self.__dict__.copy()\n\n if type(self).__module__.startswith('sklearn.'):\n return dict(state.items(), _sklearn_version=__version__)\n else:\n return state\n\n def __setstate__(self, state):\n if type(self).__module__.startswith('sklearn.'):\n pickle_version = state.pop("_sklearn_version", "pre-0.18")\n if pickle_version != __version__:\n warnings.warn(\n "Trying to unpickle estimator {0} from version {1} when "\n "using version {2}. This might lead to breaking code or "\n "invalid results. Use at your own risk.".format(\n self.__class__.__name__, pickle_version, __version__),\n UserWarning)\n try:\n super(BaseEstimator, self).__setstate__(state)\n except AttributeError:\n self.__dict__.update(state)\n\n\nclass ClusterMixin(object):\n """Mixin class for all cluster estimators in scikit-learn."""\n _estimator_type = "clusterer"\n\n def fit_predict(self, X, y=None):\n """Performs clustering on X and returns cluster labels.\n\n Parameters\n ----------\n X : ndarray, shape (n_samples, n_features)\n Input data.\n\n Returns\n -------\n y : ndarray, shape (n_samples,)\n cluster labels\n """\n # non-optimized default implementation; override when a better\n # method is possible for a given clustering algorithm\n self.fit(X)\n return self.labels_\n\n\nclass TransformerMixin(object):\n """Mixin class for all transformers in scikit-learn."""\n\n def fit_transform(self, X, y=None, **fit_params):\n """Fit to data, then transform it.\n\n Fits transformer to X and y with optional parameters fit_params\n and returns a transformed version of X.\n\n Parameters\n ----------\n X : numpy array of shape [n_samples, n_features]\n Training set.\n\n y : numpy array of shape [n_samples]\n Target values.\n\n Returns\n -------\n X_new : numpy array of shape [n_samples, n_features_new]\n Transformed array.\n\n """\n # non-optimized default implementation; override when a better\n # method is possible for a given clustering algorithm\n if y is None:\n # fit method of arity 1 (unsupervised transformation)\n return self.fit(X, **fit_params).transform(X)\n else:\n # fit method of arity 2 (supervised transformation)\n return self.fit(X, y, **fit_params).transform(X)\n\n\ndef _pprint(params, offset=0, printer=repr):\n """Pretty print the dictionary 'params'\n\n Parameters\n ----------\n params : dict\n The dictionary to pretty print\n\n offset : int\n The offset in characters to add at the begin of each line.\n\n printer : callable\n The function to convert entries to strings, typically\n the builtin str or repr\n\n """\n # Do a multi-line justified repr:\n options = np.get_printoptions()\n np.set_printoptions(precision=5, threshold=64, edgeitems=2)\n params_list = list()\n this_line_length = offset\n line_sep = ',\\n' + (1 + offset // 2) * ' '\n for i, (k, v) in enumerate(sorted(six.iteritems(params))):\n if type(v) is float:\n # use str for representing floating point numbers\n # this way we get consistent representation across\n # architectures and versions.\n this_repr = '%s=%s' % (k, str(v))\n else:\n # use repr of the rest\n this_repr = '%s=%s' % (k, printer(v))\n if len(this_repr) > 500:\n this_repr = this_repr[:300] + '...' + this_repr[-100:]\n if i > 0:\n if (this_line_length + len(this_repr) >= 75 or '\\n' in this_repr):\n params_list.append(line_sep)\n this_line_length = len(line_sep)\n else:\n params_list.append(', ')\n this_line_length += 2\n params_list.append(this_repr)\n this_line_length += len(this_repr)\n\n np.set_printoptions(**options)\n lines = ''.join(params_list)\n # Strip trailing space to avoid nightmare in doctests\n lines = '\\n'.join(l.rstrip(' ') for l in lines.split('\\n'))\n return lines\n\n"""K-means clustering"""\n\n# Authors: Gael Varoquaux <gael.varoquaux@normalesup.org>\n# Thomas Rueckstiess <ruecksti@in.tum.de>\n# James Bergstra <james.bergstra@umontreal.ca>\n# Jan Schlueter <scikit-learn@jan-schlueter.de>\n# Nelle Varoquaux\n# Peter Prettenhofer <peter.prettenhofer@gmail.com>\n# Olivier Grisel <olivier.grisel@ensta.org>\n# Mathieu Blondel <mathieu@mblondel.org>\n# Robert Layton <robertlayton@gmail.com>\n# License: BSD 3 clause\n\nimport warnings\n\nimport numpy as np\nimport scipy.sparse as sp\nfrom k_means_constrained.sklearn_import.base import BaseEstimator, ClusterMixin, TransformerMixin\nfrom six import string_types\nfrom k_means_constrained.sklearn_import.metrics.pairwise import euclidean_distances, pairwise_distances_argmin_min\nfrom k_means_constrained.sklearn_import.utils.validation import check_array, check_random_state, FLOAT_DTYPES, \\\n check_is_fitted\nfrom k_means_constrained.sklearn_import.utils.extmath import row_norms, stable_cumsum\nfrom k_means_constrained.sklearn_import.utils.sparsefuncs import mean_variance_axis\n\nfrom k_means_constrained.sklearn_import.cluster import _k_means\n\n\n###############################################################################\n# Initialization heuristic\n\n\ndef _k_init(X, n_clusters, x_squared_norms, random_state, n_local_trials=None):\n """Init n_clusters seeds according to k-means++\n\n Parameters\n -----------\n X : array or sparse matrix, shape (n_samples, n_features)\n The data to pick seeds for. To avoid memory copy, the input data\n should be double precision (dtype=np.float64).\n\n n_clusters : integer\n The number of seeds to choose\n\n x_squared_norms : array, shape (n_samples,)\n Squared Euclidean norm of each data point.\n\n random_state : numpy.RandomState\n The generator used to initialize the centers.\n\n n_local_trials : integer, optional\n The number of seeding trials for each center (except the first),\n of which the one reducing inertia the most is greedily chosen.\n Set to None to make the number of trials depend logarithmically\n on the number of seeds (2+log(k)); this is the default.\n\n Notes\n -----\n Selects initial cluster centers for k-mean clustering in a smart way\n to speed up convergence. see: Arthur, D. and Vassilvitskii, S.\n "k-means++: the advantages of careful seeding". ACM-SIAM symposium\n on Discrete algorithms. 2007\n\n Version ported from http://www.stanford.edu/~darthur/kMeansppTest.zip,\n which is the implementation used in the aforementioned paper.\n """\n n_samples, n_features = X.shape\n\n centers = np.empty((n_clusters, n_features), dtype=X.dtype)\n\n assert x_squared_norms is not None, 'x_squared_norms None in _k_init'\n\n # Set the number of local seeding trials if none is given\n if n_local_trials is None:\n # This is what Arthur/Vassilvitskii tried, but did not report\n # specific results for other than mentioning in the conclusion\n # that it helped.\n n_local_trials = 2 + int(np.log(n_clusters))\n\n # Pick first center randomly\n center_id = random_state.randint(n_samples)\n if sp.issparse(X):\n centers[0] = X[center_id].toarray()\n else:\n centers[0] = X[center_id]\n\n # Initialize list of closest distances and calculate current potential\n closest_dist_sq = euclidean_distances(\n centers[0, np.newaxis], X, Y_norm_squared=x_squared_norms,\n squared=True)\n current_pot = closest_dist_sq.sum()\n\n # Pick the remaining n_clusters-1 points\n for c in range(1, n_clusters):\n # Choose center candidates by sampling with probability proportional\n # to the squared distance to the closest existing center\n rand_vals = random_state.random_sample(n_local_trials) * current_pot\n candidate_ids = np.searchsorted(stable_cumsum(closest_dist_sq),\n rand_vals)\n\n # Compute distances to center candidates\n distance_to_candidates = euclidean_distances(\n X[candidate_ids], X, Y_norm_squared=x_squared_norms, squared=True)\n\n # Decide which candidate is the best\n best_candidate = None\n best_pot = None\n best_dist_sq = None\n for trial in range(n_local_trials):\n # Compute potential when including center candidate\n new_dist_sq = np.minimum(closest_dist_sq,\n distance_to_candidates[trial])\n new_pot = new_dist_sq.sum()\n\n # Store result if it is the best local trial so far\n if (best_candidate is None) or (new_pot < best_pot):\n best_candidate = candidate_ids[trial]\n best_pot = new_pot\n best_dist_sq = new_dist_sq\n\n # Permanently add best center candidate found in local tries\n if sp.issparse(X):\n centers[c] = X[best_candidate].toarray()\n else:\n centers[c] = X[best_candidate]\n current_pot = best_pot\n closest_dist_sq = best_dist_sq\n\n return centers\n\n\n###############################################################################\n# K-means batch estimation by EM (expectation maximization)\n\ndef _validate_center_shape(X, n_centers, centers):\n """Check if centers is compatible with X and n_centers"""\n if len(centers) != n_centers:\n raise ValueError('The shape of the initial centers (%s) '\n 'does not match the number of clusters %i'\n % (centers.shape, n_centers))\n if centers.shape[1] != X.shape[1]:\n raise ValueError(\n "The number of features of the initial centers %s "\n "does not match the number of features of the data %s."\n % (centers.shape[1], X.shape[1]))\n\n\ndef _tolerance(X, tol):\n """Return a tolerance which is independent of the dataset"""\n if sp.issparse(X):\n variances = mean_variance_axis(X, axis=0)[1]\n else:\n variances = np.var(X, axis=0)\n return np.mean(variances) * tol\n\n\ndef _labels_inertia_precompute_dense(X, x_squared_norms, centers, distances):\n """Compute labels and inertia using a full distance matrix.\n\n This will overwrite the 'distances' array in-place.\n\n Parameters\n ----------\n X : numpy array, shape (n_sample, n_features)\n Input data.\n\n x_squared_norms : numpy array, shape (n_samples,)\n Precomputed squared norms of X.\n\n centers : numpy array, shape (n_clusters, n_features)\n Cluster centers which data is assigned to.\n\n distances : numpy array, shape (n_samples,)\n Pre-allocated array in which distances are stored.\n\n Returns\n -------\n labels : numpy array, dtype=np.int, shape (n_samples,)\n Indices of clusters that samples are assigned to.\n\n inertia : float\n Sum of distances of samples to their closest cluster center.\n\n """\n n_samples = X.shape[0]\n\n # Breakup nearest neighbor distance computation into batches to prevent\n # memory blowup in the case of a large number of samples and clusters.\n # TODO: Once PR #7383 is merged use check_inputs=False in metric_kwargs.\n labels, mindist = pairwise_distances_argmin_min(\n X=X, Y=centers, metric='euclidean', metric_kwargs={'squared': True})\n # cython k-means code assumes int32 inputs\n labels = labels.astype(np.int32)\n if n_samples == distances.shape[0]:\n # distances will be changed in-place\n distances[:] = mindist\n inertia = mindist.sum()\n return labels, inertia\n\n\ndef _labels_inertia(X, x_squared_norms, centers,\n precompute_distances=True, distances=None):\n """E step of the K-means EM algorithm.\n\n Compute the labels and the inertia of the given samples and centers.\n This will compute the distances in-place.\n\n Parameters\n ----------\n X : float64 array-like or CSR sparse matrix, shape (n_samples, n_features)\n The input samples to assign to the labels.\n\n x_squared_norms : array, shape (n_samples,)\n Precomputed squared euclidean norm of each data point, to speed up\n computations.\n\n centers : float array, shape (k, n_features)\n The cluster centers.\n\n precompute_distances : boolean, default: True\n Precompute distances (faster but takes more memory).\n\n distances : float array, shape (n_samples,)\n Pre-allocated array to be filled in with each sample's distance\n to the closest center.\n\n Returns\n -------\n labels : int array of shape(n)\n The resulting assignment\n\n inertia : float\n Sum of distances of samples to their closest cluster center.\n """\n n_samples = X.shape[0]\n # set the default value of centers to -1 to be able to detect any anomaly\n # easily\n labels = -np.ones(n_samples, np.int32)\n if distances is None:\n distances = np.zeros(shape=(0,), dtype=X.dtype)\n # distances will be changed in-place\n if sp.issparse(X):\n inertia = _k_means._assign_labels_csr(\n X, x_squared_norms, centers, labels, distances=distances)\n else:\n if precompute_distances:\n return _labels_inertia_precompute_dense(X, x_squared_norms,\n centers, distances)\n inertia = _k_means._assign_labels_array(\n X, x_squared_norms, centers, labels, distances=distances)\n return labels, inertia\n\n\ndef _init_centroids(X, k, init, random_state=None, x_squared_norms=None,\n init_size=None):\n """Compute the initial centroids\n\n Parameters\n ----------\n\n X : array, shape (n_samples, n_features)\n\n k : int\n number of centroids\n\n init : {'k-means++', 'random' or ndarray or callable} optional\n Method for initialization\n\n random_state : int, RandomState instance or None, optional, default: None\n If int, random_state is the seed used by the random number generator;\n If RandomState instance, random_state is the random number generator;\n If None, the random number generator is the RandomState instance used\n by `np.random`.\n\n x_squared_norms : array, shape (n_samples,), optional\n Squared euclidean norm of each data point. Pass it if you have it at\n hands already to avoid it being recomputed here. Default: None\n\n init_size : int, optional\n Number of samples to randomly sample for speeding up the\n initialization (sometimes at the expense of accuracy): the\n only algorithm is initialized by running a batch KMeans on a\n random subset of the data. This needs to be larger than k.\n\n Returns\n -------\n centers : array, shape(k, n_features)\n """\n random_state = check_random_state(random_state)\n n_samples = X.shape[0]\n\n if x_squared_norms is None:\n x_squared_norms = row_norms(X, squared=True)\n\n if init_size is not None and init_size < n_samples:\n if init_size < k:\n warnings.warn(\n "init_size=%d should be larger than k=%d. "\n "Setting it to 3*k" % (init_size, k),\n RuntimeWarning, stacklevel=2)\n init_size = 3 * k\n init_indices = random_state.randint(0, n_samples, init_size)\n X = X[init_indices]\n x_squared_norms = x_squared_norms[init_indices]\n n_samples = X.shape[0]\n elif n_samples < k:\n raise ValueError(\n "n_samples=%d should be larger than k=%d" % (n_samples, k))\n\n if isinstance(init, string_types) and init == 'k-means++':\n centers = _k_init(X, k, random_state=random_state,\n x_squared_norms=x_squared_norms)\n elif isinstance(init, string_types) and init == 'random':\n seeds = random_state.permutation(n_samples)[:k]\n centers = X[seeds]\n elif hasattr(init, '__array__'):\n # ensure that the centers have the same dtype as X\n # this is a requirement of fused types of cython\n centers = np.array(init, dtype=X.dtype)\n elif callable(init):\n centers = init(X, k, random_state=random_state)\n centers = np.asarray(centers, dtype=X.dtype)\n else:\n raise ValueError("the init parameter for the k-means should "\n "be 'k-means++' or 'random' or an ndarray, "\n "'%s' (type '%s') was passed." % (init, type(init)))\n\n if sp.issparse(centers):\n centers = centers.toarray()\n\n _validate_center_shape(X, k, centers)\n return centers\n\n\nclass KMeans(BaseEstimator, ClusterMixin, TransformerMixin):\n """K-Means clustering\n\n Read more in the :ref:`User Guide <k_means>`.\n\n Parameters\n ----------\n\n n_clusters : int, optional, default: 8\n The number of clusters to form as well as the number of\n centroids to generate.\n\n init : {'k-means++', 'random' or an ndarray}\n Method for initialization, defaults to 'k-means++':\n\n 'k-means++' : selects initial cluster centers for k-mean\n clustering in a smart way to speed up convergence. See section\n Notes in k_init for more details.\n\n 'random': choose k observations (rows) at random from data for\n the initial centroids.\n\n If an ndarray is passed, it should be of shape (n_clusters, n_features)\n and gives the initial centers.\n\n n_init : int, default: 10\n Number of time the k-means algorithm will be run with different\n centroid seeds. The final results will be the best output of\n n_init consecutive runs in terms of inertia.\n\n max_iter : int, default: 300\n Maximum number of iterations of the k-means algorithm for a\n single run.\n\n tol : float, default: 1e-4\n Relative tolerance with regards to inertia to declare convergence\n\n precompute_distances : {'auto', True, False}\n Precompute distances (faster but takes more memory).\n\n 'auto' : do not precompute distances if n_samples * n_clusters > 12\n million. This corresponds to about 100MB overhead per job using\n double precision.\n\n True : always precompute distances\n\n False : never precompute distances\n\n verbose : int, default 0\n Verbosity mode.\n\n random_state : int, RandomState instance or None, optional, default: None\n If int, random_state is the seed used by the random number generator;\n If RandomState instance, random_state is the random number generator;\n If None, the random number generator is the RandomState instance used\n by `np.random`.\n\n copy_x : boolean, default True\n When pre-computing distances it is more numerically accurate to center\n the data first. If copy_x is True, then the original data is not\n modified. If False, the original data is modified, and put back before\n the function returns, but small numerical differences may be introduced\n by subtracting and then adding the data mean.\n\n n_jobs : int\n The number of jobs to use for the computation. This works by computing\n each of the n_init runs in parallel.\n\n If -1 all CPUs are used. If 1 is given, no parallel computing code is\n used at all, which is useful for debugging. For n_jobs below -1,\n (n_cpus + 1 + n_jobs) are used. Thus for n_jobs = -2, all CPUs but one\n are used.\n\n algorithm : "auto", "full" or "elkan", default="auto"\n K-means algorithm to use. The classical EM-style algorithm is "full".\n The "elkan" variation is more efficient by using the triangle\n inequality, but currently doesn't support sparse data. "auto" chooses\n "elkan" for dense data and "full" for sparse data.\n\n Attributes\n ----------\n cluster_centers_ : array, [n_clusters, n_features]\n Coordinates of cluster centers\n\n labels_ :\n Labels of each point\n\n inertia_ : float\n Sum of distances of samples to their closest cluster center.\n\n Examples\n --------\n\n >>> from sklearn.cluster import KMeans\n >>> import numpy as np\n >>> X = np.array([[1, 2], [1, 4], [1, 0],\n ... [4, 2], [4, 4], [4, 0]])\n >>> kmeans = KMeans(n_clusters=2, random_state=0).fit(X)\n >>> kmeans.labels_\n array([0, 0, 0, 1, 1, 1], dtype=int32)\n >>> kmeans.predict([[0, 0], [4, 4]])\n array([0, 1], dtype=int32)\n >>> kmeans.cluster_centers_\n array([[ 1., 2.],\n [ 4., 2.]])\n\n See also\n --------\n\n MiniBatchKMeans\n Alternative online implementation that does incremental updates\n of the centers positions using mini-batches.\n For large scale learning (say n_samples > 10k) MiniBatchKMeans is\n probably much faster than the default batch implementation.\n\n Notes\n ------\n The k-means problem is solved using Lloyd's algorithm.\n\n The average complexity is given by O(k n T), were n is the number of\n samples and T is the number of iteration.\n\n The worst case complexity is given by O(n^(k+2/p)) with\n n = n_samples, p = n_features. (D. Arthur and S. Vassilvitskii,\n 'How slow is the k-means method?' SoCG2006)\n\n In practice, the k-means algorithm is very fast (one of the fastest\n clustering algorithms available), but it falls in local minima. That's why\n it can be useful to restart it several times.\n\n """\n\n def __init__(self, n_clusters=8, init='k-means++', n_init=10,\n max_iter=300, tol=1e-4, precompute_distances='auto',\n verbose=0, random_state=None, copy_x=True,\n n_jobs=1, algorithm='auto'):\n\n self.n_clusters = n_clusters\n self.init = init\n self.max_iter = max_iter\n self.tol = tol\n self.precompute_distances = precompute_distances\n self.n_init = n_init\n self.verbose = verbose\n self.random_state = random_state\n self.copy_x = copy_x\n self.n_jobs = n_jobs\n self.algorithm = algorithm\n\n def _check_fit_data(self, X):\n """Verify that the number of samples given is larger than k"""\n X = check_array(X, accept_sparse='csr', dtype=[np.float64, np.float32])\n if X.shape[0] < self.n_clusters:\n raise ValueError("n_samples=%d should be >= n_clusters=%d" % (\n X.shape[0], self.n_clusters))\n return X\n\n def _check_test_data(self, X):\n X = check_array(X, accept_sparse='csr', dtype=FLOAT_DTYPES)\n n_samples, n_features = X.shape\n expected_n_features = self.cluster_centers_.shape[1]\n if not n_features == expected_n_features:\n raise ValueError("Incorrect number of features. "\n "Got %d features, expected %d" % (\n n_features, expected_n_features))\n\n return X\n\n def fit(self, X, y=None):\n """Compute k-means clustering.\n\n Parameters\n ----------\n X : array-like or sparse matrix, shape=(n_samples, n_features)\n Training instances to cluster.\n """\n # Added to remove scikit-learn internal dependenceies\n raise NotImplemented\n\n def fit_predict(self, X, y=None):\n """Compute cluster centers and predict cluster index for each sample.\n\n Convenience method; equivalent to calling fit(X) followed by\n predict(X).\n\n Parameters\n ----------\n X : {array-like, sparse matrix}, shape = [n_samples, n_features]\n New data to transform.\n\n Returns\n -------\n labels : array, shape [n_samples,]\n Index of the cluster each sample belongs to.\n """\n return self.fit(X).labels_\n\n def fit_transform(self, X, y=None):\n """Compute clustering and transform X to cluster-distance space.\n\n Equivalent to fit(X).transform(X), but more efficiently implemented.\n\n Parameters\n ----------\n X : {array-like, sparse matrix}, shape = [n_samples, n_features]\n New data to transform.\n\n Returns\n -------\n X_new : array, shape [n_samples, k]\n X transformed in the new space.\n """\n # Currently, this just skips a copy of the data if it is not in\n # np.array or CSR format already.\n # XXX This skips _check_test_data, which may change the dtype;\n # we should refactor the input validation.\n X = self._check_fit_data(X)\n return self.fit(X)._transform(X)\n\n def transform(self, X):\n """Transform X to a cluster-distance space.\n\n In the new space, each dimension is the distance to the cluster\n centers. Note that even if X is sparse, the array returned by\n `transform` will typically be dense.\n\n Parameters\n ----------\n X : {array-like, sparse matrix}, shape = [n_samples, n_features]\n New data to transform.\n\n Returns\n -------\n X_new : array, shape [n_samples, k]\n X transformed in the new space.\n """\n check_is_fitted(self, 'cluster_centers_')\n\n X = self._check_test_data(X)\n return self._transform(X)\n\n def _transform(self, X):\n """guts of transform method; no input validation"""\n return euclidean_distances(X, self.cluster_centers_)\n\n def predict(self, X):\n """Predict the closest cluster each sample in X belongs to.\n\n In the vector quantization literature, `cluster_centers_` is called\n the code book and each value returned by `predict` is the index of\n the closest code in the code book.\n\n Parameters\n ----------\n X : {array-like, sparse matrix}, shape = [n_samples, n_features]\n New data to predict.\n\n Returns\n -------\n labels : array, shape [n_samples,]\n Index of the cluster each sample belongs to.\n """\n check_is_fitted(self, 'cluster_centers_')\n\n X = self._check_test_data(X)\n x_squared_norms = row_norms(X, squared=True)\n return _labels_inertia(X, x_squared_norms, self.cluster_centers_)[0]\n\n def score(self, X, y=None):\n """Opposite of the value of X on the K-means objective.\n\n Parameters\n ----------\n X : {array-like, sparse matrix}, shape = [n_samples, n_features]\n New data.\n\n Returns\n -------\n score : float\n Opposite of the value of X on the K-means objective.\n """\n check_is_fitted(self, 'cluster_centers_')\n\n X = self._check_test_data(X)\n x_squared_norms = row_norms(X, squared=True)\n return -_labels_inertia(X, x_squared_norms, self.cluster_centers_)[1]\n\n\n\n"""Base classes for all estimators."""\n\n# Author: Gael Varoquaux <gael.varoquaux@normalesup.org>\n# License: BSD 3 clause\n\nimport copy\nimport warnings\nfrom collections import defaultdict\nimport platform\nimport inspect\nimport re\n\nimport numpy as np\n\nfrom . import __version__\nfrom .utils import _IS_32BIT\n\n_DEFAULT_TAGS = {\n 'non_deterministic': False,\n 'requires_positive_data': False,\n 'X_types': ['2darray'],\n 'poor_score': False,\n 'no_validation': False,\n 'multioutput': False,\n "allow_nan": False,\n 'stateless': False,\n 'multilabel': False,\n '_skip_test': False,\n 'multioutput_only': False}\n\n\ndef clone(estimator, safe=True):\n """Constructs a new estimator with the same parameters.\n\n Clone does a deep copy of the model in an estimator\n without actually copying attached data. It yields a new estimator\n with the same parameters that has not been fit on any data.\n\n Parameters\n ----------\n estimator : estimator object, or list, tuple or set of objects\n The estimator or group of estimators to be cloned\n\n safe : boolean, optional\n If safe is false, clone will fall back to a deep copy on objects\n that are not estimators.\n\n """\n estimator_type = type(estimator)\n # XXX: not handling dictionaries\n if estimator_type in (list, tuple, set, frozenset):\n return estimator_type([clone(e, safe=safe) for e in estimator])\n elif not hasattr(estimator, 'get_params') or isinstance(estimator, type):\n if not safe:\n return copy.deepcopy(estimator)\n else:\n raise TypeError("Cannot clone object '%s' (type %s): "\n "it does not seem to be a scikit-learn estimator "\n "as it does not implement a 'get_params' methods."\n % (repr(estimator), type(estimator)))\n klass = estimator.__class__\n new_object_params = estimator.get_params(deep=False)\n for name, param in new_object_params.items():\n new_object_params[name] = clone(param, safe=False)\n new_object = klass(**new_object_params)\n params_set = new_object.get_params(deep=False)\n\n # quick sanity check of the parameters of the clone\n for name in new_object_params:\n param1 = new_object_params[name]\n param2 = params_set[name]\n if param1 is not param2:\n raise RuntimeError('Cannot clone object %s, as the constructor '\n 'either does not set or modifies parameter %s' %\n (estimator, name))\n return new_object\n\n\ndef _pprint(params, offset=0, printer=repr):\n """Pretty print the dictionary 'params'\n\n Parameters\n ----------\n params : dict\n The dictionary to pretty print\n\n offset : int\n The offset in characters to add at the begin of each line.\n\n printer : callable\n The function to convert entries to strings, typically\n the builtin str or repr\n\n """\n # Do a multi-line justified repr:\n options = np.get_printoptions()\n np.set_printoptions(precision=5, threshold=64, edgeitems=2)\n params_list = list()\n this_line_length = offset\n line_sep = ',\\n' + (1 + offset // 2) * ' '\n for i, (k, v) in enumerate(sorted(params.items())):\n if type(v) is float:\n # use str for representing floating point numbers\n # this way we get consistent representation across\n # architectures and versions.\n this_repr = '%s=%s' % (k, str(v))\n else:\n # use repr of the rest\n this_repr = '%s=%s' % (k, printer(v))\n if len(this_repr) > 500:\n this_repr = this_repr[:300] + '...' + this_repr[-100:]\n if i > 0:\n if (this_line_length + len(this_repr) >= 75 or '\\n' in this_repr):\n params_list.append(line_sep)\n this_line_length = len(line_sep)\n else:\n params_list.append(', ')\n this_line_length += 2\n params_list.append(this_repr)\n this_line_length += len(this_repr)\n\n np.set_printoptions(**options)\n lines = ''.join(params_list)\n # Strip trailing space to avoid nightmare in doctests\n lines = '\\n'.join(l.rstrip(' ') for l in lines.split('\\n'))\n return lines\n\n\ndef _update_if_consistent(dict1, dict2):\n common_keys = set(dict1.keys()).intersection(dict2.keys())\n for key in common_keys:\n if dict1[key] != dict2[key]:\n raise TypeError("Inconsistent values for tag {}: {} != {}".format(\n key, dict1[key], dict2[key]\n ))\n dict1.update(dict2)\n return dict1\n\n\nclass BaseEstimator:\n """Base class for all estimators in scikit-learn\n\n Notes\n -----\n All estimators should specify all the parameters that can be set\n at the class level in their ``__init__`` as explicit keyword\n arguments (no ``*args`` or ``**kwargs``).\n """\n\n @classmethod\n def _get_param_names(cls):\n """Get parameter names for the estimator"""\n # fetch the constructor or the original constructor before\n # deprecation wrapping if any\n init = getattr(cls.__init__, 'deprecated_original', cls.__init__)\n if init is object.__init__:\n # No explicit constructor to introspect\n return []\n\n # introspect the constructor arguments to find the model parameters\n # to represent\n init_signature = inspect.signature(init)\n # Consider the constructor parameters excluding 'self'\n parameters = [p for p in init_signature.parameters.values()\n if p.name != 'self' and p.kind != p.VAR_KEYWORD]\n for p in parameters:\n if p.kind == p.VAR_POSITIONAL:\n raise RuntimeError("scikit-learn estimators should always "\n "specify their parameters in the signature"\n " of their __init__ (no varargs)."\n " %s with constructor %s doesn't "\n " follow this convention."\n % (cls, init_signature))\n # Extract and sort argument names excluding 'self'\n return sorted([p.name for p in parameters])\n\n def get_params(self, deep=True):\n """Get parameters for this estimator.\n\n Parameters\n ----------\n deep : boolean, optional\n If True, will return the parameters for this estimator and\n contained subobjects that are estimators.\n\n Returns\n -------\n params : mapping of string to any\n Parameter names mapped to their values.\n """\n out = dict()\n for key in self._get_param_names():\n value = getattr(self, key, None)\n if deep and hasattr(value, 'get_params'):\n deep_items = value.get_params().items()\n out.update((key + '__' + k, val) for k, val in deep_items)\n out[key] = value\n return out\n\n def set_params(self, **params):\n """Set the parameters of this estimator.\n\n The method works on simple estimators as well as on nested objects\n (such as pipelines). The latter have parameters of the form\n ``<component>__<parameter>`` so that it's possible to update each\n component of a nested object.\n\n Returns\n -------\n self\n """\n if not params:\n # Simple optimization to gain speed (inspect is slow)\n return self\n valid_params = self.get_params(deep=True)\n\n nested_params = defaultdict(dict) # grouped by prefix\n for key, value in params.items():\n key, delim, sub_key = key.partition('__')\n if key not in valid_params:\n raise ValueError('Invalid parameter %s for estimator %s. '\n 'Check the list of available parameters '\n 'with `estimator.get_params().keys()`.' %\n (key, self))\n\n if delim:\n nested_params[key][sub_key] = value\n else:\n setattr(self, key, value)\n valid_params[key] = value\n\n for key, sub_params in nested_params.items():\n valid_params[key].set_params(**sub_params)\n\n return self\n\n def __repr__(self, N_CHAR_MAX=700):\n # N_CHAR_MAX is the (approximate) maximum number of non-blank\n # characters to render. We pass it as an optional parameter to ease\n # the tests.\n\n from .utils._pprint import _EstimatorPrettyPrinter\n\n N_MAX_ELEMENTS_TO_SHOW = 30 # number of elements to show in sequences\n\n # use ellipsis for sequences with a lot of elements\n pp = _EstimatorPrettyPrinter(\n compact=True, indent=1, indent_at_name=True,\n n_max_elements_to_show=N_MAX_ELEMENTS_TO_SHOW)\n\n repr_ = pp.pformat(self)\n\n # Use bruteforce ellipsis when there are a lot of non-blank characters\n n_nonblank = len(''.join(repr_.split()))\n if n_nonblank > N_CHAR_MAX:\n lim = N_CHAR_MAX // 2 # apprx number of chars to keep on both ends\n regex = r'^(\\s*\\S){%d}' % lim\n # The regex '^(\\s*\\S){%d}' % n\n # matches from the start of the string until the nth non-blank\n # character:\n # - ^ matches the start of string\n # - (pattern){n} matches n repetitions of pattern\n # - \\s*\\S matches a non-blank char following zero or more blanks\n left_lim = re.match(regex, repr_).end()\n right_lim = re.match(regex, repr_[::-1]).end()\n\n if '\\n' in repr_[left_lim:-right_lim]:\n # The left side and right side aren't on the same line.\n # To avoid weird cuts, e.g.:\n # categoric...ore',\n # we need to start the right side with an appropriate newline\n # character so that it renders properly as:\n # categoric...\n # handle_unknown='ignore',\n # so we add [^\\n]*\\n which matches until the next \\n\n regex += r'[^\\n]*\\n'\n right_lim = re.match(regex, repr_[::-1]).end()\n\n ellipsis = '...'\n if left_lim + len(ellipsis) < len(repr_) - right_lim:\n # Only add ellipsis if it results in a shorter repr\n repr_ = repr_[:left_lim] + '...' + repr_[-right_lim:]\n\n return repr_\n\n def __getstate__(self):\n try:\n state = super().__getstate__()\n except AttributeError:\n state = self.__dict__.copy()\n\n if type(self).__module__.startswith('sklearn.'):\n return dict(state.items(), _sklearn_version=__version__)\n else:\n return state\n\n def __setstate__(self, state):\n if type(self).__module__.startswith('sklearn.'):\n pickle_version = state.pop("_sklearn_version", "pre-0.18")\n if pickle_version != __version__:\n warnings.warn(\n "Trying to unpickle estimator {0} from version {1} when "\n "using version {2}. This might lead to breaking code or "\n "invalid results. Use at your own risk.".format(\n self.__class__.__name__, pickle_version, __version__),\n UserWarning)\n try:\n super().__setstate__(state)\n except AttributeError:\n self.__dict__.update(state)\n\n def _get_tags(self):\n collected_tags = {}\n for base_class in inspect.getmro(self.__class__):\n if (hasattr(base_class, '_more_tags')\n and base_class != self.__class__):\n more_tags = base_class._more_tags(self)\n collected_tags = _update_if_consistent(collected_tags,\n more_tags)\n if hasattr(self, '_more_tags'):\n more_tags = self._more_tags()\n collected_tags = _update_if_consistent(collected_tags, more_tags)\n tags = _DEFAULT_TAGS.copy()\n tags.update(collected_tags)\n return tags\n\n\nclass ClassifierMixin:\n """Mixin class for all classifiers in scikit-learn."""\n _estimator_type = "classifier"\n\n def score(self, X, y, sample_weight=None):\n """Returns the mean accuracy on the given test data and labels.\n\n In multi-label classification, this is the subset accuracy\n which is a harsh metric since you require for each sample that\n each label set be correctly predicted.\n\n Parameters\n ----------\n X : array-like, shape = (n_samples, n_features)\n Test samples.\n\n y : array-like, shape = (n_samples) or (n_samples, n_outputs)\n True labels for X.\n\n sample_weight : array-like, shape = [n_samples], optional\n Sample weights.\n\n Returns\n -------\n score : float\n Mean accuracy of self.predict(X) wrt. y.\n\n """\n from .metrics import accuracy_score\n return accuracy_score(y, self.predict(X), sample_weight=sample_weight)\n\n\nclass RegressorMixin:\n """Mixin class for all regression estimators in scikit-learn."""\n _estimator_type = "regressor"\n\n def score(self, X, y, sample_weight=None):\n """Returns the coefficient of determination R^2 of the prediction.\n\n The coefficient R^2 is defined as (1 - u/v), where u is the residual\n sum of squares ((y_true - y_pred) ** 2).sum() and v is the total\n sum of squares ((y_true - y_true.mean()) ** 2).sum().\n The best possible score is 1.0 and it can be negative (because the\n model can be arbitrarily worse). A constant model that always\n predicts the expected value of y, disregarding the input features,\n would get a R^2 score of 0.0.\n\n Parameters\n ----------\n X : array-like, shape = (n_samples, n_features)\n Test samples. For some estimators this may be a\n precomputed kernel matrix instead, shape = (n_samples,\n n_samples_fitted], where n_samples_fitted is the number of\n samples used in the fitting for the estimator.\n\n y : array-like, shape = (n_samples) or (n_samples, n_outputs)\n True values for X.\n\n sample_weight : array-like, shape = [n_samples], optional\n Sample weights.\n\n Returns\n -------\n score : float\n R^2 of self.predict(X) wrt. y.\n\n Notes\n -----\n The R2 score used when calling ``score`` on a regressor will use\n ``multioutput='uniform_average'`` from version 0.23 to keep consistent\n with `metrics.r2_score`. This will influence the ``score`` method of\n all the multioutput regressors (except for\n `multioutput.MultiOutputRegressor`). To specify the default value\n manually and avoid the warning, please either call `metrics.r2_score`\n directly or make a custom scorer with `metrics.make_scorer` (the\n built-in scorer ``'r2'`` uses ``multioutput='uniform_average'``).\n """\n\n from .metrics import r2_score\n from .metrics.regression import _check_reg_targets\n y_pred = self.predict(X)\n # XXX: Remove the check in 0.23\n y_type, _, _, _ = _check_reg_targets(y, y_pred, None)\n if y_type == 'continuous-multioutput':\n warnings.warn("The default value of multioutput (not exposed in "\n "score method) will change from 'variance_weighted' "\n "to 'uniform_average' in 0.23 to keep consistent "\n "with 'metrics.r2_score'. To specify the default "\n "value manually and avoid the warning, please "\n "either call 'metrics.r2_score' directly or make a "\n "custom scorer with 'metrics.make_scorer' (the "\n "built-in scorer 'r2' uses "\n "multioutput='uniform_average').", FutureWarning)\n return r2_score(y, y_pred, sample_weight=sample_weight,\n multioutput='variance_weighted')\n\n\nclass ClusterMixin:\n """Mixin class for all cluster estimators in scikit-learn."""\n _estimator_type = "clusterer"\n\n def fit_predict(self, X, y=None):\n """Performs clustering on X and returns cluster labels.\n\n Parameters\n ----------\n X : ndarray, shape (n_samples, n_features)\n Input data.\n\n y : Ignored\n not used, present for API consistency by convention.\n\n Returns\n -------\n labels : ndarray, shape (n_samples,)\n cluster labels\n """\n # non-optimized default implementation; override when a better\n # method is possible for a given clustering algorithm\n self.fit(X)\n return self.labels_\n\n\nclass BiclusterMixin:\n """Mixin class for all bicluster estimators in scikit-learn"""\n\n @property\n def biclusters_(self):\n """Convenient way to get row and column indicators together.\n\n Returns the ``rows_`` and ``columns_`` members.\n """\n return self.rows_, self.columns_\n\n def get_indices(self, i):\n """Row and column indices of the i'th bicluster.\n\n Only works if ``rows_`` and ``columns_`` attributes exist.\n\n Parameters\n ----------\n i : int\n The index of the cluster.\n\n Returns\n -------\n row_ind : np.array, dtype=np.intp\n Indices of rows in the dataset that belong to the bicluster.\n col_ind : np.array, dtype=np.intp\n Indices of columns in the dataset that belong to the bicluster.\n\n """\n rows = self.rows_[i]\n columns = self.columns_[i]\n return np.nonzero(rows)[0], np.nonzero(columns)[0]\n\n def get_shape(self, i):\n """Shape of the i'th bicluster.\n\n Parameters\n ----------\n i : int\n The index of the cluster.\n\n Returns\n -------\n shape : (int, int)\n Number of rows and columns (resp.) in the bicluster.\n """\n indices = self.get_indices(i)\n return tuple(len(i) for i in indices)\n\n def get_submatrix(self, i, data):\n """Returns the submatrix corresponding to bicluster `i`.\n\n Parameters\n ----------\n i : int\n The index of the cluster.\n data : array\n The data.\n\n Returns\n -------\n submatrix : array\n The submatrix corresponding to bicluster i.\n\n Notes\n -----\n Works with sparse matrices. Only works if ``rows_`` and\n ``columns_`` attributes exist.\n """\n from .utils.validation import check_array\n data = check_array(data, accept_sparse='csr')\n row_ind, col_ind = self.get_indices(i)\n return data[row_ind[:, np.newaxis], col_ind]\n\n\nclass TransformerMixin:\n """Mixin class for all transformers in scikit-learn."""\n\n def fit_transform(self, X, y=None, **fit_params):\n """Fit to data, then transform it.\n\n Fits transformer to X and y with optional parameters fit_params\n and returns a transformed version of X.\n\n Parameters\n ----------\n X : numpy array of shape [n_samples, n_features]\n Training set.\n\n y : numpy array of shape [n_samples]\n Target values.\n\n Returns\n -------\n X_new : numpy array of shape [n_samples, n_features_new]\n Transformed array.\n\n """\n # non-optimized default implementation; override when a better\n # method is possible for a given clustering algorithm\n if y is None:\n # fit method of arity 1 (unsupervised transformation)\n return self.fit(X, **fit_params).transform(X)\n else:\n # fit method of arity 2 (supervised transformation)\n return self.fit(X, y, **fit_params).transform(X)\n\n\nclass DensityMixin:\n """Mixin class for all density estimators in scikit-learn."""\n _estimator_type = "DensityEstimator"\n\n def score(self, X, y=None):\n """Returns the score of the model on the data X\n\n Parameters\n ----------\n X : array-like, shape = (n_samples, n_features)\n\n Returns\n -------\n score : float\n """\n pass\n\n\nclass OutlierMixin:\n """Mixin class for all outlier detection estimators in scikit-learn."""\n _estimator_type = "outlier_detector"\n\n def fit_predict(self, X, y=None):\n """Performs fit on X and returns labels for X.\n\n Returns -1 for outliers and 1 for inliers.\n\n Parameters\n ----------\n X : ndarray, shape (n_samples, n_features)\n Input data.\n\n y : Ignored\n not used, present for API consistency by convention.\n\n Returns\n -------\n y : ndarray, shape (n_samples,)\n 1 for inliers, -1 for outliers.\n """\n # override for transductive outlier detectors like LocalOulierFactor\n return self.fit(X).predict(X)\n\n\nclass MetaEstimatorMixin:\n _required_parameters = ["estimator"]\n """Mixin class for all meta estimators in scikit-learn."""\n\n\nclass MultiOutputMixin(object):\n """Mixin to mark estimators that support multioutput."""\n def _more_tags(self):\n return {'multioutput': True}\n\n\nclass _UnstableArchMixin(object):\n """Mark estimators that are non-determinstic on 32bit or PowerPC"""\n def _more_tags(self):\n return {'non_deterministic': (\n _IS_32BIT or platform.machine().startswith(('ppc', 'powerpc')))}\n\n\ndef is_classifier(estimator):\n """Returns True if the given estimator is (probably) a classifier.\n\n Parameters\n ----------\n estimator : object\n Estimator object to test.\n\n Returns\n -------\n out : bool\n True if estimator is a classifier and False otherwise.\n """\n return getattr(estimator, "_estimator_type", None) == "classifier"\n\n\ndef is_regressor(estimator):\n """Returns True if the given estimator is (probably) a regressor.\n\n Parameters\n ----------\n estimator : object\n Estimator object to test.\n\n Returns\n -------\n out : bool\n True if estimator is a regressor and False otherwise.\n """\n return getattr(estimator, "_estimator_type", None) == "regressor"\n\n\ndef is_outlier_detector(estimator):\n """Returns True if the given estimator is (probably) an outlier detector.\n\n Parameters\n ----------\n estimator : object\n Estimator object to test.\n\n Returns\n -------\n out : bool\n True if estimator is an outlier detector and False otherwise.\n """\n return getattr(estimator, "_estimator_type", None) == "outlier_detector"\n