phynexis-deps/armadillo-code
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

rework docs for kmeans, gmm_diag, gmm_full

Browse Source
This commit is contained in:
conrad
2024-01-29 15:17:42 +10:00
parent ef4736878b
commit 614f2a9c68
1 changed files with 45 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs.html
+45 -44
View File
@@ -198,12 +198,16 @@ Citations are useful for the continued development and maintenance of the librar
<br>
Conrad Sanderson and Ryan Curtin.
<br><i><a href="armadillo_joss_2016.pdf">Armadillo: a template-based C++ library for linear algebra</a></i>.
<br>Journal of Open Source Software, Vol.&nbsp;1, No.&nbsp;2, pp.&nbsp;26, 2016.
<br>Journal of Open Source Software, Vol.&thinsp;1, No.&thinsp;2, pp.&thinsp;26, 2016.
<br>
<br>
Conrad Sanderson and Ryan Curtin.
<!--
<br><i><a href="armadillo_mca_2019.pdf">Practical Sparse Matrices in C++ with Hybrid Storage and Template-Based Expression Optimisation</a></i>.
<br>Mathematical and Computational Applications, Vol.&thinsp;24, No.&thinsp;3, 2019.
-->
<br><i><a href="armadillo_lncs_2018.pdf">A User-Friendly Hybrid Sparse Matrix Class in C++</a></i>.
<br>Lecture Notes in Computer Science (LNCS), Vol.&nbsp;10931, pp.&nbsp;422-430, 2018.
<br>Lecture Notes in Computer Science (LNCS), Vol.&thinsp;10931, pp.&thinsp;422-430, 2018.
</li>
</ul>
</td>
@@ -536,7 +540,7 @@ Conrad Sanderson and Ryan Curtin.
<tr style="background-color: #F5F5F5;"><td><a href="#running_stat">running_stat</a></td><td>&nbsp;</td><td>running statistics of scalars (one dimensional process/signal)</td></tr>
<tr style="background-color: #F5F5F5;"><td><a href="#running_stat_vec">running_stat_vec</a></td><td>&nbsp;</td><td>running statistics of vectors (multi-dimensional process/signal)</td></tr>
<tr><td><a href="#kmeans">kmeans</a></td><td>&nbsp;</td><td>cluster data into disjoint sets</td></tr>
<tr><td><a href="#gmm_diag">gmm_diag/gmm_full</a></td><td>&nbsp;</td><td>model and evaluate data using Gaussian Mixture Models (GMMs)</td></tr>
<tr><td><a href="#gmm_diag">gmm_diag/gmm_full</a></td><td>&nbsp;</td><td>probabilistic clustering and likelihood calculation via Gaussian mixture models</td></tr>
</tbody>
</table>
</ul>
@@ -15409,14 +15413,14 @@ See also:
<ul>
<li><a href="#cov">cov()</a></li>
<li><a href="#cor">cor()</a></li>
<li><a href="#diff">diff()</a></li>
<li><a href="#hist">hist()</a></li>
<li><a href="#histc">histc()</a></li>
<li><a href="#quantile">quantile()</a></li>
<li><a href="#normpdf">normpdf()</a></li>
<li><a href="#min_and_max">min() &amp; max()</a></li>
<li><a href="#running_stat">running_stat</a> - class for running statistics of scalars</li>
<li><a href="#running_stat_vec">running_stat_vec</a> - class for running statistics of vectors</li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - model and evaluate data using Gaussian Mixture Models (GMMs)</li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - probabilistic clustering and likelihood calculation via Gaussian mixture models</li>
<li><a href="#kmeans">kmeans()</a></li>
</ul>
</li>
@@ -15854,7 +15858,7 @@ See also:
<li><a href="#log_normpdf">log_normpdf()</a></li>
<li><a href="#normcdf">normcdf()</a></li>
<li><a href="#randn">randn()</a></li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - model and evaluate data using Gaussian Mixture Models (GMMs)</li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - probabilistic clustering and likelihood calculation via Gaussian mixture models</li>
<li><a href="https://en.wikipedia.org/wiki/Normal_distribution">normal distribution in Wikipedia</a></li>
</ul>
</li>
@@ -15930,7 +15934,7 @@ double P5 = log_normpdf(1.23, 4.56, 7.89);
See also:
<ul>
<li><a href="#normpdf">normpdf()</a></li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - model and evaluate data using Gaussian Mixture Models (GMMs)</li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - probabilistic clustering and likelihood calculation via Gaussian mixture models</li>
<li><a href="https://en.wikipedia.org/wiki/Normal_distribution">normal distribution in Wikipedia</a></li>
</ul>
</li>
@@ -16035,7 +16039,7 @@ See also:
<li><a href="#wishrnd">wishrnd()</a></li>
<li><a href="#cov">cov()</a></li>
<li><a href="#is_sympd">.is_sympd()</a></li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - model and evaluate data using Gaussian Mixture Models (GMMs)</li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - probabilistic clustering and likelihood calculation via Gaussian mixture models</li>
<li><a href="https://en.wikipedia.org/wiki/Multivariate_normal_distribution">multivariate normal distribution in Wikipedia</a></li>
</ul>
</li>
@@ -16388,7 +16392,7 @@ cout &lt;&lt; "max = " &lt;&lt; stats.max() &lt;&lt; endl;
<ul>
<li><a href="#running_stat_vec">running_stat_vec</a> (running statistics of vectors)</li>
<li><a href="#stats_fns">statistics functions</a></li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - model and evaluate data using Gaussian Mixture Models (GMMs)</li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - probabilistic clustering via Gaussian mixture models</li>
</ul>
</li>
<br>
@@ -16598,7 +16602,7 @@ cout &lt;&lt; more_stats.cov() / (sd.t() * sd);
<li><a href="#stats_fns">statistics functions</a></li>
<li><a href="#cov">cov()</a></li>
<li><a href="#cor">cor()</a></li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - model and evaluate data using Gaussian Mixture Models (GMMs)</li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - probabilistic clustering via Gaussian mixture models</li>
</ul>
</li>
<br>
@@ -16638,7 +16642,7 @@ The <i>seed_mode</i> parameter specifies how the initial centroids are seeded; i
</tbody>
</table>
<br>
<b>caveat:</b> seeding the initial centroids with <code>static_spread</code> and <code>random_spread</code>
<b>Caveat:</b> seeding the initial centroids with <code>static_spread</code> and <code>random_spread</code>
can be much more time consuming than with <code>static_subset</code> and <code>random_subset</code>
</ul>
</li>
@@ -16656,7 +16660,11 @@ If the clustering fails, the <i>means</i> matrix is reset and a bool set to <i>f
</li>
<br>
<li>
The clustering will run faster on multi-core machines when OpenMP is enabled in your compiler (eg. <i>-fopenmp</i> in GCC and clang)
For faster execution on multi-core machines, enable OpenMP in your compiler (eg. <i>-fopenmp</i> in GCC and clang)
</li>
<br>
<li>
<b>Caveat:</b> for probabilistic clustering, use the <a href="#gmm_diag">gmm_diag</a> or <a href="#gmm_full">gmm_full</a> classes instead
</li>
<br>
<li>
@@ -16684,7 +16692,7 @@ means.print("means:");
<br>
<li>See also:
<ul>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a> - model and evaluate data using Gaussian Mixture Models (GMMs)</li>
<li><a href="#gmm_diag">gmm_diag&nbsp;/&nbsp;gmm_full</a></li>
<li><a href="#stats_fns">statistics functions</a></li>
<li><a href="#running_stat_vec">running_stat_vec</a></li>
<li><a href="https://en.wikipedia.org/wiki/K-means_clustering">k-means clustering in Wikipedia</a></li>
@@ -16703,38 +16711,11 @@ means.print("means:");
<ul>
<li>
Classes for multivariate data modelling and evaluation via <b>Gaussian Mixture Models</b> (GMMs)
Classes for multi-variate probabilistic clustering and likelihood calculation via <b>Gaussian Mixture Models</b> (GMMs)
</li>
<br>
<li>
The <i>gmm_diag</i> class is tailored for <b>diagonal covariance matrices</b> (ie. in each covariance matrix, all entries outside the main diagonal are assumed to be zero)
</li>
<br>
<li>
The <i>gmm_full</i> class is tailored for <b>full covariance matrices</b>
</li>
<br>
<li>
The <i>gmm_diag</i> class is typically much faster to train and use than the <i>gmm_full</i> class,
at the potential cost of some reduction in modelling accuracy
</li>
<br>
<li>
The <i>gmm_diag</i> and <i>gmm_full</i> classes include dedicated optimisation algorithms for learning (training) the model parameters from data:
<ul>
<li>k-means clustering, for quick initial estimates</li>
<li>Expectation-Maximisation (EM), for maximum-likelihood estimates</li>
</ul>
<br>
The optimisation algorithms are multi-threaded and can run much quicker on multi-core machines when OpenMP is enabled in your compiler (eg. <i>-fopenmp</i> in GCC and clang)
</li>
<br>
<li>
The classes can also be used for probabilistic clustering and vector quantisation (VQ)
</li>
<br>
<li>
Data is modelled as:
Distribution of data is modelled as:
<table style="text-align: left;" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
@@ -16751,6 +16732,7 @@ Data is modelled as:
</table>
where:
<ul>
<li><i>x</i> is a column vector</li>
<li><i>n_gaus</i> is the number of Gaussians; <i>n_gaus</i>&thinsp;&geq;&thinsp;1</li>
<li>N(<small>&thinsp;</small><i>x</i><small>&thinsp;</small>|<small>&thinsp;</small><i>m<sub>g</sub></i><small>&thinsp;</small>,&thinsp;<i>C<sub>g</sub></i><small>&thinsp;</small>) represents a Gaussian (normal) distribution</li>
<li>each Gaussian <i>g</i> has the following parameters:
@@ -16764,7 +16746,27 @@ where:
</li>
<br>
<li>
Mathematical implementation details are available in the following paper:
<i>gmm_diag</i> is tailored for <b>diagonal covariance matrices</b>
</li>
<br>
<li>
<i>gmm_full</i> is tailored for <b>full covariance matrices</b>
</li>
<br>
<li>
<i>gmm_diag</i> is considerably faster than <i>gmm_full</i>, at the cost of some reduction in modelling accuracy
</li>
<br>
<li>
Both <i>gmm_diag</i> and <i>gmm_full</i> include tailored k-means and Expectation Maximisation algorithms for learning model parameters from training data
</li>
<br>
<li>
For faster execution on multi-core machines, enable OpenMP in your compiler (eg. <i>-fopenmp</i> in GCC and clang)
</li>
<br>
<li>
Implementation details are available in the following paper:
<ul>
Conrad Sanderson and Ryan Curtin.
<br><i><a href="armadillo_spcs_2017.pdf">An Open Source C++ Implementation of Multi-Threaded Gaussian Mixture Models, k-Means and Expectation Maximisation</a></i>.
@@ -17379,7 +17381,6 @@ model.save("my_model.gmm");
<li><a href="https://mathworld.wolfram.com/K-MeansClusteringAlgorithm.html">k-means clustering in MathWorld</a></li>
<li><a href="https://en.wikipedia.org/wiki/Expectation-maximization_algorithm">Expectation-Maximisation algorithm in Wikipedia</a></li>
<li><a href="https://mathworld.wolfram.com/MaximumLikelihood.html">maximum likelihood in MathWorld</a></li>
<li><a href="https://en.wikipedia.org/wiki/Vector_quantization">vector quantisation in Wikipedia</a></li>
<li><a href="https://en.wikipedia.org/wiki/OpenMP">OpenMP in Wikipedia</a></li>
</ul>
</li>