## Properties

centroids
idxv

medoids
relMeanCentroidDist

## Methods

explain(X)
fit(X)
getModel()

getParams()
permuteCentroids(mapping)
predict(A)

save(fout)
setParams(params)
transform(A)

## new KMeans([arg])

KMeans Clustering

### Example

    // import analytics and la modules
    var analytics = require('qminer').analytics;
    var la = require('qminer').la;
    // create a KMeans object
    var KMeans = new analytics.KMeans();
    // create the matrix to be fitted
    var X = new la.Matrix([[1, -2, -1], [1, 1, -3]]);
    // create the model
    KMeans.fit(X);
    // predict where the columns of the matrix will be assigned
    var Y = new la.Matrix([[1, 1, 0], [-2, 3, 1]]);
    var prediction = KMeans.predict(Y);

### Parameter

Name | Type | Optional | Description
--- | --- | --- | ---
arg | (module:analytics~KMeansParam or module:fs.FIn) | Yes | Construction arguments. There are two ways of constructing: 1. Using the module:analytics~KMeansParam object, 2. using the file input stream module:fs.FIn.

## Properties

### centroids

The centroids created with the fit method. Type module:la.Matrix.

#### Example

    // import the modules
    var analytics = require('qminer').analytics;
    // create a new KMeans object
    var KMeans = new analytics.KMeans({ iter: 1000, k: 3 });
    // create a matrix to be fitted
    var X = new la.Matrix([[1, -2, -1], [1, 1, -3]]);
    // create the model with the matrix X
    KMeans.fit(X);
    // get the centroids
    var centroids = KMeans.centroids;

### idxv

The integer vector containing the cluster ids of the training set created with the fit method. Type module:la.IntVector.

#### Example

    // import the modules
    var analytics = require('qminer').analytics;
    // create a new KMeans object
    var KMeans = new analytics.KMeans({ iter: 1000, k: 3 });
    // create a matrix to be fitted
    var X = new la.Matrix([[1, -2, -1], [1, 1, -3]]);
    // create the model with the matrix X
    KMeans.fit(X);
    // get the idxv
    var idxv = KMeans.idxv;

### medoids

The medoids created with the fit method. Type module:la.IntVector.

#### Example

    // import the modules
    var analytics = require('qminer').analytics;
    // create a new KMeans object
    var KMeans = new analytics.KMeans({ iter: 1000, k: 3 });
    // create a matrix to be fitted
    var X = new la.Matrix([[1, -2, -1], [1, 1, -3]]);
    // create the model with the matrix X
    KMeans.fit(X);
    // get the centroids
    var medoids = KMeans.medoids;

### relMeanCentroidDist

Returns the normalized weighted distance between the vectors and their centroids using the following formula: d = \frac{sum_i p_i*sum_j d(x_j,c_i) / n_i}{sum_{k=1}^n d(x_k, mu) / n} = \frac{sum_{i,j} d(c_i,x_j)}{sum_k d(x_k, mu)}

Returns

  `number`B relMeanDist

## Methods

### explain(X) → Array of module:analytics~KMeansExplain

Returns the IDs of the nearest medoid for each example.

#### Example

    // import analytics module
    var analytics = require('qminer').analytics;
    // import linear algebra module
    var la = require('qminer').la;
    // create a new KMeans object
    var KMeans = new analytics.KMeans({ iter: 1000, k: 3 });
    // create a matrix to be fitted
    var X = new la.Matrix([[1, -2, -1], [1, 1, -3]]);
    // create the model with the matrix X using the column IDs [0,1,2]
    KMeans.fit(X, [1234,1142,2355]);
    // create the matrix of the prediction vectors
    var test = new la.Matrix([[2, -1, 1], [1, 0, -3]]);
    // predict/explain - return the closest medoids
    var explanation = KMeans.explain(test);

#### Parameter

Name | Type | Optional | Description
--- | --- | --- | ---
X | (module:la.Matrix or module:la.SparseMatrix) |  | Matrix whose columns correspond to examples.

Returns

  `Array of module:analytics~KMeansExplain`B Array containing the KMeans explanantions.

### fit(X) → module:analytics.KMeans

Calculates the centroids.

#### Examples

Asynchronous function

    // import analytics module
    var analytics = require('qminer').analytics;
    var la = require('qminer').la;
    // create a new KMeans object
    var KMeans = new analytics.KMeans({ iter: 1000, k: 3 });
    // create a matrix to be fitted
    var X = new la.Matrix([[1, -2, -1], [1, 1, -3]]);
    // create the model with the matrix X
    KMeans.fitAsync(X, function (err) {
        if (err) console.log(err);
        // successful calculation
    });

Synchronous function

    var analytics = require('qminer').analytics;
    var la = require('qminer').la;
    // create a new KMeans object
    var KMeans = new analytics.KMeans({ iter: 1000, k: 3 });
    // create a matrix to be fitted
    var X = new la.Matrix([[1, -2, -1], [1, 1, -3]]);
    // create the model with the matrix X
    KMeans.fit(X);

#### Parameter

Name | Type | Optional | Description
--- | --- | --- | ---
X | (module:la.Matrix or module:la.SparseMatrix) |  | Matrix whose columns correspond to examples.

Returns

  `module:analytics.KMeans`B Self. The model has been updated.

### getModel() → Object

Returns the model.

