qminer
Version:
A C++ based data analytics platform for processing large-scale real-time streams containing structured and unstructured data
732 lines (728 loc) • 31.1 kB
HTML
<html>
<head>
<meta name="generator" content="JSDoc 3">
<meta charset="utf-8">
<title>Class: KMeans</title>
<link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Karla:400,400i,700,700i" type="text/css">
<link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Noto+Serif:400,400i,700,700i" type="text/css">
<link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Inconsolata:500" type="text/css">
<link href="css/baseline.css" rel="stylesheet">
</head>
<body onload="prettyPrint()">
<nav id="jsdoc-navbar" role="navigation" class="jsdoc-navbar">
<div id="jsdoc-navbar-container">
<div id="jsdoc-navbar-content">
<a href="index.html" class="jsdoc-navbar-package-name">QMiner JavaScript API v9.4.0</a>
</div>
</div>
</nav>
<div id="jsdoc-body-container">
<div id="jsdoc-content">
<div id="jsdoc-content-container">
<div id="jsdoc-main" role="main">
<header class="page-header">
<div class="symbol-detail-labels"><span class="label label-kind">class</span> <span class="label label-static">static</span></div>
<h1><small><a href="module-analytics.html">analytics</a>.<wbr></small><span class="symbol-name">KMeans</span></h1>
<p class="source-link">Source: <a href="analyticsdoc.js.html#source-line-1705">analyticsdoc.<wbr>js:1705</a></p>
<div class="symbol-classdesc">
<p>KMeans Clustering is an iterative, data-partitioning algorithm that assigns observations into K clusters.</p>
</div>
<dl class="dl-compact">
</dl>
</header>
<section id="summary">
<div class="summary-callout">
<h2 class="summary-callout-heading">Properties</h2>
<div class="summary-content">
<div class="summary-column">
<dl class="dl-summary-callout">
<dt><a href="module-analytics.KMeans.html#centroids">centroids</a></dt>
<dd>
</dd>
<dt><a href="module-analytics.KMeans.html#idxv">idxv</a></dt>
<dd>
</dd>
</dl>
</div>
<div class="summary-column">
<dl class="dl-summary-callout">
<dt><a href="module-analytics.KMeans.html#medoids">medoids</a></dt>
<dd>
</dd>
<dt><a href="module-analytics.KMeans.html#relMeanCentroidDist">relMeanCentroidDist</a></dt>
<dd>
</dd>
</dl>
</div>
<div class="summary-column">
</div>
</div>
</div>
<div class="summary-callout">
<h2 class="summary-callout-heading">Methods</h2>
<div class="summary-content">
<div class="summary-column">
<dl class="dl-summary-callout">
<dt><a href="module-analytics.KMeans.html#explain">explain(X)</a></dt>
<dd>
</dd>
<dt><a href="module-analytics.KMeans.html#fit">fit(X)</a></dt>
<dd>
</dd>
<dt><a href="module-analytics.KMeans.html#getModel">getModel()</a></dt>
<dd>
</dd>
</dl>
</div>
<div class="summary-column">
<dl class="dl-summary-callout">
<dt><a href="module-analytics.KMeans.html#getParams">getParams()</a></dt>
<dd>
</dd>
<dt><a href="module-analytics.KMeans.html#permuteCentroids">permuteCentroids(mapping)</a></dt>
<dd>
</dd>
<dt><a href="module-analytics.KMeans.html#predict">predict(A)</a></dt>
<dd>
</dd>
</dl>
</div>
<div class="summary-column">
<dl class="dl-summary-callout">
<dt><a href="module-analytics.KMeans.html#save">save(fout)</a></dt>
<dd>
</dd>
<dt><a href="module-analytics.KMeans.html#setParams">setParams(params)</a></dt>
<dd>
</dd>
<dt><a href="module-analytics.KMeans.html#transform">transform(A)</a></dt>
<dd>
</dd>
</dl>
</div>
</div>
</div>
</section>
<section>
<h2 id="KMeans">new <span class="symbol-name">KMeans</span><span class="signature"><span class="signature-params">([arg])</span></span></h2>
<p>KMeans Clustering</p>
<section>
<h3>
Example
</h3>
<div>
<pre class="prettyprint"><code>// 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);</code></pre>
</div>
</section>
<section>
<h3>Parameter</h3>
<table class="jsdoc-details-table">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Optional</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>arg</p>
</td>
<td>
<p>(<a href="module-analytics.html#~KMeansParam">module:analytics~KMeansParam</a> or <a href="module-fs.FIn.html">module:fs.FIn</a>)</p>
</td>
<td>
<p>Yes</p>
</td>
<td>
<p>Construction arguments. There are two ways of constructing:
<br>1. Using the <a href="module-analytics.html#~KMeansParam">module:analytics~KMeansParam</a> object,
<br>2. using the file input stream <a href="module-fs.FIn.html">module:fs.FIn</a>.
</p>
</td>
</tr>
</tbody>
</table>
</section>
<dl class="dl-compact">
</dl>
</section>
<section>
<h2>Properties</h2>
<section>
<h3 id="centroids"><span class="symbol-name">centroids</span></h3>
<p>The centroids created with the fit method. Type <a href="module-la.Matrix.html">module:la.Matrix</a>.</p>
<section>
<h4>
Example
</h4>
<div>
<pre class="prettyprint"><code>// 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;</code></pre>
</div>
</section>
<dl class="dl-compact">
</dl>
<h3 id="idxv"><span class="symbol-name">idxv</span></h3>
<p>The integer vector containing the cluster ids of the training set created with the fit method. Type <a href="module-la.IntVector.html">module:la.IntVector</a>.</p>
<section>
<h4>
Example
</h4>
<div>
<pre class="prettyprint"><code>// 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;</code></pre>
</div>
</section>
<dl class="dl-compact">
</dl>
<h3 id="medoids"><span class="symbol-name">medoids</span></h3>
<p>The medoids created with the fit method. Type <a href="module-la.IntVector.html">module:la.IntVector</a>.</p>
<section>
<h4>
Example
</h4>
<div>
<pre class="prettyprint"><code>// 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;</code></pre>
</div>
</section>
<dl class="dl-compact">
</dl>
<h3 id="relMeanCentroidDist"><span class="symbol-name">relMeanCentroidDist</span></h3>
<p>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)}</p>
<dl class="dl-compact">
<dt>Returns</dt>
<dd>
<p><code>number</code>B relMeanDist</p>
</dd>
</dl>
</section>
<h2>Methods</h2>
<section>
<h3 id="explain"><span class="symbol-name">explain</span><span class="signature"><span class="signature-params">(X)</span> → <span class="signature-returns"> Array of <a href="module-analytics.html#~KMeansExplain">module:analytics~KMeansExplain</a></span></span></h3>
<p>Returns the IDs of the nearest medoid for each example.</p>
<section>
<h4>
Example
</h4>
<div>
<pre class="prettyprint"><code>// 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);</code></pre>
</div>
</section>
<section>
<h4>Parameter</h4>
<table class="jsdoc-details-table">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Optional</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>X</p>
</td>
<td>
<p>(<a href="module-la.Matrix.html">module:la.Matrix</a> or <a href="module-la.SparseMatrix.html">module:la.SparseMatrix</a>)</p>
</td>
<td>
<p> </p>
</td>
<td>
<p>Matrix whose columns correspond to examples.</p>
</td>
</tr>
</tbody>
</table>
</section>
<dl class="dl-compact">
<dt>Returns</dt>
<dd>
<p><code>Array of <a href="module-analytics.html#~KMeansExplain">module:analytics~KMeansExplain</a></code>B Array containing the KMeans explanantions.</p>
</dd>
</dl>
<h3 id="fit"><span class="symbol-name">fit</span><span class="signature"><span class="signature-params">(X)</span> → <span class="signature-returns"> <a href="module-analytics.KMeans.html">module:analytics.KMeans</a></span></span></h3>
<p>Calculates the centroids.</p>
<section>
<h4>
Examples
</h4>
<div>
<p> Asynchronous function </p>
<pre class="prettyprint"><code>// 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
});</code></pre>
</div>
<div>
<p> Synchronous function </p>
<pre class="prettyprint"><code>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);</code></pre>
</div>
</section>
<section>
<h4>Parameter</h4>
<table class="jsdoc-details-table">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Optional</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>X</p>
</td>
<td>
<p>(<a href="module-la.Matrix.html">module:la.Matrix</a> or <a href="module-la.SparseMatrix.html">module:la.SparseMatrix</a>)</p>
</td>
<td>
<p> </p>
</td>
<td>
<p>Matrix whose columns correspond to examples.</p>
</td>
</tr>
</tbody>
</table>
</section>
<dl class="dl-compact">
<dt>Returns</dt>
<dd>
<p><code><a href="module-analytics.KMeans.html">module:analytics.KMeans</a></code>B Self. The model has been updated.</p>
</dd>
</dl>
<h3 id="getModel"><span class="symbol-name">getModel</span><span class="signature"><span class="signature-params">()</span> → <span class="signature-returns"> Object</span></span></h3>
<p>Returns the model.</p>
<section>
<h4>
Example
</h4>
<div>
<pre class="prettyprint"><code>// 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();</code></pre>
</div>
</section>
<dl class="dl-compact">
<dt>Returns</dt>
<dd>
<p><code>Object</code>B The <code>KMeansModel</code> object containing the properites:
<br> 1. <code>KMeansModel.C</code> - The <a href="module-la.Matrix.html">module:la.Matrix</a> or <a href="module-la.SparseMatrix.html">module:la.SparseMatrix</a> containing the centroids,
<br> 2. <code>KMeansModel.medoids</code> - The <a href="module-la.IntVector.html">module:la.IntVector</a> of cluster medoids of the training data,
<br> 3. <code>KMeansModel.idxv</code> - The <a href="module-la.IntVector.html">module:la.IntVector</a> of cluster IDs of the training data.
</p>
</dd>
</dl>
<h3 id="getParams"><span class="symbol-name">getParams</span><span class="signature"><span class="signature-params">()</span> → <span class="signature-returns"> <a href="module-analytics.html#~KMeansParam">module:analytics~KMeansParam</a></span></span></h3>
<p>Returns the parameters.</p>
<section>
<h4>
Example
</h4>
<div>
<pre class="prettyprint"><code>// 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();</code></pre>
</div>
</section>
<dl class="dl-compact">
<dt>Returns</dt>
<dd>
<p><code><a href="module-analytics.html#~KMeansParam">module:analytics~KMeansParam</a></code>B The construction parameters.</p>
</dd>
</dl>
<h3 id="permuteCentroids"><span class="symbol-name">permuteCentroids</span><span class="signature"><span class="signature-params">(mapping)</span> → <span class="signature-returns"> <a href="module-analytics.KMeans.html">module:analytics.KMeans</a></span></span></h3>
<p>Permutates the clusters, and with it <a href="module-analytics.KMeans.html#centroids">module:analytics.KMeans#centroids</a>, <a href="module-analytics.KMeans.html#medoids">module:analytics.KMeans#medoids</a> and <a href="module-analytics.KMeans.html#idxv">module:analytics.KMeans#idxv</a>.</p>
<section>
<h4>
Example
</h4>
<div>
<pre class="prettyprint"><code>// 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);</code></pre>
</div>
</section>
<section>
<h4>Parameter</h4>
<table class="jsdoc-details-table">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Optional</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>mapping</p>
</td>
<td>
<p><a href="module-la.IntVector.html">module:la.IntVector</a></p>
</td>
<td>
<p> </p>
</td>
<td>
<p>The mapping, where <code>mapping[4] = 2</code> means "map cluster 4 into cluster 2".</p>
</td>
</tr>
</tbody>
</table>
</section>
<dl class="dl-compact">
<dt>Returns</dt>
<dd>
<p><code><a href="module-analytics.KMeans.html">module:analytics.KMeans</a></code>B Self. The clusters has been permutated.</p>
</dd>
</dl>
<h3 id="predict"><span class="symbol-name">predict</span><span class="signature"><span class="signature-params">(A)</span> → <span class="signature-returns"> <a href="module-la.IntVector.html">module:la.IntVector</a></span></span></h3>
<p>Returns an vector of cluster id assignments.</p>
<section>
<h4>
Example
</h4>
<div>
<pre class="prettyprint"><code>// 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);</code></pre>
</div>
</section>
<section>
<h4>Parameter</h4>
<table class="jsdoc-details-table">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Optional</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>A</p>
</td>
<td>
<p>(<a href="module-la.Matrix.html">module:la.Matrix</a> or <a href="module-la.SparseMatrix.html">module:la.SparseMatrix</a>)</p>
</td>
<td>
<p> </p>
</td>
<td>
<p>Matrix whose columns correspond to examples.</p>
</td>
</tr>
</tbody>
</table>
</section>
<dl class="dl-compact">
<dt>Returns</dt>
<dd>
<p><code><a href="module-la.IntVector.html">module:la.IntVector</a></code>B Vector of cluster assignments.</p>
</dd>
</dl>
<h3 id="save"><span class="symbol-name">save</span><span class="signature"><span class="signature-params">(fout)</span> → <span class="signature-returns"> <a href="module-fs.FOut.html">module:fs.FOut</a></span></span></h3>
<p>Saves KMeans internal state into (binary) file.</p>
<section>
<h4>
Example
</h4>
<div>
<pre class="prettyprint"><code>// 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);</code></pre>
</div>
</section>
<section>
<h4>Parameter</h4>
<table class="jsdoc-details-table">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Optional</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>fout</p>
</td>
<td>
<p><a href="module-fs.FOut.html">module:fs.FOut</a></p>
</td>
<td>
<p> </p>
</td>
<td>
<p>The output stream.</p>
</td>
</tr>
</tbody>
</table>
</section>
<dl class="dl-compact">
<dt>Returns</dt>
<dd>
<p><code><a href="module-fs.FOut.html">module:fs.FOut</a></code>B The output stream <code>fout</code>.</p>
</dd>
</dl>
<h3 id="setParams"><span class="symbol-name">setParams</span><span class="signature"><span class="signature-params">(params)</span> → <span class="signature-returns"> <a href="module-analytics.KMeans.html">module:analytics.KMeans</a></span></span></h3>
<p>Sets the parameters.</p>
<section>
<h4>
Example
</h4>
<div>
<pre class="prettyprint"><code>// 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 });</code></pre>
</div>
</section>
<section>
<h4>Parameter</h4>
<table class="jsdoc-details-table">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Optional</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>params</p>
</td>
<td>
<p><a href="module-analytics.html#~KMeansParam">module:analytics~KMeansParam</a></p>
</td>
<td>
<p> </p>
</td>
<td>
<p>The construction parameters.</p>
</td>
</tr>
</tbody>
</table>
</section>
<dl class="dl-compact">
<dt>Returns</dt>
<dd>
<p><code><a href="module-analytics.KMeans.html">module:analytics.KMeans</a></code>B Self. The model parameters have been updated.</p>
</dd>
</dl>
<h3 id="transform"><span class="symbol-name">transform</span><span class="signature"><span class="signature-params">(A)</span> → <span class="signature-returns"> <a href="module-la.Matrix.html">module:la.Matrix</a></span></span></h3>
<p>Transforms the points to vectors of distances to centroids.</p>
<section>
<h4>
Example
</h4>
<div>
<pre class="prettyprint"><code>// 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);</code></pre>
</div>
</section>
<section>
<h4>Parameter</h4>
<table class="jsdoc-details-table">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Optional</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>A</p>
</td>
<td>
<p>(<a href="module-la.Matrix.html">module:la.Matrix</a> or <a href="module-la.SparseMatrix.html">module:la.SparseMatrix</a>)</p>
</td>
<td>
<p> </p>
</td>
<td>
<p>Matrix whose columns correspond to examples.</p>
</td>
</tr>
</tbody>
</table>
</section>
<dl class="dl-compact">
<dt>Returns</dt>
<dd>
<p><code><a href="module-la.Matrix.html">module:la.Matrix</a></code>B Matrix where each column represents the squared distances to the centroid vectors.</p>
</dd>
</dl>
</section>
</section>
</div>
</div>
<nav id="jsdoc-toc-nav" role="navigation"></nav>
</div>
</div>
<footer id="jsdoc-footer" class="jsdoc-footer">
<div id="jsdoc-footer-container">
<p>
</p>
</div>
</footer>
<script src="scripts/jquery.min.js"></script>
<script src="scripts/tree.jquery.js"></script>
<script src="scripts/prettify.js"></script>
<script src="scripts/jsdoc-toc.js"></script>
<script src="scripts/linenumber.js"></script>
<script src="scripts/scrollanchor.js"></script>
</body>
</html>