dlib C++ Library - sammon_abstract.h

    // Copyright (C) 2012  Emanuele Cesena (emanuele.cesena@gmail.com), Davis E. King
    // License: Boost Software License   See LICENSE.txt for the full license.
    #undef DLIB_SAMMoN_ABSTRACT_Hh_
    #ifdef DLIB_SAMMoN_ABSTRACT_Hh_

    #include "../matrix/matrix_abstract.h"
    #include <vector>

    namespace dlib
    {

        class sammon_projection
        {
            /*!
                WHAT THIS OBJECT REPRESENTS
                    This is a function object that computes the Sammon projection of a set
                    of N points in a L-dimensional vector space onto a d-dimensional space
                    (d < L), according to the paper:
                        A Nonlinear Mapping for Data Structure Analysis (1969) by J.W. Sammon

                    The current implementation is a vectorized version of the original algorithm.
            !*/

        public:

            sammon_projection(
            );
            /*!
                ensures
                    - this object is properly initialized
            !*/

            template <typename matrix_type>
            std::vector<matrix<double,0,1> > operator() (
                const std::vector<matrix_type>& data,
                const long num_dims
            );
            /*!
                requires
                    - num_dims > 0
                    - matrix_type should be a kind of dlib::matrix of doubles capable
                      of representing column vectors.
                    - for all valid i:
                        - is_col_vector(data[i]) == true
                        - data[0].size() == data[i].size()
                          (i.e. all the vectors in data must have the same dimensionality)
                    - if (data.size() != 0) then
                        - 0 < num_dims <= data[0].size()
                          (i.e. you can't project into a higher dimension than the input data,
                          only to a lower dimension.)
                ensures
                    - This routine computes Sammon's dimensionality reduction method based on the
                      given input data.  It will attempt to project the contents of data into a
                      num_dims dimensional space that preserves relative distances between the
                      input data points.
                    - This function returns a std::vector, OUT, such that:
                        - OUT == a set of column vectors that represent the Sammon projection of
                          the input data vectors.
                        - OUT.size() == data.size()
                        - for all valid i:
                            - OUT[i].size() == num_dims
                            - OUT[i] == the Sammon projection of the input vector data[i]
            !*/

            template <typename matrix_type>
            void operator() (
                const std::vector<matrix_type>& data,
                const long num_dims,
                std::vector<matrix<double,0,1> >& result,
                double &err,
                const unsigned long num_iters = 1000,
                const double err_delta = 1.0e-9
            );
            /*!
                requires
                    - num_iters > 0
                    - err_delta > 0
                    - num_dims > 0
                    - matrix_type should be a kind of dlib::matrix of doubles capable
                      of representing column vectors.
                    - for all valid i:
                        - is_col_vector(data[i]) == true
                        - data[0].size() == data[i].size()
                          (i.e. all the vectors in data must have the same dimensionality)
                    - if (data.size() != 0) then
                        - 0 < num_dims <= data[0].size()
                          (i.e. you can't project into a higher dimension than the input data,
                          only to a lower dimension.)
                ensures
                    - This routine computes Sammon's dimensionality reduction method based on the
                      given input data.  It will attempt to project the contents of data into a
                      num_dims dimensional space that preserves relative distances between the
                      input data points.
                    - #err == the final error value at the end of the algorithm.  The goal of Sammon's
                      algorithm is to find a lower dimensional projection of the input data that
                      preserves the relative distances between points.  The value in #err is a measure
                      of the total error at the end of the algorithm.  So smaller values indicate
                      a better projection was found than if a large value is returned via #err.
                    - Sammon's algorithm will run until either num_iters iterations has executed
                      or the change in error from one iteration to the next is less than err_delta.
                    - Upon completion, the output of Sammon's projection is stored into #result, in
                      particular, we will have:
                        - #result == a set of column vectors that represent the Sammon projection of
                          the input data vectors.
                        - #result.size() == data.size()
                        - for all valid i:
                            - #result[i].size() == num_dims
                            - #result[i] == the Sammon projection of the input vector data[i]
            !*/

        };

    }

    #endif // DLIB_SAMMoN_ABSTRACT_Hh_