    // 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_