xmmGaussianDistribution.hpp

Go to the documentation of this file.

/*
 * xmmGaussianDistribution.hpp
 *
 * Multivariate Gaussian Distribution
 *
 * Contact:
 * - Jules Francoise <jules.francoise@ircam.fr>
 *
 * This code has been initially authored by Jules Francoise
 * <http://julesfrancoise.com> during his PhD thesis, supervised by Frederic
 * Bevilacqua <href="http://frederic-bevilacqua.net>, in the Sound Music
 * Movement Interaction team <http://ismm.ircam.fr> of the
 * STMS Lab - IRCAM, CNRS, UPMC (2011-2015).
 *
 * Copyright (C) 2015 UPMC, Ircam-Centre Pompidou.
 *
 * This File is part of XMM.
 *
 * XMM is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * XMM is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with XMM.  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef xmmGaussianDistribution_h
#define xmmGaussianDistribution_h

#include "../common/xmmAttribute.hpp"
#include "../common/xmmJson.hpp"

namespace xmm {
struct Ellipse {
    float x;

    float y;

    float width;

    float height;

    float angle;
};

class GaussianDistribution : public Writable {
  public:
    enum class CovarianceMode {
        Full = 0,

        Diagonal = 1
    };

    GaussianDistribution(bool bimodal = false, unsigned int dimension = 1,
                         unsigned int dimension_input = 0,
                         CovarianceMode covariance_mode = CovarianceMode::Full);

    GaussianDistribution(GaussianDistribution const& src);

    explicit GaussianDistribution(Json::Value const& root);

    GaussianDistribution& operator=(GaussianDistribution const& src);


    double likelihood(const float* observation) const;

    double likelihood_input(const float* observation_input) const;

    double likelihood_bimodal(const float* observation_input,
                              const float* observation_output) const;

    void regression(std::vector<float> const& observation_input,
                    std::vector<float>& predicted_output) const;



    void regularize(std::vector<double> regularization);

    void updateInverseCovariance();

    Ellipse toEllipse(unsigned int dimension1, unsigned int dimension2);

    void fromEllipse(Ellipse const& gaussian_ellipse, unsigned int dimension1,
                     unsigned int dimension2);



    Json::Value toJson() const;

    void fromJson(Json::Value const& root);


    //        /** @name Conversion & Extraction */
    //        ///@{
    //
    //        /**
    //         @brief Convert to bimodal distribution in place
    //         @param dimension_input dimension of the input modality
    //         @throws runtime_error if the model is already bimodal
    //         @throws out_of_range if the requested input dimension is too
    //         large
    //         */
    //        void makeBimodal(unsigned int dimension_input);
    //
    //        /**
    //         @brief Convert to unimodal distribution in place
    //         @throws runtime_error if the model is already unimodal
    //         */
    //        void makeUnimodal();
    //
    //        /**
    //         @brief extract a sub-distribution with the given columns
    //         @param columns columns indices in the target order
    //         @throws runtime_error if the model is training
    //         @throws out_of_range if the number or indices of the requested
    //         columns exceeds the current dimension
    //         @return a Gaussian Distribution from the current model
    //         considering only the target columns
    //         */
    //        GaussianDistribution extractSubmodel(std::vector<unsigned int>&
    //        columns) const;
    //
    //        /**
    //         @brief extract the sub-distribution of the input modality
    //         @throws runtime_error if the model is training or if it is not
    //         bimodal
    //         @return a unimodal Gaussian Distribution of the input modality
    //         from the current bimodal model
    //         */
    //        GaussianDistribution extractSubmodel_input() const;
    //
    //        /**
    //         @brief extract the sub-distribution of the output modality
    //         @throws runtime_error if the model is training or if it is not
    //         bimodal
    //         @return a unimodal Gaussian Distribution of the output modality
    //         from the current bimodal model
    //         */
    //        GaussianDistribution extractSubmodel_output() const;
    //
    //        /**
    //         @brief extract the model with reversed input and output
    //         modalities
    //         @throws runtime_error if the model is training or if it is not
    //         bimodal
    //         @return a bimodal Gaussian Distribution  that swaps the input and
    //         output modalities
    //         */
    //        GaussianDistribution extract_inverse_model() const;
    //
    //        ///@}

    Attribute<unsigned int> dimension;

    Attribute<unsigned int> dimension_input;

    std::vector<double> mean;

    Attribute<CovarianceMode> covariance_mode;

    std::vector<double> covariance;

    std::vector<double> output_covariance;

  protected:
    void allocate();

    virtual void onAttributeChange(AttributeBase* attr_pointer);

    void updateOutputCovariance();

    bool bimodal_;

    double covariance_determinant_;

    std::vector<double> inverse_covariance_;

    double covariance_determinant_input_;

    std::vector<double> inverse_covariance_input_;
};

Ellipse covariance2ellipse(double c_xx, double c_xy, double c_yy);

template <>
void checkLimits<GaussianDistribution::CovarianceMode>(
    GaussianDistribution::CovarianceMode const& value,
    GaussianDistribution::CovarianceMode const& limit_min,
    GaussianDistribution::CovarianceMode const& limit_max);

template <>
GaussianDistribution::CovarianceMode
Attribute<GaussianDistribution::CovarianceMode>::defaultLimitMax();
}

#endif