LDABuilder.hpp

#ifndef _LDAPLUSPLUS_LDABUILDER_HPP_
#define _LDAPLUSPLUS_LDABUILDER_HPP_

#include <memory>
#include <stdexcept>
#include <thread>
#include <vector>

#include <Eigen/Core>

#include "ldaplusplus/Document.hpp"
#include "ldaplusplus/em/FastSupervisedEStep.hpp"
#include "ldaplusplus/em/EStepInterface.hpp"
#include "ldaplusplus/em/MStepInterface.hpp"
#include "ldaplusplus/LDA.hpp"

namespace ldaplusplus {


template <typename Scalar = double>
class LDABuilderInterface
{
    public:
        virtual operator LDA<Scalar>() const = 0;

    virtual ~LDABuilderInterface(){};
};


template <typename Scalar = double>
class LDABuilder : public LDABuilderInterface<Scalar>
{
    typedef Eigen::Matrix<Scalar, Eigen::Dynamic, Eigen::Dynamic> MatrixX;
    typedef Eigen::Matrix<Scalar, Eigen::Dynamic, 1> VectorX;

    public:
        LDABuilder();

        LDABuilder & set_iterations(size_t iterations);

        LDABuilder & set_workers(size_t workers);

        std::shared_ptr<em::EStepInterface<Scalar> > get_classic_e_step(
            size_t e_step_iterations = 10,
            Scalar e_step_tolerance = 1e-2,
            Scalar compute_likelihood = 1.0,
            int random_state = 0
        );
        LDABuilder & set_classic_e_step(
            size_t e_step_iterations = 10,
            Scalar e_step_tolerance = 1e-2,
            Scalar compute_likelihood = 1.0,
            int random_state = 0
        ) {
            e_requires_eta_ = false;
            return set_e(get_classic_e_step(
                e_step_iterations,
                e_step_tolerance,
                compute_likelihood,
                random_state
            ));
        }

        std::shared_ptr<em::EStepInterface<Scalar> > get_supervised_e_step(
            size_t e_step_iterations = 10,
            Scalar e_step_tolerance = 1e-2,
            size_t fixed_point_iterations = 10,
            Scalar compute_likelihood = 1.0,
            int random_state = 0
        );
        LDABuilder & set_supervised_e_step(
            size_t e_step_iterations = 10,
            Scalar e_step_tolerance = 1e-2,
            size_t fixed_point_iterations = 10,
            Scalar compute_likelihood = 1.0,
            int random_state = 0
        ) {
            set_e(get_supervised_e_step(
                e_step_iterations,
                e_step_tolerance,
                fixed_point_iterations,
                compute_likelihood,
                random_state
            ));
            e_requires_eta_ = true;
            return *this;
        }

        std::shared_ptr<em::EStepInterface<Scalar> > get_fast_supervised_e_step(
            size_t e_step_iterations = 10,
            Scalar e_step_tolerance = 1e-2,
            Scalar C = 1,
            Scalar compute_likelihood = 1.0,
            int random_state = 0
        );
        LDABuilder & set_fast_supervised_e_step(
            size_t e_step_iterations = 10,
            Scalar e_step_tolerance = 1e-2,
            Scalar C = 1,
            Scalar compute_likelihood = 1.0,
            int random_state = 0
        ) {
            set_e(get_fast_supervised_e_step(
                e_step_iterations,
                e_step_tolerance,
                C,
                compute_likelihood,
                random_state
            ));
            e_requires_eta_ = true;
            return *this;
        }

        std::shared_ptr<em::EStepInterface<Scalar> > get_semi_supervised_e_step(
            std::shared_ptr<em::EStepInterface<Scalar> > supervised_step = nullptr,
            std::shared_ptr<em::EStepInterface<Scalar> > unsupervised_step = nullptr
        );
        LDABuilder & set_semi_supervised_e_step(
            std::shared_ptr<em::EStepInterface<Scalar> > supervised_step = nullptr,
            std::shared_ptr<em::EStepInterface<Scalar> > unsupervised_step = nullptr
        ) {
            set_e(get_semi_supervised_e_step(
                supervised_step,
                unsupervised_step
            ));
            e_requires_eta_ = true;
            return *this;
        }

        std::shared_ptr<em::EStepInterface<Scalar> > get_multinomial_supervised_e_step(
            size_t e_step_iterations = 10,
            Scalar e_step_tolerance = 1e-2,
            Scalar mu = 2,
            Scalar eta_weight = 1,
            Scalar compute_likelihood = 1.0,
            int random_state = 0
        );
        LDABuilder & set_multinomial_supervised_e_step(
            size_t e_step_iterations = 10,
            Scalar e_step_tolerance = 1e-2,
            Scalar mu = 2,
            Scalar eta_weight = 1,
            Scalar compute_likelihood = 1.0,
            int random_state = 0
        ) {
            set_e(get_multinomial_supervised_e_step(
                e_step_iterations,
                e_step_tolerance,
                mu,
                eta_weight,
                compute_likelihood,
                random_state
            ));
            e_requires_eta_ = true;
            return *this;
        }

