umappp 0.1.2

data/vendor/irlba/utils.hpp

@@ -0,0 +1,224 @@
+#ifndef IRLBA_UTILS_HPP
+#define IRLBA_UTILS_HPP
+
+#include "Eigen/Dense"
+#include <random>
+#include <utility>
+#include "aarand/aarand.hpp"
+
+/**
+ * @file utils.hpp
+ * 
+ * @brief Various utility functions.
+ */
+
+namespace irlba {
+
+/**
+ * Orthogonalize a vector against a set of orthonormal column vectors. 
+ *
+ * @param mat A matrix where the left-most `ncols` columns are orthonormal vectors.
+ * @param vec The vector of interest, of length equal to the number of rows in `mat`.
+ * @param tmp A vector of length equal to `mat.cols()`, used to store intermediate matrix products.
+ * @param ncols Number of left-most columns of `mat` to use.
+ *
+ * @return `vec` is modified to contain `vec - mat0 * t(mat0) * vec`, where `mat0` is defined as the first `ncols` columns of `mat`.
+ * This ensures that it is orthogonal to each column of `mat0`.
+ */
+inline void orthogonalize_vector(const Eigen::MatrixXd& mat, Eigen::VectorXd& vec, size_t ncols, Eigen::VectorXd& tmp) {
+    tmp.head(ncols).noalias() = mat.leftCols(ncols).adjoint() * vec;
+    vec.noalias() -= mat.leftCols(ncols) * tmp.head(ncols);
+    return;
+}
+
+/** 
+ * Fill an **Eigen** vector with random normals via **aarand**.
+ *
+ * @param Vec Any **Eigen** vector class or equivalent proxy object.
+ * @param Engine A (pseudo-)random number generator class that returns a random number when called with no arguments.
+ *
+ * @param vec Instance of a `Vec` class.
+ * @param eng Instance of an `Engine` class.
+ *
+ * @return `vec` is filled with random draws from a standard normal distribution.
+ */
+template<class Vec, class Engine>
+void fill_with_random_normals(Vec& vec, Engine& eng) {
+    Eigen::Index i = 0;
+    while (i < vec.size() - 1) {
+        auto paired = aarand::standard_normal(eng);
+        vec[i] = paired.first;
+        vec[i + 1] = paired.second;
+        i += 2;
+    }
+
+    if (i != vec.size()) {
+        auto paired = aarand::standard_normal(eng);
+        vec[i] = paired.first;
+    }
+    return;
+}
+
+/**
+ * @cond
+ */
+template<class M>
+struct ColumnVectorProxy {
+    ColumnVectorProxy(M& m, int c) : mat(m), col(c) {}
+    auto size () { return mat.rows(); }
+    auto& operator[](int r) { return mat(r, col); }
+    M& mat;
+    int col;
+};
+/**
+ * @endcond
+ */
+ 
+/** 
+ * Fill a column of an **Eigen** matrix with random normals via **aarand**.
+ *
+ * @param Matrix Any **Eigen** matrix class or equivalent proxy object.
+ * @param Engine A (pseudo-)random number generator class that returns a random number when called with no arguments.
+ *
+ * @param mat Instance of a `Matrix` class.
+ * @param eng Instance of an `Engine` class.
+ *
+ * @return The `column` column of `mat` is filled with random draws from a standard normal distribution.
+ */
+template<class Matrix, class Engine>
+void fill_with_random_normals(Matrix& mat, int column, Engine& eng) {
+    ColumnVectorProxy proxy(mat, column);
+    fill_with_random_normals(proxy, eng);
+    return;
+}
+
+/**
+ * @brief Test for IRLBA convergence.
+ */
+struct ConvergenceTest {
+public:
+    struct Defaults {
+        /**
+         * See `set_tol()` for more details.
+         */
+        static constexpr double tol = 1e-5;
+
+        /**
+         * See `set_svtol()` for more details.
+         */
+        static constexpr double svtol = -1;
+    };
+
+private:
+    double tol = Defaults::tol;
+    double svtol = Defaults::svtol;
+
+public:
+    /**
+     * Set the tolerance on the residuals.
+     *
+     * @param t Tolerance, should be a positive number.
+     *
+     * @return A reference to this `ConvergenceTest` instance.
+     */
+    ConvergenceTest& set_tol(double t = Defaults::tol) {
+        tol = t;
+        return *this;
+    }
+
+    /**
+     * Set the tolerance on the relative differences between singular values across iterations.
+     *
+     * @param s Tolerance, should be a positive number.
+     * Alternatively -1, in which case the value supplied to `set_tol()` is used.
+     *
+     * @return A reference to this `ConvergenceTest` instance.
+     */
+    ConvergenceTest& set_svtol(double s = Defaults::svtol) {
+        svtol = s;
+        return *this;
+    }
+
+public:
+    /**
+     * Calculate the number of singular values/vectors that have converged.
+     *
+     * @param sv Vector of singular values.
+     * @param residuals Vector of residuals for each singular value/vector.
+     *
+     * @return The number of singular values/vectors that have achieved convergence.
+     */
+    int run(const Eigen::VectorXd& sv, const Eigen::VectorXd& residuals, const Eigen::VectorXd& last) const {
+        int counter = 0;
+        double Smax = *std::max_element(sv.begin(), sv.end());
+        double svtol_actual = (svtol >= 0 ? svtol : tol);
+
+        for (int j = 0; j < sv.size(); ++j) {
+            double ratio = std::abs(sv[j] - last[j]) / sv[j];
+            if (std::abs(residuals[j]) < tol * Smax && // see the RHS of Equation 2.13 in Baglama and Reichel.
+                    ratio < svtol_actual) {
+                ++counter;
+            }
+        }
+
+        return counter;
+    }
+};
+
+/**
+ * Utility function to generate a default `NULL` argument for the random number generator input.
+ *
+ * @return A null pointer to an RNG.
+ * Any RNG will do here, so we use the most common one.
+ */
+constexpr std::mt19937_64* null_rng() { return NULL; }
+
+/**
+ * @cond
+ */
+template<class M, typename = int>
+struct has_multiply_method {
+    static constexpr bool value = false;
+};
+
+template<class M>
+struct has_multiply_method<M, decltype((void) (std::declval<M>() * std::declval<Eigen::VectorXd>()), 0)> {
+    static constexpr bool value = true;
+};
+
+template<class M, typename = int>
+struct has_adjoint_multiply_method {
+    static constexpr bool value = false;
+};
+
+template<class M>
+struct has_adjoint_multiply_method<M, decltype((void) (std::declval<M>().adjoint() * std::declval<Eigen::VectorXd>()), 0)> {
+    static constexpr bool value = true;
+};
+
+template<class M, typename = int>
+struct has_realize_method {
+    static constexpr bool value = false;
+};
+
+template<class M>
+struct has_realize_method<M, decltype((void) std::declval<M>().realize(), 0)> {
+    static constexpr bool value = std::is_same<decltype(std::declval<M>().realize()), Eigen::MatrixXd>::value;
+};
+
+template<class M, typename = int>
+struct has_data_method {
+    static constexpr bool value = false;
+};
+
+template<class M>
+struct has_data_method<M, decltype((void) (std::declval<M>().data()), 0)> {
+    static constexpr bool value = true;
+};
+/**
+ * @endcond
+ */
+
+}
+
+#endif

