Worked on the discriminant_pca specification more. It is now relatively complete.

--HG--
extra : convert_revision : svn%3Afdd8eb12-d10e-0410-9acb-85c331704f74/trunk%403331

dlib/statistics/dpca_abstract.h

@@ -28,10 +28,28 @@ namespace dlib
 
             WHAT THIS OBJECT REPRESENTS
                 This object implements the Discriminant PCA technique described in the paper:
-                    A New Discriminant Principal Component Analysis Method with Partial Supervision
+                    A New Discriminant Principal Component Analysis Method with Partial Supervision (2009)
                     by Dan Sun and Daoqiang Zhang
 
-                TODO
+                This algorithm is basically a straightforward generalization of the classical PCA
+                technique to handle partially labeled data.  It is useful if you want to learn a linear
+                dimensionality reduction rule using a bunch of data that is partially labeled.  
+                
+                It functions by estimating three different scatter matrices.  The first is the total scatter 
+                matrix St (i.e.  the total data covariance matrix), the second is the between class scatter 
+                matrix Sb (basically a measure of the variance between data of different classes) and the 
+                third is the within class scatter matrix Sw (a measure of the variance of data within the 
+                same classes).  
+
+                Once these three matrices are estimated they are combined according to the following equation:
+                   S = St + a*Sb - b*Sw
+                Where a and b are user supplied weights.  Then the largest eigenvalues of the S matrix are 
+                computed and their associated eigenvectors are returned as the output of this algorithm.  
+                That is, the desired linear dimensionality reduction is given by the transformation matrix 
+                with these eigenvectors stored in its rows.
+
+                Note that if a and b are set to 0 (or no labeled data is provided) then the output transformation
+                matrix is the same as the one produced by the classical PCA algorithm.
         !*/
 
     public:
@@ -85,6 +103,9 @@ namespace dlib
         scalar_type within_class_weight (
         ) const;
         /*!
+            ensures
+                - returns the weight used when combining the within class scatter matrix with
+                  the other scatter matrices.  
         !*/
 
         void set_between_class_weight (
@@ -100,6 +121,9 @@ namespace dlib
         scalar_type between_class_weight (
         ) const;
         /*!
+            ensures
+                - returns the weight used when combining the between class scatter matrix with
+                  the other scatter matrices.  
         !*/
 
         void add_to_within_class_variance(
@@ -115,7 +139,10 @@ namespace dlib
                     - x.size() == y.size() == in_vector_size()
             ensures
                 - #in_vector_size() == x.size()
-                - TODO
+                - Adds (x-y)*trans(x-y) to the within class scatter matrix.
+                  (i.e. the direction given by (x-y) is recorded as being a direction associated
+                  with within class variance and is therefore unimportant and will be weighted
+                  less in the final dimensionality reduction)
         !*/
 
         void add_to_between_class_variance(
@@ -131,7 +158,10 @@ namespace dlib
                     - x.size() == y.size() == in_vector_size()
             ensures
                 - #in_vector_size() == x.size()
-                - TODO
+                - Adds (x-y)*trans(x-y) to the between class scatter matrix.
+                  (i.e. the direction given by (x-y) is recorded as being a direction associated
+                  with between class variance and is therefore important and will be weighted
+                  higher in the final dimensionality reduction)
         !*/
 
         void add_to_total_variance(
@@ -144,7 +174,11 @@ namespace dlib
                     - x.size() == in_vector_size()
             ensures
                 - #in_vector_size() == x.size()
-                - TODO
+                - let M denote the centroid (or mean) of all the data.  Then this function 
+                  Adds (x-M)*trans(x-M) to the total scatter matrix.
+                  (i.e. the direction given by (x-M) is recorded as being a direction associated
+                  with unlabeled variance and is therefore of default importance and will be weighted
+                  as described in the discriminant_pca class description.)
         !*/
 
         const general_matrix dpca_matrix (
@@ -156,9 +190,11 @@ namespace dlib
                 - in_vector_size() != 0
                   (i.e. you have to have given this object some data)
             ensures
-                - computes and returns the matrix M given by dpca_matrix(M,eigen,eps).  
+                - computes and returns the matrix MAT given by dpca_matrix(MAT,eigen,eps).  
                   That is, this function returns the dpca_matrix computed by the function
                   defined below.  
+                - Note that MAT is the desired linear transformation matrix.  That is, 
+                  multiplying a vector by MAT performs the desired linear dimensionality reduction.
             throws
                 - discriminant_pca_error
                     This exception is thrown if we are unable to create the dpca_matrix for some 
@@ -179,10 +215,20 @@ namespace dlib
                   (i.e. you have to have given this object some data)
             ensures
                 - #is_col_vector(eigenvalues) == true
-                - #eigenvalues.size() == #dpca_mat.nr()
+                - #dpca_mat.nr() == eigenvalues.size() 
                 - #dpca_mat.nc() == in_vector_size()
-                - all values in #eigenvalues are > 0
-                - TODO
+                - rowm(#dpca_mat,i) represents the ith eigenvector of the S matrix described
+                  in the class description and its eigenvalue is given by eigenvalues(i).
+                - all values in #eigenvalues are > 0.  Moreover, the eigenvalues are in
+                  sorted order with the largest eigenvalue stored at eigenvalues(0).
+                - Note that #dpca_mat is the desired linear transformation matrix.  That is, 
+                  multiplying a vector by #dpca_mat performs the desired linear dimensionality 
+                  reduction.
+                - sum(eigenvalues) will be equal to about eps times the total sum of all 
+                  positive eigenvalues in the S matrix described in this class's description.
+                  This means that eps is a number that controls how "lossy" the dimensionality
+                  reduction will be.  Large values of eps result in more output dimensions 
+                  while smaller values result in fewer. 
             throws
                 - discriminant_pca_error
                     This exception is thrown if we are unable to create the dpca_matrix for some