        std::shared_ptr<em::EStepInterface<Scalar> > get_correspondence_supervised_e_step(
            size_t e_step_iterations = 10,
            Scalar e_step_tolerance = 1e-2,
            Scalar mu = 2,
            Scalar compute_likelihood = 1.0,
            int random_state = 0
        );
        LDABuilder & set_correspondence_supervised_e_step(
            size_t e_step_iterations = 10,
            Scalar e_step_tolerance = 1e-2,
            Scalar mu = 2,
            Scalar compute_likelihood = 1.0,
            int random_state = 0
        ) {
            set_e(get_correspondence_supervised_e_step(
                e_step_iterations,
                e_step_tolerance,
                mu,
                compute_likelihood,
                random_state
            ));
            e_requires_eta_ = true;
            return *this;
        }

        LDABuilder & set_e(std::shared_ptr<em::EStepInterface<Scalar> > e_step) {
            e_requires_eta_ = false; // clear require eta because we do not know
                                     // this e_step
            e_step_ = e_step;
            return *this;
        }

        std::shared_ptr<em::MStepInterface<Scalar> > get_classic_m_step();
        LDABuilder & set_classic_m_step() {
            set_m(get_classic_m_step());
            m_requires_eta_ = false;
            return *this;
        }

        std::shared_ptr<em::MStepInterface<Scalar> > get_fast_supervised_m_step(
            size_t m_step_iterations = 10,
            Scalar m_step_tolerance = 1e-2,
            Scalar regularization_penalty = 1e-2
        );
        LDABuilder & set_fast_supervised_m_step(
            size_t m_step_iterations = 10,
            Scalar m_step_tolerance = 1e-2,
            Scalar regularization_penalty = 1e-2
        ) {
            set_m(get_fast_supervised_m_step(
                m_step_iterations,
                m_step_tolerance,
                regularization_penalty
            ));
            m_requires_eta_ = true;
            return *this;
        }

        std::shared_ptr<em::MStepInterface<Scalar> > get_supervised_m_step(
            size_t m_step_iterations = 10,
            Scalar m_step_tolerance = 1e-2,
            Scalar regularization_penalty = 1e-2
        );
        LDABuilder & set_supervised_m_step(
            size_t m_step_iterations = 10,
            Scalar m_step_tolerance = 1e-2,
            Scalar regularization_penalty = 1e-2
        ) {
            set_m(get_supervised_m_step(
                m_step_iterations,
                m_step_tolerance,
                regularization_penalty
            ));
            m_requires_eta_ = true;
            return *this;
        }

        std::shared_ptr<em::MStepInterface<Scalar> > get_fast_supervised_online_m_step(
            size_t num_classes,
            Scalar regularization_penalty = 1e-2,
            size_t minibatch_size = 128,
            Scalar eta_momentum = 0.9,
            Scalar eta_learning_rate = 0.01,
            Scalar beta_weight = 0.9
        );
        LDABuilder & set_fast_supervised_online_m_step(
            size_t num_classes,
            Scalar regularization_penalty = 1e-2,
            size_t minibatch_size = 128,
            Scalar eta_momentum = 0.9,
            Scalar eta_learning_rate = 0.01,
            Scalar beta_weight = 0.9
        ) {
            set_m(get_fast_supervised_online_m_step(
                num_classes,
                regularization_penalty,
                minibatch_size,
                eta_momentum,
                eta_learning_rate,
                beta_weight
            ));
            m_requires_eta_ = true;
            return *this;
        }

        std::shared_ptr<em::MStepInterface<Scalar> > get_fast_supervised_online_m_step(
            std::vector<Scalar> class_weights,
            Scalar regularization_penalty = 1e-2,
            size_t minibatch_size = 128,
            Scalar eta_momentum = 0.9,
            Scalar eta_learning_rate = 0.01,
            Scalar beta_weight = 0.9
        );
        LDABuilder & set_fast_supervised_online_m_step(
            std::vector<Scalar> class_weights,
            Scalar regularization_penalty = 1e-2,
            size_t minibatch_size = 128,
            Scalar eta_momentum = 0.9,
            Scalar eta_learning_rate = 0.01,
            Scalar beta_weight = 0.9
        ) {
            set_m(get_fast_supervised_online_m_step(
                class_weights,
                regularization_penalty,
                minibatch_size,
                eta_momentum,
                eta_learning_rate,
                beta_weight
            ));
            m_requires_eta_ = true;
            return *this;
        }

