diff options
Diffstat (limited to 'ml/dlib/dlib/statistics/cca_abstract.h')
| -rw-r--r-- | ml/dlib/dlib/statistics/cca_abstract.h | 191 |
1 files changed, 191 insertions, 0 deletions
diff --git a/ml/dlib/dlib/statistics/cca_abstract.h b/ml/dlib/dlib/statistics/cca_abstract.h new file mode 100644 index 000000000..8e0b4e742 --- /dev/null +++ b/ml/dlib/dlib/statistics/cca_abstract.h @@ -0,0 +1,191 @@ +// Copyright (C) 2013 Davis E. King (davis@dlib.net) +// License: Boost Software License See LICENSE.txt for the full license. +#undef DLIB_CCA_AbSTRACT_Hh_ +#ifdef DLIB_CCA_AbSTRACT_Hh_ + +#include "../matrix/matrix_la_abstract.h" +#include "random_subset_selector_abstract.h" + +namespace dlib +{ + +// ---------------------------------------------------------------------------------------- + + template < + typename T + > + matrix<typename T::type,0,1> compute_correlations ( + const matrix_exp<T>& L, + const matrix_exp<T>& R + ); + /*! + requires + - L.size() > 0 + - R.size() > 0 + - L.nr() == R.nr() + ensures + - This function treats L and R as sequences of paired row vectors. It + then computes the correlation values between the elements of these + row vectors. In particular, we return a vector COR such that: + - COR.size() == L.nc() + - for all valid i: + - COR(i) == the correlation coefficient between the following sequence + of paired numbers: (L(k,i), R(k,i)) for k: 0 <= k < L.nr(). + Therefore, COR(i) is a value between -1 and 1 inclusive where 1 + indicates perfect correlation and -1 perfect anti-correlation. Note + that this function assumes the input data vectors have been centered + (i.e. made to have zero mean). If this is not the case then it will + report inaccurate results. + !*/ + +// ---------------------------------------------------------------------------------------- + + template < + typename T + > + matrix<T,0,1> cca ( + const matrix<T>& L, + const matrix<T>& R, + matrix<T>& Ltrans, + matrix<T>& Rtrans, + unsigned long num_correlations, + unsigned long extra_rank = 5, + unsigned long q = 2, + double regularization = 0 + ); + /*! + requires + - num_correlations > 0 + - L.size() > 0 + - R.size() > 0 + - L.nr() == R.nr() + - regularization >= 0 + ensures + - This function performs a canonical correlation analysis between the row + vectors in L and R. That is, it finds two transformation matrices, Ltrans + and Rtrans, such that row vectors in the transformed matrices L*Ltrans and + R*Rtrans are as correlated as possible. That is, we try to find two transforms + such that the correlation values returned by compute_correlations(L*Ltrans, R*Rtrans) + would be maximized. + - Let N == min(num_correlations, min(R.nr(),min(L.nc(),R.nc()))) + (This is the actual number of elements in the transformed vectors. + Therefore, note that you can't get more outputs than there are rows or + columns in the input matrices.) + - #Ltrans.nr() == L.nc() + - #Ltrans.nc() == N + - #Rtrans.nr() == R.nc() + - #Rtrans.nc() == N + - This function assumes the data vectors in L and R have already been centered + (i.e. we assume the vectors have zero means). However, in many cases it is + fine to use uncentered data with cca(). But if it is important for your + problem then you should center your data before passing it to cca(). + - This function works with reduced rank approximations of the L and R matrices. + This makes it fast when working with large matrices. In particular, we use + the svd_fast() routine to find reduced rank representations of the input + matrices by calling it as follows: svd_fast(L, U,D,V, num_correlations+extra_rank, q) + and similarly for R. This means that you can use the extra_rank and q + arguments to cca() to influence the accuracy of the reduced rank + approximation. However, the default values should work fine for most + problems. + - returns an estimate of compute_correlations(L*#Ltrans, R*#Rtrans). The + returned vector should exactly match the output of compute_correlations() + when the reduced rank approximation to L and R is accurate and regularization + is set to 0. However, if this is not the case then the return value of this + function will deviate from compute_correlations(L*#Ltrans, R*#Rtrans). This + deviation can be used to check if the reduced rank approximation is working + or you need to increase extra_rank. + - The dimensions of the output vectors produced by L*#Ltrans or R*#Rtrans are + ordered such that the dimensions with the highest correlations come first. + That is, after applying the transforms produced by cca() to a set of vectors + you will find that dimension 0 has the highest correlation, then dimension 1 + has the next highest, and so on. This also means that the list of numbers + returned from cca() will always be listed in decreasing order. + - This function performs the ridge regression version of Canonical Correlation + Analysis when regularization is set to a value > 0. In particular, larger + values indicate the solution should be more heavily regularized. This can be + useful when the dimensionality of the data is larger than the number of + samples. + - A good discussion of CCA can be found in the paper "Canonical Correlation + Analysis" by David Weenink. In particular, this function is implemented + using equations 29 and 30 from his paper. We also use the idea of doing CCA + on a reduced rank approximation of L and R as suggested by Paramveer S. + Dhillon in his paper "Two Step CCA: A new spectral method for estimating + vector models of words". + !*/ + +// ---------------------------------------------------------------------------------------- + + template < + typename sparse_vector_type, + typename T + > + matrix<T,0,1> cca ( + const std::vector<sparse_vector_type>& L, + const std::vector<sparse_vector_type>& R, + matrix<T>& Ltrans, + matrix<T>& Rtrans, + unsigned long num_correlations, + unsigned long extra_rank = 5, + unsigned long q = 2, + double regularization = 0 + ); + /*! + requires + - num_correlations > 0 + - L.size() == R.size() + - max_index_plus_one(L) > 0 && max_index_plus_one(R) > 0 + (i.e. L and R can't represent empty matrices) + - L and R must contain sparse vectors (see the top of dlib/svm/sparse_vector_abstract.h + for a definition of sparse vector) + - regularization >= 0 + ensures + - This is just an overload of the cca() function defined above. Except in this + case we take a sparse representation of the input L and R matrices rather than + dense matrices. Therefore, in this case, we interpret L and R as matrices + with L.size() rows, where each row is defined by a sparse vector. So this + function does exactly the same thing as the above cca(). + - Note that you can apply the output transforms to a sparse vector with the + following code: + sparse_matrix_vector_multiply(trans(Ltrans), your_sparse_vector) + !*/ + +// ---------------------------------------------------------------------------------------- + + template < + typename sparse_vector_type, + typename Rand_type, + typename T + > + matrix<T,0,1> cca ( + const random_subset_selector<sparse_vector_type,Rand_type>& L, + const random_subset_selector<sparse_vector_type,Rand_type>& R, + matrix<T>& Ltrans, + matrix<T>& Rtrans, + unsigned long num_correlations, + unsigned long extra_rank = 5, + unsigned long q = 2, + double regularization = 0 + ); + /*! + requires + - num_correlations > 0 + - L.size() == R.size() + - max_index_plus_one(L) > 0 && max_index_plus_one(R) > 0 + (i.e. L and R can't represent empty matrices) + - L and R must contain sparse vectors (see the top of dlib/svm/sparse_vector_abstract.h + for a definition of sparse vector) + - regularization >= 0 + ensures + - returns cca(L.to_std_vector(), R.to_std_vector(), Ltrans, Rtrans, num_correlations, extra_rank, q) + (i.e. this is just a convenience function for calling the cca() routine when + your sparse vectors are contained inside a random_subset_selector rather than + a std::vector) + !*/ + +// ---------------------------------------------------------------------------------------- + +} + +#endif // DLIB_CCA_AbSTRACT_Hh_ + + |