data/vendor/irlba/wrappers.hpp

@@ -0,0 +1,228 @@
+#ifndef IRLBA_WRAPPERS_HPP
+#define IRLBA_WRAPPERS_HPP
+
+#include "utils.hpp"
+#include "Eigen/Dense"
+
+/**
+ * @file wrappers.hpp
+ *
+ * @brief Wrapper classes for multiplication of modified matrices.
+ *
+ * The idea is to compute the product of a modified matrix with a vector - but without actually modifying the underlying matrix.
+ * This is especially important when the modification results in an unnecessary copy and/or loss of sparsity.
+ * We achieve this effect by deferring the modification into the subspace defined by vector.
+ *
+ * An instance `mat` of a wrapper class should implement:
+ *
+ * - `mat.rows()`, returning the number of rows.
+ * - `mat.cols()`, returning the number of columns.
+ * - `mat.multiply(rhs, out)`, which computes the matrix product `mat * rhs` and stores it in `out`.
+ * `rhs` should be an `Eigen::VectorXd` (or an expression equivalent) while `out` should be a `Eigen::VectorXd`.
+ * - `mat.adjoint_multiply(rhs, out)`, which computes the matrix product `mat.adjoint() * rhs` and stores it in `out`.
+ * `rhs` should be an `Eigen::VectorXd` (or an expression equivalent) while `out` should be a `Eigen::VectorXd`.
+ * - `mat.realize()`, which returns an `Eigen::MatrixXd` containing the matrix with all modifications applied.
+ */
+
+namespace irlba {
+
+/**
+ * @brief Wrapper for a centered matrix.
+ *
+ * @tparam Matrix An **Eigen** matrix class - or alternatively, a wrapper class around such a class.
+ * 
+ * This modification involves centering all columns, i.e., subtracting the mean of each column from the values of that column.
+ * Naively doing such an operation would involve loss of sparsity, which we avoid by deferring the subtraction into the subspace defined by `rhs`.
+ */
+template<class Matrix>
+struct Centered {
+    /**
+     * @param m Underlying matrix to be column-centered.
+     * @param c Vector of length equal to the number of columns of `m`,
+     * containing the value to subtract from each column.
+     */
+    Centered(const Matrix* m, const Eigen::VectorXd* c) : mat(m), center(c) {}
+
+    /**
+     * @return Number of rows in the matrix.
+     */
+    auto rows() const { return mat->rows(); }
+
+    /**
+     * @return Number of columns in the matrix.
+     */
+    auto cols() const { return mat->cols(); }
+
+    /**
+     * @tparam Right An `Eigen::VectorXd` or equivalent expression.
+     *
+     * @param[in] rhs The right-hand side of the matrix product.
+     * This should be a vector or have only one column.
+     * @param[out] out The output vector to store the matrix product.
+     * 
+     * @return `out` is filled with the product of this matrix and `rhs`.
+     */
+    template<class Right>
+    void multiply(const Right& rhs, Eigen::VectorXd& out) const {
+        if constexpr(has_multiply_method<Matrix>::value) {
+            out.noalias() = *mat * rhs;
+        } else {
+            mat->multiply(rhs, out);
+        }
+
+        double beta = rhs.dot(*center);
+        for (auto& o : out) {
+            o -= beta;
+        }
+        return;
+    }
+
+    /**
+     * @tparam Right An `Eigen::VectorXd` or equivalent expression.
+     *
+     * @param[in] rhs The right-hand side of the matrix product.
+     * This should be a vector or have only one column.
+     * @param[out] out The output vector to store the matrix product.
+     * 
+     * @return `out` is filled with the product of the transpose of this matrix and `rhs`.
+     */
+    template<class Right>
+    void adjoint_multiply(const Right& rhs, Eigen::VectorXd& out) const {
+        if constexpr(has_adjoint_multiply_method<Matrix>::value) {
+            out.noalias() = mat->adjoint() * rhs;
+        } else {
+            mat->adjoint_multiply(rhs, out);
+        }
+
+        double beta = rhs.sum();
+        out -= beta * (*center);
+        return;
+    }
+
+    /**
+     * @return A realized version of the centered matrix,
+     * where the centering has been explicitly applied.
+     */
+    Eigen::MatrixXd realize() const {
+        auto subtractor = [&](Eigen::MatrixXd& m) -> void {
+            for (Eigen::Index c = 0; c < m.cols(); ++c) {
+                for (Eigen::Index r = 0; r < m.rows(); ++r) {
+                    m(r, c) -= (*center)[c];
+                }
+            }
+        };
+
+        if constexpr(has_realize_method<Matrix>::value) {
+            Eigen::MatrixXd output = mat->realize();
+            subtractor(output);
+            return output;
+        } else {
+            Eigen::MatrixXd output(*mat);
+            subtractor(output);
+            return output;
+        }
+    }
+
+private:
+    const Matrix* mat;
+    const Eigen::VectorXd* center;
+};
+
+/**
+ * @brief Wrapper for a scaled matrix.
+ *
+ * @tparam Matrix An **Eigen** matrix class - or alternatively, a wrapper class around such a class.
+ * 
+ * This modification involves scaling all columns, i.e., dividing the values of each column by the standard deviation of that column to achieve unit variance.
+ * Naively doing such an operation would involve a copy of the matrix, which we avoid by deferring the scaling into the subspace defined by `rhs`.
+ */
+template<class Matrix>
+struct Scaled {
+    /**
+     * @param m Underlying matrix to be column-scaled.
+     * @param s Vector of length equal to the number of columns of `m`,
+     * containing the value to scale each column.
+     */
+    Scaled(const Matrix* m, const Eigen::VectorXd* s) : mat(m), scale(s) {}
+
+    /**
+     * @return Number of rows in the matrix.
+     */
+    auto rows() const { return mat->rows(); }
+
+    /**
+     * @return Number of columns in the matrix.
+     */
+    auto cols() const { return mat->cols(); }
+
+    /**
+     * @tparam Right An `Eigen::VectorXd` or equivalent expression.
+     *
+     * @param[in] rhs The right-hand side of the matrix product.
+     * This should be a vector or have only one column.
+     * @param[out] out The output vector to store the matrix product.
+     * 
+     * @return `out` is filled with the product of this matrix and `rhs`.
+     */
+    template<class Right>
+    void multiply(const Right& rhs, Eigen::VectorXd& out) const {
+        if constexpr(has_multiply_method<Matrix>::value) {
+            out.noalias() = *mat * rhs.cwiseQuotient(*scale);
+        } else {
+            mat->multiply(rhs.cwiseQuotient(*scale), out);
+        }
+        return;
+    }
+
+    /**
+     * @tparam Right An `Eigen::VectorXd` or equivalent expression.
+     *
+     * @param[in] rhs The right-hand side of the matrix product.
+     * This should be a vector or have only one column.
+     * @param[out] out The output vector to store the matrix product.
+     * 
+     * @return `out` is filled with the product of the transpose of this matrix and `rhs`.
+     */
+    template<class Right>
+    void adjoint_multiply(const Right& rhs, Eigen::VectorXd& out) const {
+        if constexpr(has_adjoint_multiply_method<Matrix>::value) {
+            out.noalias() = mat->adjoint() * rhs;
+        } else {
+            mat->adjoint_multiply(rhs, out);
+        }
+        out.noalias() = out.cwiseQuotient(*scale);
+        return;
+    }
+
+    /**
+     * @return A realized version of the scaled matrix,
+     * where the scaling has been explicitly applied.
+     */
+    Eigen::MatrixXd realize() const {
+        auto scaler = [&](Eigen::MatrixXd& m) -> void {
+            for (Eigen::Index c = 0; c < m.cols(); ++c) {
+                for (Eigen::Index r = 0; r < m.rows(); ++r) {
+                    m(r, c) /= (*scale)[c];
+                }
+            }
+        };
+
+        if constexpr(has_realize_method<Matrix>::value) {
+            Eigen::MatrixXd output = mat->realize();
+            scaler(output);
+            return output;
+        } else {
+            Eigen::MatrixXd output(*mat);
+            scaler(output);
+            return output;
+        }
+    }
+
+private:
+    const Matrix* mat;
+    const Eigen::VectorXd* scale;
+};
+
+}
+
+#endif

