OpenStudio:utilities
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Pages
List of all members
openstudio::TimeSeries Class Reference

#include <TimeSeries.hpp>

Public Member Functions

Constructors
 TimeSeries ()
 Default constructor with no data. More...
 
 TimeSeries (const Date &startDate, const Time &intervalLength, const Vector &values, const std::string &units)
 Constructor from start date, interval length, values, and units. More...
 
 TimeSeries (const DateTime &firstReportDateTime, const Time &intervalLength, const Vector &values, const std::string &units)
 Constructor from first report date and time, interval length, values, and units. More...
 
 TimeSeries (const DateTime &firstReportDateTime, const Vector &timeInDays, const Vector &values, const std::string &units)
 Constructor from first report date and time, time in days, values, and units. More...
 
 TimeSeries (const DateTime &firstReportDateTime, const std::vector< double > &timeInDays, const std::vector< double > &values, const std::string &units)
 Constructor from first report date and time, time in days, values, and units. More...
 
 TimeSeries (const DateTimeVector &dateTimes, const Vector &values, const std::string &units)
 Constructor from date times, values, and units. More...
 
 TimeSeries (const DateTime &firstReportDateTime, const std::vector< long > &timeInSeconds, const Vector &values, const std::string &units)
 Constructor from first report date and time, time in seconds, values, and units. More...
 
 ~TimeSeries ()=default
 Virtual destructor. More...
 
Getters
openstudio::OptionalTime intervalLength () const
 Returns the interval length if any. More...
 
openstudio::DateTimeVector dateTimes () const
 Returns the date and times at which values are reported, these are the end of each reporting interval. More...
 
openstudio::DateTime firstReportDateTime () const
 Returns the date and time of first report value. More...
 
openstudio::DateTime startDateTime () const
 Returns the date and time of start value. More...
 
openstudio::Vector daysFromFirstReport () const
 Returns the vector of time in days from end of the first reporting interval. More...
 
double daysFromFirstReport (unsigned int i) const
 Returns the time in days from end of the first reporting interval at index i to prevent implicit vector copy for single value. More...
 
std::vector< long > secondsFromFirstReport () const
 Returns the time in seconds from end of the first reporting interval. More...
 
long secondsFromFirstReport (unsigned int i) const
 Return the time in seconds from end of the first reporting interval at index i to prevent implicit vector copy for single value. More...
 
openstudio::Vector values () const
 Returns the values vector. More...
 
double values (unsigned int i) const
 Returns the value at index i to prevent implicit vector copy for single value. More...
 
const std::string units () const
 Returns the series units as a standard string. More...
 
double value (double daysFromFirstReport) const
 Get value at number of days from first report date and time. More...
 
double value (const Time &timeFromFirstReport) const
 Get value at time from first report date and time. More...
 
double value (const DateTime &dateTime) const
 Get value at date and time. More...
 
Vector values (const DateTime &startDateTime, const DateTime &endDateTime) const
 Get values between start and end date times. More...
 
double outOfRangeValue () const
 Get the value used for out of range data. More...
 
Setters
void setOutOfRangeValue (double value)
 Set the value used for out of range data, defaults to 0. More...
 
Operators
TimeSeries operator+ (const TimeSeries &other) const
 Add timeseries. More...
 
TimeSeries operator- (const TimeSeries &other) const
 Subtract timeseries. More...
 
TimeSeries operator* (double d) const
 TimeSeries * double. More...
 
TimeSeries operator/ (double d) const
 TimeSeries / double. More...
 
Analysis Functions
double integrate () const
 Integrate the time series. More...
 
double averageValue () const
 Compute the time series average value. More...
 

Detailed Description

TimeSeries is a series of values each reported at a single time.

We follow the EnergyPlus convention that the time reported for each value is at the end of the reporting interval. For example, if a value is measured over the interval from hour 1 (non-inclusive) to hour 2 (inclusive), that is 1 < t <= 2, and the reported value (either the average, median, min, max, etc) is determined to be 7, then the value 7 is reported at hour 2. One of the primary tasks of the TimeSeries class is to get the value of the series at an arbitrary time. For the example above, any time in the interval 1 < t <= 2 will return 7. We refer to the beginning of the first reporting interval as the startDateTime. The end of the first interval is referred to as the firstReportDateTime.

Todo: add method to mark TimeSeries that represent point in time measurements rather than interval measurements

Todo: add calendar to deal with Daylight Savings

Constructor & Destructor Documentation

openstudio::TimeSeries::TimeSeries ( )

Default constructor with no data.

openstudio::TimeSeries::TimeSeries ( const Date startDate,
const Time intervalLength,
const Vector &  values,
const std::string &  units 
)

Constructor from start date, interval length, values, and units.

First reporting interval starts at 0 hours on startDate and ends at startDate + intervalLength.

openstudio::TimeSeries::TimeSeries ( const DateTime firstReportDateTime,
const Time intervalLength,
const Vector &  values,
const std::string &  units 
)

Constructor from first report date and time, interval length, values, and units.

First reporting interval starts at firstReportDateTime - intervalLength and ends at firstReportDateTime.

openstudio::TimeSeries::TimeSeries ( const DateTime firstReportDateTime,
const Vector &  timeInDays,
const Vector &  values,
const std::string &  units 
)

Constructor from first report date and time, time in days, values, and units.

