Merge pull request #306 from alesis/gmm

Few documentation additions
shogun-toolbox · Aug 21, 2011 · f14ecfb · f14ecfb
2 parents 23edad1 + e030a9e
commit f14ecfb
Show file tree

Hide file tree

Showing 7 changed files with 47 additions and 0 deletions.
diff --git a/examples/descriptions/modular/clustering_gmm.txt b/examples/descriptions/modular/clustering_gmm.txt
@@ -0,0 +1,11 @@
+In this example the GMM clustering method is used to cluster a generated
+data set. In GMM clustering one tries to partition n observations into k
+clusters in which each observation belongs to the cluster defined by a Gaussian
+distribution, whose probability of generating the observation is highest.
+The algorithm class constructor takes the number of clusters and a type of
+covariance as input. The covariance used in this example is the full covariance.
+The training method used in this example is Expectation-Maximization. It takes
+minimum covariance, maximum iterations and minimum log-likelihood change as
+input. After training one can cluster observations by selecting the most
+likely cluster to have generated the observation. 
+
diff --git a/examples/undocumented/python_modular/clustering_gmm_modular.py b/examples/undocumented/python_modular/clustering_gmm_modular.py
@@ -1,3 +1,7 @@
+##!/usr/bin/env python
+#"""
+#Explicit examples on how to use clustering
+#"""
 from numpy import array, append
 from shogun.Distribution import GMM
 from shogun.Library import Math_init_random

diff --git a/examples/undocumented/python_modular/graphical/em_1d_gmm.py b/examples/undocumented/python_modular/graphical/em_1d_gmm.py
@@ -6,10 +6,12 @@
 
 util.set_title('EM for 1d GMM example')
 
+#set the parameters
 min_cov=1e-9
 max_iter=1000
 min_change=1e-9
 
+#setup the real GMM
 real_gmm=GMM(3)
 
 real_gmm.set_nth_mean(array([-2.0]), 0)
@@ -22,15 +24,19 @@
 
 real_gmm.set_coef(array([0.3, 0.5, 0.2]))
 
+#generate training set from real GMM
 generated=array([real_gmm.sample()])
 for i in range(199):
     generated=append(generated, array([real_gmm.sample()]), axis=1)
 
 feat_train=RealFeatures(generated)
+
+#train GMM using EM
 est_gmm=GMM(3)
 est_gmm.train(feat_train)
 est_gmm.train_em(min_cov, max_iter, min_change)
 
+#get and print estimated means and covariances
 est_mean1=est_gmm.get_nth_mean(0)
 est_mean2=est_gmm.get_nth_mean(1)
 est_mean3=est_gmm.get_nth_mean(2)
@@ -46,6 +52,7 @@
 print est_cov3
 print est_coef
 
+#plot real GMM, data and estimated GMM
 min_gen=min(min(generated))
 max_gen=max(max(generated))
 plot_real=empty(0)

diff --git a/examples/undocumented/python_modular/graphical/em_2d_gmm.py b/examples/undocumented/python_modular/graphical/em_2d_gmm.py
@@ -6,11 +6,13 @@
 
 util.set_title('EM for 2d GMM example')
 
+#set the parameters
 min_cov=1e-9
 max_iter=1000
 min_change=1e-9
 cov_type=0
 
+#setup the real GMM
 real_gmm=GMM(2)
 
 real_gmm.set_nth_mean(array([1.0, 1.0]), 0)
@@ -21,16 +23,20 @@
 
 real_gmm.set_coef(array([0.3, 0.7]))
 
+#generate training set from real GMM
 generated=array([real_gmm.sample()])
 for i in range(199):
     generated=append(generated, array([real_gmm.sample()]), axis=0)
 
 generated=generated.transpose()
 feat_train=RealFeatures(generated)
+
+#train GMM using EM
 est_gmm=GMM(2, cov_type)
 est_gmm.train(feat_train)
 est_gmm.train_em(min_cov, max_iter, min_change)
 
+#get and print estimated means and covariances
 est_mean1=est_gmm.get_nth_mean(0)
 est_mean2=est_gmm.get_nth_mean(1)
 est_cov1=est_gmm.get_nth_cov(0)