data/vendor/kmeans/Base.hpp

@@ -0,0 +1,75 @@
+#ifndef KMEANS_BASE_HPP
+#define KMEANS_BASE_HPP
+
+#include "Details.hpp"
+
+namespace kmeans {
+
+/**
+ * @brief Base class for all k-means refinement algorithms.
+ *
+ * @tparam DATA_t Floating-point type for the data and centroids.
+ * @tparam CLUSTER_t Integer type for the cluster assignments.
+ * @tparam INDEX_t Integer type for the observation index.
+ */
+template<typename DATA_t = double, typename CLUSTER_t = int, typename INDEX_t = int>
+class Refine {
+public:
+    virtual ~Refine() {}
+
+    /**
+     * @param ndim Number of dimensions.
+     * @param nobs Number of observations.
+     * @param[in] data Pointer to a `ndim`-by-`nobs` array where columns are observations and rows are dimensions. 
+     * Data should be stored in column-major order.
+     * @param ncenters Number of cluster centers.
+     * @param[in, out] centers Pointer to a `ndim`-by-`ncenters` array where columns are cluster centers and rows are dimensions. 
+     * On input, this should contain the initial centroid locations for each cluster.
+     * Data should be stored in column-major order.
+     * On output, this will contain the final centroid locations for each cluster.
+     * @param[out] clusters Pointer to an array of length `nobs`.
+     * On output, this will contain the cluster assignment for each observation.
+     *
+     * @return `centers` and `clusters` are filled, and a `Details` object is returned containing clustering statistics.
+     * If `ncenters > nobs`, only the first `nobs` columns of the `centers` array will be filled.
+     */
+    virtual Details<DATA_t, INDEX_t> run(int ndim, INDEX_t nobs, const DATA_t* data, CLUSTER_t ncenters, DATA_t* centers, CLUSTER_t* clusters) = 0;
+};
+
+/**
+ * @brief Base class for all k-means initialization algorithms.
+ *
+ * @tparam DATA_t Floating-point type for the data and centroids.
+ * @tparam CLUSTER_t Integer type for the cluster assignments.
+ * @tparam INDEX_t Integer type for the observation index.
+ */
+template<typename DATA_t = double, typename CLUSTER_t = int, typename INDEX_t = int>
+class Initialize {
+public:
+    virtual ~Initialize() {}
+
+    /**
+     * @param ndim Number of dimensions.
+     * @param nobs Number of observations.
+     * @param[in] data Pointer to a `ndim`-by-`nobs` array where columns are observations and rows are dimensions. 
+     * Data should be stored in column-major order.
+     * @param ncenters Number of cluster centers.
+     * @param[in, out] centers Pointer to a `ndim`-by-`ncenters` array where columns are cluster centers and rows are dimensions. 
+     * On input, this should contain the initial centroid locations for each cluster, or it may be ignored, depending on the subclass.
+     * Data should be stored in column-major order.
+     * On output, this will contain the final centroid locations for each cluster.
+     * @param[in, out] clusters Pointer to an array of length `nobs`.
+     * On input, this should contain the initial cluster assignments for each observation, or it may be ignored, depending on the subclass.
+     * This may be modified by the subclass - no guarantees are provided as to the output state.
+     *
+     * @return `centers` is filled with the new cluster centers.
+     * The number of filled centers is returned - this is usually equal to `ncenters`, but may not be if, e.g., `ncenters > nobs`.
+     * If the returned value is less than `ncenters`, only the first centers in `centers` will be filled.
+     */
+    virtual CLUSTER_t run(int ndim, INDEX_t nobs, const DATA_t* data, CLUSTER_t ncenters, DATA_t* centers, CLUSTER_t* clusters) = 0;
+};
+
+
+}
+
+#endif