The treatment of the time vector depends upon the value of the first element:

  • If timeInDays[0] == 0 then the first reporting interval starts at 0 hours on the firstReportDateTime's date and ends at firstReportDateTime.
  • If timeInDays[0] > 0 then the first reporting interval starts at firstReportDateTime - timeInDays[0] and ends at firstReportDateTime.

An exception is thrown if:

  • timeInDays.size != values.size
  • timeInDays is not monotonically increasing
  • the start date and time of first reporting interval cannot be determined
openstudio::TimeSeries::TimeSeries ( const DateTime firstReportDateTime,
const std::vector< double > &  timeInDays,
const std::vector< double > &  values,
const std::string &  units 
)

Constructor from first report date and time, time in days, values, and units.

The treatment of the time vector depends upon the value of the first element:

  • If timeInDays[0] == 0 then the first reporting interval starts at 0 hours on the firstReportDateTime's date and ends at firstReportDateTime.
  • If timeInDays[0] > 0 then the first reporting interval starts at firstReportDateTime - timeInDays[0] and ends at firstReportDateTime.

An exception is thrown if:

  • timeInDays.size != values.size
  • timeInDays is not monotonically increasing
  • the start date and time of first reporting interval cannot be determined
openstudio::TimeSeries::TimeSeries ( const DateTimeVector &  dateTimes,
const Vector &  values,
const std::string &  units 
)

Constructor from date times, values, and units.

The size of the dateTimes vector determines how it is handled:

  • If dateTimes.size == values.size then the first reporting interval starts at 0 hours on dateTimes[0]'s date and ends at dateTimes[0].
  • If dateTimes.size == values.size + 1 then the first reporting interval starts at dateTimes[0] and ends at dateTimes[1].

An exception is thrown if:

  • (timeInDays.size != values.size) and (timeInDays.size != values.size + 1)
  • the start date and time of first reporting interval cannot be determined
openstudio::TimeSeries::TimeSeries ( const DateTime firstReportDateTime,
const std::vector< long > &  timeInSeconds,
const Vector &  values,
const std::string &  units 
)

Constructor from first report date and time, time in seconds, values, and units.

The treatment of the time vector depends upon the value of the first element:

  • If timeInSeconds[0] == 0 then the first reporting interval starts at 0 hours on the firstReportDateTime's date and ends at firstReportDateTime.
  • If timeInSeconds[0] > 0 then the first reporting interval starts at firstReportDateTime - timeInSeconds[0] and ends at firstReportDateTime.

An exception is thrown if:

  • timeInSeconds.size != values.size
  • timeInSeconds is not monotonically increasing
  • start date and time of first reporting interval cannot be determined
openstudio::TimeSeries::~TimeSeries ( )
default

Virtual destructor.

Member Function Documentation

double openstudio::TimeSeries::averageValue ( ) const

Compute the time series average value.

openstudio::DateTimeVector openstudio::TimeSeries::dateTimes ( ) const

Returns the date and times at which values are reported, these are the end of each reporting interval.

openstudio::Vector openstudio::TimeSeries::daysFromFirstReport ( ) const

Returns the vector of time in days from end of the first reporting interval.

double openstudio::TimeSeries::daysFromFirstReport ( unsigned int  i) const

Returns the time in days from end of the first reporting interval at index i to prevent implicit vector copy for single value.

openstudio::DateTime openstudio::TimeSeries::firstReportDateTime ( ) const

Returns the date and time of first report value.

double openstudio::TimeSeries::integrate ( ) const

Integrate the time series.

openstudio::OptionalTime openstudio::TimeSeries::intervalLength ( ) const

Returns the interval length if any.

TimeSeries openstudio::TimeSeries::operator* ( double  d) const

TimeSeries * double.

TimeSeries openstudio::TimeSeries::operator+ ( const TimeSeries other) const

Add timeseries.

TimeSeries openstudio::TimeSeries::operator- ( const TimeSeries other) const

Subtract timeseries.

TimeSeries openstudio::TimeSeries::operator/ ( double  d) const

TimeSeries / double.

double openstudio::TimeSeries::outOfRangeValue ( ) const

Get the value used for out of range data.

std::vector<long> openstudio::TimeSeries::secondsFromFirstReport ( ) const

Returns the time in seconds from end of the first reporting interval.

long openstudio::TimeSeries::secondsFromFirstReport ( unsigned int  i) const

Return the time in seconds from end of the first reporting interval at index i to prevent implicit vector copy for single value.

void openstudio::TimeSeries::setOutOfRangeValue ( double  value)

Set the value used for out of range data, defaults to 0.

openstudio::DateTime openstudio::TimeSeries::startDateTime ( ) const

Returns the date and time of start value.

const std::string openstudio::TimeSeries::units ( ) const

Returns the series units as a standard string.

double openstudio::TimeSeries::value ( double  daysFromFirstReport) const

Get value at number of days from first report date and time.

double openstudio::TimeSeries::value ( const Time timeFromFirstReport) const

Get value at time from first report date and time.

double openstudio::TimeSeries::value ( const DateTime dateTime) const

Get value at date and time.

openstudio::Vector openstudio::TimeSeries::values ( ) const

Returns the values vector.

double openstudio::TimeSeries::values ( unsigned int  i) const

Returns the value at index i to prevent implicit vector copy for single value.

Vector openstudio::TimeSeries::values ( const DateTime startDateTime,
const DateTime endDateTime 
) const

Get values between start and end date times.