KMeansTrainer Class

Definition

Namespace:

Microsoft.ML.Trainers

Assembly:

Microsoft.ML.KMeansClustering.dll

Package:

Microsoft.ML v3.0.1

The IEstimator<TTransformer> for training a KMeans clusterer

public class KMeansTrainer : Microsoft.ML.Trainers.TrainerEstimatorBase<Microsoft.ML.Data.ClusteringPredictionTransformer<Microsoft.ML.Trainers.KMeansModelParameters>,Microsoft.ML.Trainers.KMeansModelParameters>

type KMeansTrainer = class
    inherit TrainerEstimatorBase<ClusteringPredictionTransformer<KMeansModelParameters>, KMeansModelParameters>

Public Class KMeansTrainer
Inherits TrainerEstimatorBase(Of ClusteringPredictionTransformer(Of KMeansModelParameters), KMeansModelParameters)

Inheritance

Object

TrainerEstimatorBase<ClusteringPredictionTransformer<KMeansModelParameters>,KMeansModelParameters>

KMeansTrainer

Remarks

To create this trainer, use KMeans or Kmeans(Options).

Input and Output Columns

The input features column data must be Single. No label column needed. This trainer outputs the following columns:

Output Column Name	Column Type	Description
Score	vector of Single	The distances of the given data point to all clusters' centroids.
PredictedLabel	key type	The closest cluster's index predicted by the model.

Trainer Characteristics

Machine learning task	Clustering
Is normalization required?	Yes
Is caching required?	Yes
Required NuGet in addition to Microsoft.ML	None
Exportable to ONNX	Yes

Training Algorithm Details

K-means is a popular clustering algorithm. With K-means, the data is clustered into a specified number of clusters in order to minimize the within-cluster sum of squared distances. This implementation follows the Yinyang K-means method. For choosing the initial cluster centeroids, one of three options can be used:

• Random initialization. This might lead to potentially bad approximations of the optimal clustering.
• The K-means++ method. This is an improved initialization algorithm introduced here by Ding et al., that guarantees to find a solution that is $O(log K)$ competitive to the optimal K-means solution.
• The K-means|| method. This method was introduced here by Bahmani et al., and uses a parallel method that drastically reduces the number of passes needed to obtain a good initialization.

K-means|| is the default initialization method. The other methods can be specified in the Options when creating the trainer using KMeansTrainer(Options).

Scoring Function

The output Score column contains the square of the $L_2$-norm distance (i.e., Euclidean distance) of the given input vector $\textbf{x}\in \mathbb{R}^n$ to each cluster's centroid. Assume that the centriod of the $c$-th cluster is $\textbf{m}_c \in \mathbb{R}^n$. The $c$-th value at the Score column would be $d_c = || \textbf{x} - \textbf{m}_c ||_2^2$. The predicted label is the index with the smallest value in a $K$ dimensional vector $[d_{0}, \dots, d_{K-1}]$, where $K$ is the number of clusters.

For more information on K-means, and K-means++ see: K-means K-means++

Check the See Also section for links to usage examples.

Fields

FeatureColumn	The feature column that the trainer expects. (Inherited from TrainerEstimatorBase<TTransformer,TModel>)
LabelColumn	The label column that the trainer expects. Can be null, which indicates that label is not used for training. (Inherited from TrainerEstimatorBase<TTransformer,TModel>)
WeightColumn	The weight column that the trainer expects. Can be null, which indicates that weight is not used for training. (Inherited from TrainerEstimatorBase<TTransformer,TModel>)

Properties

Info

Methods

Fit(IDataView)	Trains and returns a ITransformer. (Inherited from TrainerEstimatorBase<TTransformer,TModel>)
GetOutputSchema(SchemaShape)	(Inherited from TrainerEstimatorBase<TTransformer,TModel>)

Extension Methods

AppendCacheCheckpoint<TTrans>(IEstimator<TTrans>, IHostEnvironment)

Append a 'caching checkpoint' to the estimator chain. This will ensure that the downstream estimators will be trained against cached data. It is helpful to have a caching checkpoint before trainers that take multiple data passes.

WithOnFitDelegate<TTransformer>(IEstimator<TTransformer>, Action<TTransformer>)

Given an estimator, return a wrapping object that will call a delegate once Fit(IDataView) is called. It is often important for an estimator to return information about what was fit, which is why the Fit(IDataView) method returns a specifically typed object, rather than just a general ITransformer. However, at the same time, IEstimator<TTransformer> are often formed into pipelines with many objects, so we may need to build a chain of estimators via EstimatorChain<TLastTransformer> where the estimator for which we want to get the transformer is buried somewhere in this chain. For that scenario, we can through this method attach a delegate that will be called once fit is called.

See also

• KMeansTrainer