        std::shared_ptr<em::MStepInterface<Scalar> > get_fast_supervised_online_m_step(
            Eigen::Matrix<Scalar, Eigen::Dynamic, 1> class_weights,
            Scalar regularization_penalty = 1e-2,
            size_t minibatch_size = 128,
            Scalar eta_momentum = 0.9,
            Scalar eta_learning_rate = 0.01,
            Scalar beta_weight = 0.9
        );
        LDABuilder & set_fast_supervised_online_m_step(
            Eigen::Matrix<Scalar, Eigen::Dynamic, 1> class_weights,
            Scalar regularization_penalty = 1e-2,
            size_t minibatch_size = 128,
            Scalar eta_momentum = 0.9,
            Scalar eta_learning_rate = 0.01,
            Scalar beta_weight = 0.9
        ) {
            set_m(get_fast_supervised_online_m_step(
                class_weights,
                regularization_penalty,
                minibatch_size,
                eta_momentum,
                eta_learning_rate,
                beta_weight
            ));
            m_requires_eta_ = true;
            return *this;
        }

        std::shared_ptr<em::MStepInterface<Scalar> > get_semi_supervised_m_step(
            size_t m_step_iterations = 10,
            Scalar m_step_tolerance = 1e-2,
            Scalar regularization_penalty = 1e-2
        );
        LDABuilder & set_semi_supervised_m_step(
            size_t m_step_iterations = 10,
            Scalar m_step_tolerance = 1e-2,
            Scalar regularization_penalty = 1e-2
        ) {
            set_m(get_semi_supervised_m_step(
                m_step_iterations,
                m_step_tolerance,
                regularization_penalty
            ));
            m_requires_eta_ = true;
            return *this;
        }

        std::shared_ptr<em::MStepInterface<Scalar> > get_multinomial_supervised_m_step(
            Scalar mu = 2.
        );
        LDABuilder & set_multinomial_supervised_m_step(
            Scalar mu = 2.
        ) {
            set_m(get_multinomial_supervised_m_step(mu));
            m_requires_eta_ = true;
            return *this;
        }

        std::shared_ptr<em::MStepInterface<Scalar> > get_correspondence_supervised_m_step(
            Scalar mu = 2.
        );
        LDABuilder & set_correspondence_supervised_m_step(
            Scalar mu = 2.
        ) {
            set_m(get_correspondence_supervised_m_step(mu));
            m_requires_eta_ = true;
            return *this;
        }

        LDABuilder & set_m(std::shared_ptr<em::MStepInterface<Scalar> > m_step) {
            m_requires_eta_ = false; // clear require eta because we do not know
                                     // this m_step
            m_step_ = m_step;
            return *this;
        }

        LDABuilder & initialize_topics_seeded(
            const Eigen::MatrixXi &X,
            size_t topics,
            size_t N = 30,
            int random_state = 0
        );

        LDABuilder & initialize_topics_seeded(
            std::shared_ptr<corpus::Corpus> corpus,
            size_t topics,
            size_t N = 30,
            int random_state = 0
        );

        LDABuilder & initialize_topics_random(
            size_t words,
            size_t topics,
            int random_state = 0
        );

        LDABuilder & initialize_topics_from_model(
            std::shared_ptr<parameters::ModelParameters<Scalar> > model
        ) {
            model_parameters_->alpha = model->alpha;
            model_parameters_->beta = model->beta;

            return *this;
        }

        LDABuilder & initialize_eta_zeros(size_t num_classes);

        LDABuilder & initialize_eta_uniform(size_t num_classes);

        LDABuilder & initialize_eta_from_model(
            std::shared_ptr<parameters::SupervisedModelParameters<Scalar> > model
        ) {
            model_parameters_->eta = model->eta;

            return *this;
        }

        virtual operator LDA<Scalar>() const override {
            if (model_parameters_->beta.rows() == 0) {
                throw std::runtime_error("You need to call initialize_topics before "
                                         "creating an LDA from the builder.");
            }

            if (
                model_parameters_->eta.rows() == 0 &&
                (e_requires_eta_ || m_requires_eta_)
            ) {
                throw std::runtime_error("An E step or M step seems to be supervised "
                                         "yet you have not initialized eta. "
                                         "Call initialize_eta_*()");
            }

            return LDA<Scalar>(
                model_parameters_,
                e_step_,
                m_step_,
                iterations_,
                workers_
            );
        };

    private:
        // generic lda parameters
        size_t iterations_;
        size_t workers_;

        // implementations
        std::shared_ptr<em::EStepInterface<Scalar> > e_step_;
        std::shared_ptr<em::MStepInterface<Scalar> > m_step_;

        // the model parameters
        std::shared_ptr<parameters::SupervisedModelParameters<Scalar> > model_parameters_;

        // A flag to keep track of having set EM steps that require the eta
        // model parameters.
        bool e_requires_eta_;
        bool m_requires_eta_;
};


} // namespace ldaplusplus
#endif  // _LDAPLUSPLUS_LDABUILDER_HPP_