@@ -42,6 +48,7 @@
 print est_cov2
 print est_coef
 
+#plot real GMM, data and estimated GMM
 min_x_gen=min(min(generated[[0]]))-0.1
 max_x_gen=max(max(generated[[0]]))+0.1
 min_y_gen=min(min(generated[[1]]))-0.1

diff --git a/examples/undocumented/python_modular/graphical/smem_1d_gmm.py b/examples/undocumented/python_modular/graphical/smem_1d_gmm.py
@@ -6,12 +6,14 @@
 
 util.set_title('SMEM for 1d GMM example')
 
+#set the parameters
 max_iter=100
 max_cand=5
 min_cov=1e-9
 max_em_iter=1000
 min_change=1e-9
 
+#setup the real GMM
 real_gmm=GMM(3)
 
 real_gmm.set_nth_mean(array([-2.0]), 0)
@@ -24,18 +26,23 @@
 
 real_gmm.set_coef(array([0.3, 0.5, 0.2]))
 
+#generate training set from real GMM
 generated=array([real_gmm.sample()])
 for i in range(199):
     generated=append(generated, array([real_gmm.sample()]), axis=1)
 
 feat_train=RealFeatures(generated)
+
+#train GMM using SMEM and print log-likelihood
 est_smem_gmm=GMM(3)
 est_smem_gmm.train(feat_train)
 print est_smem_gmm.train_smem(max_iter, max_cand, min_cov, max_em_iter, min_change)
+#train GMM using EM and print log-likelihood
 est_em_gmm=GMM(3)
 est_em_gmm.train(feat_train)
 print est_em_gmm.train_em(min_cov, max_em_iter, min_change)
 
+#plot real GMM, data and both estimated GMMs
 min_gen=min(min(generated))
 max_gen=max(max(generated))
 plot_real=empty(0)

diff --git a/examples/undocumented/python_modular/graphical/smem_2d_gmm.py b/examples/undocumented/python_modular/graphical/smem_2d_gmm.py
@@ -6,13 +6,15 @@
 
 util.set_title('SMEM for 2d GMM example')
 
+#set the parameters
 max_iter=100
 max_cand=5
 min_cov=1e-9
 max_em_iter=1000
 min_change=1e-9
 cov_type=0
 
+#setup the real GMM
 real_gmm=GMM(3)
 
 real_gmm.set_nth_mean(array([2.0, 2.0]), 0)
@@ -25,12 +27,15 @@
 
 real_gmm.set_coef(array([0.3, 0.4, 0.3]))
 
+#generate training set from real GMM
 generated=array([real_gmm.sample()])
 for i in range(199):
     generated=append(generated, array([real_gmm.sample()]), axis=0)
 
 generated=generated.transpose()
 feat_train=RealFeatures(generated)
+
+#train GMM using SMEM and print log-likelihood
 est_smem_gmm=GMM(3, cov_type)
 est_smem_gmm.train(feat_train)
 
@@ -46,6 +51,7 @@
 
 print est_smem_gmm.train_smem(max_iter, max_cand, min_cov, max_em_iter, min_change)
 
+#train GMM using EM and bad initial conditions and print log-likelihood
 est_em_gmm=GMM(3, cov_type)
 est_em_gmm.train(feat_train)
 
@@ -61,6 +67,7 @@
 
 print est_em_gmm.train_em(min_cov, max_em_iter, min_change)
 
+#plot real GMM, data and both estimated GMMs
 min_x_gen=min(min(generated[[0]]))-0.1
 max_x_gen=max(max(generated[[0]]))+0.1
 min_y_gen=min(min(generated[[1]]))-0.1

diff --git a/src/shogun/distributions/Gaussian.h b/src/shogun/distributions/Gaussian.h
@@ -25,10 +25,14 @@ namespace shogun
 {
 class CDotFeatures;
 
+/** Covariance type */
 enum ECovType
 {
+	/// full covariance
 	FULL,
+	/// diagonal covariance
 	DIAG,
+	/// spherical covariance
 	SPHERICAL
 };