data/vendor/kmeans/Details.hpp

@@ -0,0 +1,79 @@
+#ifndef KMEANS_DETAILS_HPP
+#define KMEANS_DETAILS_HPP
+
+#include <vector>
+
+namespace kmeans {
+
+/**
+ * @file Details.hpp
+ *
+ * @brief Report detailed clustering statistics.
+ */
+
+/**
+ * @brief Additional statistics from the k-means algorithm.
+ *
+ * @tparam DATA_t Floating-point type for the data and centroids.
+ * @tparam INDEX_t Integer type for the observation index.
+ * This should have a maximum positive value that is at least 50 times greater than the maximum expected number of observations.
+ */
+template<typename DATA_t = double, typename INDEX_t = int>
+struct Details {
+    /**
+     * @cond
+     */
+    Details() {}
+
+    Details(int it, int st) : sizes(0), withinss(0), iterations(it), status(st) {}
+
+    Details(std::vector<INDEX_t> s, std::vector<DATA_t> w, int it, int st) : sizes(std::move(s)), withinss(std::move(w)), iterations(it), status(st) {} 
+    /**
+     * @endcond
+     */
+
+    /**
+     * The number of observations in each cluster.
+     * All values are guaranteed to be positive for non-zero numbers of observations when `status == 0`.
+     */
+    std::vector<INDEX_t> sizes;
+
+    /**
+     * The within-cluster sum of squares for each cluster.
+     * All values are guaranteed to be non-negative.
+     * Values may be zero for clusters with only one observation.
+     */
+    std::vector<DATA_t> withinss;
+
+    /**
+     * The number of iterations used to achieve convergence.
+     * This value may be greater than the `maxit` if convergence was not achieved, see `status`.
+     */
+    int iterations;
+
+    /**
+     * The status of the algorithm.
+     * A value of 0 indicates that the algorithm completed successfully.
+     * The interpretation of a non-zero value depends on the algorithm.
+     *
+     * For `HartiganWong`:
+     *
+     * - 1: empty cluster detected.
+     * This usually indicates a problem with the initial choice of centroids.
+     * It can also occur in pathological situations with duplicate points.
+     * - 2: maximum iterations reached without convergence. 
+     * - 3: the number of centers is not positive or greater than the number of observations.
+     * - 4: maximum number of quick transfer steps exceeded.
+     *
+     * For `Lloyd`:
+     *
+     * - 1: empty cluster detected.
+     * - 2: maximum iterations reached without convergence. 
+     */
+    int status;
+};
+
+}
+
+#endif
+