#### Example

    // import modules
    var analytics = require('qminer').analytics;
    var la = require('qminer').la;
    // create the KMeans object
    var KMeans = new analytics.KMeans({ iter: 1000 });
    // create a matrix to be fitted
    var X = new la.Matrix([[1, -2, -1], [1, 1, -3]]);
    // create the model
    KMeans.fit(X);
    // get the model
    var model = KMeans.getModel();

Returns

  `Object`B The `KMeansModel` object containing the properites:
  1. `KMeansModel.C` - The module:la.Matrix or module:la.SparseMatrix containing the centroids,
  2. `KMeansModel.medoids` - The module:la.IntVector of cluster medoids of the training data,
  3. `KMeansModel.idxv` - The module:la.IntVector of cluster IDs of the training data.

### getParams() → module:analytics~KMeansParam

Returns the parameters.

#### Example

    // import analytics module
    var analytics = require('qminer').analytics;
    // create a new KMeans object
    var KMeans = new analytics.KMeans({ iter: 1000, k: 5 });
    // get the parameters
    var json = KMeans.getParams();

Returns

  `module:analytics~KMeansParam`B The construction parameters.

### permuteCentroids(mapping) → module:analytics.KMeans

Permutates the clusters, and with it module:analytics.KMeans#centroids, module:analytics.KMeans#medoids and module:analytics.KMeans#idxv.

#### Example

    // import the modules
    var analytics = require('qminer').analytics;
    var la = require('qminer').la;
    // create a new KMeans object
    var KMeans = new analytics.KMeans({ iter: 1000, k: 3 });
    // create a matrix to be fitted
    var X = new la.Matrix([[1, -2, -1], [1, 1, -3]]);
    // create the model with the matrix X
    KMeans.fit(X);
    // create the mapping vector
    var Mapping = new la.IntVector([1, 0, 2]);
    // permutate the clusters.
    KMeans.permuteCentroids(Mapping);

#### Parameter

Name | Type | Optional | Description
--- | --- | --- | ---
mapping | module:la.IntVector |  | The mapping, where `mapping[4] = 2` means "map cluster 4 into cluster 2".

Returns

  `module:analytics.KMeans`B Self. The clusters has been permutated.

### predict(A) → module:la.IntVector

Returns an vector of cluster id assignments.

#### Example

    // import analytics module
    var analytics = require('qminer').analytics;
    var la = require('qminer').la;
    // create a new KMeans object
    var KMeans = new analytics.KMeans({ iter: 1000, k: 3 });
    // create a matrix to be fitted
    var X = new la.Matrix([[1, -2, -1], [1, 1, -3]]);
    // create the model with the matrix X
    KMeans.fit(X);
    // create the matrix of the prediction vectors
    var pred = new la.Matrix([[2, -1, 1], [1, 0, -3]]);
    // predict the values
    var prediction = KMeans.predict(pred);

#### Parameter

Name | Type | Optional | Description
--- | --- | --- | ---
A | (module:la.Matrix or module:la.SparseMatrix) |  | Matrix whose columns correspond to examples.

Returns

  `module:la.IntVector`B Vector of cluster assignments.

### save(fout) → module:fs.FOut

Saves KMeans internal state into (binary) file.

#### Example

    // import the modules
    var analytics = require('qminer').analytics;
    var la = require('qminer').la;
    var fs = require('qminer').fs;
    // create a new KMeans object
    var KMeans = new analytics.KMeans({ iter: 1000, k: 3 });
    // create a matrix to be fitted
    var X = new la.Matrix([[1, -2, -1], [1, 1, -3]]);
    // create the model with the matrix X
    KMeans.fit(X);
    // create the file output stream
    var fout = new fs.openWrite('KMeans.bin');
    // save the KMeans instance
    KMeans.save(fout);
    fout.close();
    // load the KMeans instance
    var fin = fs.openRead('KMeans.bin');
    var KMeans2 = new analytics.KMeans(fin);

#### Parameter

Name | Type | Optional | Description
--- | --- | --- | ---
fout | module:fs.FOut |  | The output stream.

Returns

  `module:fs.FOut`B The output stream `fout`.

### setParams(params) → module:analytics.KMeans

Sets the parameters.

#### Example

    // import analytics module
    var analytics = require('qminer').analytics;
    // create a new KMeans object
    var KMeans = new analytics.KMeans();
    // change the parameters of the KMeans object
    KMeans.setParams({ iter: 1000, k: 5 });

#### Parameter

Name | Type | Optional | Description
--- | --- | --- | ---
params | module:analytics~KMeansParam |  | The construction parameters.

Returns

  `module:analytics.KMeans`B Self. The model parameters have been updated.

### transform(A) → module:la.Matrix

Transforms the points to vectors of distances to centroids.

#### Example

    // import modules
    var analytics = require('qminer').analytics;
    var la = require('qminer').la;
    // create a new KMeans object
    var KMeans = new analytics.KMeans({ iter: 1000, k: 3 });
    // create a matrix to be fitted
    var X = new la.Matrix([[1, -2, -1], [1, 1, -3]]);
    // create the model with the matrix X
    KMeans.fit(X);
    // create the matrix of the transform vectors
    var matrix = new la.Matrix([[-2, 0], [0, -3]]);
    // get the transform values of matrix
    // returns the matrix
    //  10    17
    //   1    20
    //  10     1
    KMeans.transform(matrix);

#### Parameter

Name | Type | Optional | Description
--- | --- | --- | ---
A | (module:la.Matrix or module:la.SparseMatrix) |  | Matrix whose columns correspond to examples.

Returns

  `module:la.Matrix`B Matrix where each column represents the squared distances to the centroid vectors.