time_series.h

Go to the documentation of this file.

/*********************************************************************
 *
 *  Software License Agreement
 *
 *  Copyright (c) 2020,
 *  TU Dortmund - Institute of Control Theory and Systems Engineering.
 *  All rights reserved.
 *
 *  This program 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.
 *
 *  This program 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 this program.  If not, see <https://www.gnu.org/licenses/>.
 *
 *  Authors: Christoph Rösmann
 *********************************************************************/

#ifndef SRC_CORE_INCLUDE_CORBO_CORE_TIME_SERIES_H_
#define SRC_CORE_INCLUDE_CORBO_CORE_TIME_SERIES_H_

#include <corbo-core/types.h>

#ifdef MESSAGE_SUPPORT
#include <corbo-communication/messages/core/time_series.pb.h>
#include <corbo-communication/messages/core/time_series_sequence.pb.h>
#endif

#include <memory>
#include <string>
#include <vector>

namespace corbo {

class TimeSeries
{
 public:
    enum class Interpolation { ZeroOrderHold, Linear };
    enum class Extrapolation { NoExtrapolation, ZeroOrderHold };
    enum class Normalization { FirstValue, AbsoluteMaximum, Maximum, Mean };

    using Ptr               = std::shared_ptr<TimeSeries>;
    using ConstPtr          = std::shared_ptr<const TimeSeries>;
    using ValuesMatMap      = Eigen::Map<Eigen::Matrix<double, Eigen::Dynamic, Eigen::Dynamic, Eigen::ColMajor>>;
    using ValuesMatConstMap = Eigen::Map<const Eigen::Matrix<double, Eigen::Dynamic, Eigen::Dynamic, Eigen::ColMajor>>;
    using TimeVecMap        = Eigen::Map<Eigen::VectorXd>;
    using TimeVecConstMap   = Eigen::Map<const Eigen::VectorXd>;

    TimeSeries() {}
    explicit TimeSeries(int value_dim) : _value_dim(value_dim) {}

    virtual ~TimeSeries() {}

    int getValueDimension() const { return _value_dim; }
    int getTimeDimension() const { return (int)_time.size(); }
    bool isEmpty() const { return _time.empty(); }
    bool isColumnMajor() const { return true; }

    // manipulation
    void setValueDimension(int value_dim);
    void reserve(int time_dim, int value_dim);

    bool add(double time, const std::vector<double>& values);
    bool add(double time, const Eigen::Ref<const Eigen::VectorXd>& values);

    bool set(const Eigen::Ref<const Eigen::VectorXd>& time, const Eigen::Ref<const Eigen::MatrixXd>& values_matrix, double time_from_start = 0.0);

    bool set(const std::vector<double>& time, const std::vector<Eigen::VectorXd>& values_vector, double time_from_start = 0.0);

    void clear();

    const std::vector<std::string>& getValueLabels() const { return _value_labels; }
    std::vector<std::string>& getValueLabelsRef() { return _value_labels; }

    // accessors
    std::vector<double> getValues(int time_idx) const;
    Eigen::Map<const Eigen::VectorXd> getValuesMap(int time_idx) const;

    virtual bool getValuesInterpolate(double time, Eigen::Ref<Eigen::VectorXd> values, Interpolation interpolation = Interpolation::Linear,
                                      Extrapolation extrapolate = Extrapolation::NoExtrapolation, double tolerance = 1e-6) const;

    const std::vector<double>& getValues() const { return _values; }
    std::vector<double>& getValuesRef() { return _values; }
    ValuesMatConstMap getValuesMatrixView() const { return ValuesMatConstMap(_values.data(), _value_dim, getTimeDimension()); }
    ValuesMatMap getValuesMatrixView() { return ValuesMatMap(_values.data(), _value_dim, getTimeDimension()); }

    const std::vector<double>& getTime() const { return _time; }
    std::vector<double>& getTimeRef() { return _time; }
    TimeVecConstMap getTimeVectorView() const { return TimeVecConstMap(_time.data(), _time.size()); }
    TimeVecMap getTimeVectorView() { return TimeVecMap(_time.data(), _time.size()); }

    const double& getTimeFromStart() const { return _time_from_start; }
    void setTimeFromStart(double tfs) { _time_from_start = tfs; }

    double getFinalTime() const { return _time.empty() ? 0.0 : _time.back(); }

    virtual double computeMeanOverall();
    virtual void computeMeanCwise(Eigen::Ref<Eigen::VectorXd> mean_values);

    virtual void normalize(Normalization norm_method, bool value_cwise = true);

    virtual void normalize(Normalization norm_method, int value_idx);

#ifdef MESSAGE_SUPPORT
    bool toMessage(corbo::messages::TimeSeries& message) const;
    bool fromMessage(const corbo::messages::TimeSeries& message, std::stringstream* issues = nullptr);
#endif

    void print(int precision = 2) const;

    friend std::ostream& operator<<(std::ostream& out, const TimeSeries& ts);

    // overloaded operators
    // friend std::ostream& operator<<(std::ostream& os, const std::vector<double>& values) {add()}

 protected:
    // We implement our own column-major matrix layout with std::vector<double>
    // instead of relying on Eigens implementation Eigen::MatrixXd
    // since we want to support a dedicated container capacity which might
    // be larger than the current size (see std::vector::reserve).
    // We assume that data is frequently appended/added during data recording.
    // Indeed, Eigen provides a conservativeResize method which utilizes std::reallocate
    // whenever columns are added in a column-major layout, but it is not guaranteed that
    // there is enough memory capacity to avoid copies completely.
    int _value_dim = 0;           // we could infer this from values.size()/time.size() but we do not want to compute this every lookup
    std::vector<double> _values;  
    std::vector<double> _time;

    double _time_from_start = 0.0;  

    std::vector<std::string> _value_labels;  
};

class TimeSeriesSequence
{
 public:
    using Ptr      = std::shared_ptr<TimeSeriesSequence>;
    using ConstPtr = std::shared_ptr<const TimeSeriesSequence>;

    TimeSeriesSequence() {}

    explicit TimeSeriesSequence(int value_dim) : _value_dim(value_dim) {}

    int getValueDimension() const { return _value_dim; }
    bool isEmpty() const { return _ts_sequence.empty(); }

    // manipulation
    void setValueDimension(int value_dim);

    bool add(TimeSeries::Ptr ts);

    const std::vector<TimeSeries::Ptr>& getSequence() const { return _ts_sequence; }

    void clear();

    void sortByTimeFromStart();

#ifdef MESSAGE_SUPPORT
    bool toMessage(corbo::messages::TimeSeriesSequence& message) const;
    bool fromMessage(const corbo::messages::TimeSeriesSequence& message, std::stringstream* issues = nullptr);
#endif

 private:
    std::vector<TimeSeries::Ptr> _ts_sequence;

    int _value_dim = 0;  
};

}  // namespace corbo

#endif  // SRC_CORE_INCLUDE_CORBO_CORE_TIME_SERIES_H_