| 53 | } |
| 54 | |
| 55 | void bind_cca(py::module& m) |
| 56 | { |
| 57 | py::class_<cca_outputs>(m, "cca_outputs") |
| 58 | .def_readwrite("correlations", &cca_outputs::correlations) |
| 59 | .def_readwrite("Ltrans", &cca_outputs::Ltrans) |
| 60 | .def_readwrite("Rtrans", &cca_outputs::Rtrans); |
| 61 | |
| 62 | m.def("max_index_plus_one", sparse_vector_max_index_plus_one, py::arg("v"), |
| 63 | "ensures \n\ |
| 64 | - returns the dimensionality of the given sparse vector. That is, returns a \n\ |
| 65 | number one larger than the maximum index value in the vector. If the vector \n\ |
| 66 | is empty then returns 0. " |
| 67 | ); |
| 68 | |
| 69 | |
| 70 | m.def("apply_cca_transform", apply_cca_transform, py::arg("m"), py::arg("v"), |
| 71 | "requires \n\ |
| 72 | - max_index_plus_one(v) <= m.nr() \n\ |
| 73 | ensures \n\ |
| 74 | - returns trans(m)*v \n\ |
| 75 | (i.e. multiply m by the vector v and return the result) " |
| 76 | ); |
| 77 | |
| 78 | |
| 79 | m.def("cca", _cca1, py::arg("L"), py::arg("R"), py::arg("num_correlations"), py::arg("extra_rank")=5, py::arg("q")=2, py::arg("regularization")=0, |
| 80 | "requires \n\ |
| 81 | - num_correlations > 0 \n\ |
| 82 | - len(L) > 0 \n\ |
| 83 | - len(R) > 0 \n\ |
| 84 | - len(L) == len(R) \n\ |
| 85 | - regularization >= 0 \n\ |
| 86 | - L and R must be properly sorted sparse vectors. This means they must list their \n\ |
| 87 | elements in ascending index order and not contain duplicate index values. You can use \n\ |
| 88 | make_sparse_vector() to ensure this is true. \n\ |
| 89 | ensures \n\ |
| 90 | - This function performs a canonical correlation analysis between the vectors \n\ |
| 91 | in L and R. That is, it finds two transformation matrices, Ltrans and \n\ |
| 92 | Rtrans, such that row vectors in the transformed matrices L*Ltrans and \n\ |
| 93 | R*Rtrans are as correlated as possible (note that in this notation we \n\ |
| 94 | interpret L as a matrix with the input vectors in its rows). Note also that \n\ |
| 95 | this function tries to find transformations which produce num_correlations \n\ |
| 96 | dimensional output vectors. \n\ |
| 97 | - Note that you can easily apply the transformation to a vector using \n\ |
| 98 | apply_cca_transform(). So for example, like this: \n\ |
| 99 | - apply_cca_transform(Ltrans, some_sparse_vector) \n\ |
| 100 | - returns a structure containing the Ltrans and Rtrans transformation matrices \n\ |
| 101 | as well as the estimated correlations between elements of the transformed \n\ |
| 102 | vectors. \n\ |
| 103 | - This function assumes the data vectors in L and R have already been centered \n\ |
| 104 | (i.e. we assume the vectors have zero means). However, in many cases it is \n\ |
| 105 | fine to use uncentered data with cca(). But if it is important for your \n\ |
| 106 | problem then you should center your data before passing it to cca(). \n\ |
| 107 | - This function works with reduced rank approximations of the L and R matrices. \n\ |
| 108 | This makes it fast when working with large matrices. In particular, we use \n\ |
| 109 | the dlib::svd_fast() routine to find reduced rank representations of the input \n\ |
| 110 | matrices by calling it as follows: svd_fast(L, U,D,V, num_correlations+extra_rank, q) \n\ |
| 111 | and similarly for R. This means that you can use the extra_rank and q \n\ |
| 112 | arguments to cca() to influence the accuracy of the reduced rank \n\ |