TimeSeries.h
Go to the documentation of this file.
1 /* Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.
2 
3  This file is part of the TerraLib - a Framework for building GIS enabled applications.
4 
5  TerraLib is free software: you can redistribute it and/or modify
6  it under the terms of the GNU Lesser General Public License as published by
7  the Free Software Foundation, either version 3 of the License,
8  or (at your option) any later version.
9 
10  TerraLib is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU Lesser General Public License for more details.
14 
15  You should have received a copy of the GNU Lesser General Public License
16  along with TerraLib. See COPYING. If not, write to
17  TerraLib Team at <terralib-team@terralib.org>.
18 */
19 
20 /*!
21  \file TimeSeries.h
22 
23  \brief This file contains a class to represent a time series.
24 */
25 
26 #ifndef __TERRALIB_ST_INTERNAL_TIMESERIES_H
27 #define __TERRALIB_ST_INTERNAL_TIMESERIES_H
28 
29 //STL
30 #include <vector>
31 #include <map>
32 #include <memory>
33 
34 //TerraLib
35 #include "../../../datatype/Enums.h"
36 
37 //ST
38 #include "../../Config.h"
39 #include "TimeSeriesIterator.h"
40 
41 // Forward declarations
42 namespace te { namespace dt { class AbstractData; class DateTime; class DateTimePeriod; } }
43 namespace te { namespace gm { class Geometry; } }
44 
45 namespace te
46 {
47  namespace st
48  {
49  // Forward declarations
50  class AbstractTimeSeriesInterp;
51 
52  /*!
53  \class TimeSeries
54 
55  \brief A class to represent time series.
56 
57  A time series represents a variation of a property over time, where
58  this property is of a textual or numerical type (T -> A).
59  It is composed of a set of observations and of an interpolator able
60  to estimate values in non-observed times.
61 
62  \ingroup st
63 
64  \sa ObservationSet AbstractInterpolator
65  */
67  {
68  public:
69 
70  /*! \name TimeSeries Constructors */
71  //@{
72 
73  /*!
74  \brief Empty constructor.
75 
76  It constructs an empty time series. The user does not indicate the interpolator
77  associated to it. Internally, it uses a default interpolator
78  that is NearestValueAtTimeInterp.
79  */
80  TimeSeries();
81 
82  /*!
83  \brief Empty constructor.
84 
85  It constructs an empty time series. The user does not indicate the interpolator
86  associated to it. Internally, it uses a default interpolator
87  that is NearestValueAtTimeInterp.
88 
89  \param id The time series id
90  */
91  TimeSeries(const std::string& id);
92 
93  /*!
94  \brief Empty constructor.
95 
96  It constructs an empty trajectory.
97 
98  \param id The time series id.
99  \param interp The interpolator associated to the time series.
100 
101  */
102  TimeSeries(AbstractTimeSeriesInterp* interp, const std::string& id);
103 
104  /*!
105  \brief Empty constructor.
106 
107  It constructs an empty trajectory.
108 
109  \param interp The interpolator associated to the time series.
110  \param id The time series id.
111  \param geom The time series location.
112 
113  \note It will take the ownership of the given geometry.
114  */
115  TimeSeries(AbstractTimeSeriesInterp* interp, const std::string& id,
116  te::gm::Geometry* geom);
117 
118  /*!
119  \brief Constructor.
120 
121  \param obs The time series observations.
122  \param interp The interpolator associated to the time series.
123  \param id The time series id.
124  \param geom The time series location.
125 
126  \note It will take the ownership of the given geometry.
127  */
129  const std::string& id, te::gm::Geometry* geom);
130  /*!
131  \brief It constructs a time series from a patch
132 
133  \param patch The given patch.
134  \param interp The interpolator
135  \param id The time series id
136  \param geom The time series location
137  */
138  TimeSeries(const TimeSeriesPatch& patch, AbstractTimeSeriesInterp* interp,
139  const std::string& id, te::gm::Geometry* geom);
140 
141  /*!
142  \brief Copy constructor.
143 
144  \note The built time series will share the internal pointers of "ts".
145  \note The caller has to use the method "clone" to have a deep copy.
146  */
147  TimeSeries(const TimeSeries& ts);
148  //@}
149 
150  /*!
151  \brief Copy assignment operator
152 
153  \note They will share the internal pointers.
154  \note The caller has to use the method "clone" to have a deep copy.
155  */
156  TimeSeries& operator=(const TimeSeries& other);
157 
158  /*!
159  \brief It returns a clone of this time series.
160 
161  \return A new time series.
162 
163  \note The caller will take the ownership of the returned pointer.
164  */
165  TimeSeries* clone() const;
166 
167  /*!
168  \brief It returns the time series observations.
169 
170  \return A reference to the time series observations.
171  */
172  const TimeSeriesObservationSet& getObservations() const;
173 
174  /*!
175  \brief It returns the interpolator associated to the time series.
176 
177  \return A pointer the interpolator associated to the time series.
178 
179  \note The caller will NOT take the ownership of the returned pointer.
180  \note The AbstractTimeSeriesInterp points to a singleton.
181  */
182  AbstractTimeSeriesInterp* getInterpolator() const;
183 
184  /*!
185  \brief It sets the interpolator associated to the time series.
186 
187  \param interp A interpolator which is able to estimate values at non-observed times.
188 
189  \note It will NOT take the ownership of the input pointer.
190  \note The AbstractTimeSeriesInterp points to a singleton.
191  */
192  void setInterpolator(AbstractTimeSeriesInterp* interp);
193 
194  /*!
195  \brief It returns the time series identifier.
196 
197  \return The time series identifier.
198  */
199  std::string getId() const;
200 
201  /*!
202  \brief It sets the time series identifier.
203 
204  \param id The time series identifier.
205  */
206  void setId(const std::string& id);
207 
208  /*!
209  \brief It returns the time series location.
210 
211  \return A pointer to the time series location.
212 
213  \note The caller will NOT take the ownership of the returned pointer.
214  */
215  te::gm::Geometry* getLocation() const;
216 
217  /*!
218  \brief It sets the time series location.
219 
220  \param geom The time series location.
221 
222  \note It will take the ownership of the given pointer.
223  */
224  void setLocation(te::gm::Geometry* geom);
225 
226  /*!
227  \brief It adds an observation (time and attribute value) into the time series.
228 
229  \param time A pointer to the time.
230  \param data A pointer to the attribute value.
231 
232  \note The caller will take the ownership of the returned pointer.
233  */
234  void add(te::dt::DateTime* time, te::dt::AbstractData* value);
235 
236  /*!
237  \brief It adds an observation (time and attribute value as double) into the time series.
238 
239  \param time A pointer to the time.
240  \param data A pointer to the attribute value as a double.
241 
242  \note The caller will take the ownership of the given pointer.
243  */
244  void add(te::dt::DateTime* time, double value);
245 
246  /*!
247  \brief It adds an observation (time and attribute value as integer) into the time series.
248 
249  \param time A pointer to the time.
250  \param data A pointer to the attribute value as a integer.
251 
252  \note The caller will take the ownership of the given pointer.
253  */
254  void add(te::dt::DateTime* time, int value);
255 
256  /*!
257  \brief It adds an observation (time and attribute value as string) into the time series.
258 
259  \param time A pointer to the time.
260  \param data A pointer to the attribute value as a string.
261 
262  \note The caller will take the ownership of the given pointer.
263  */
264  void add(te::dt::DateTime* time, const std::string& value);
265 
266  /*!
267  \brief It adds an observation (time and attribute value) into the time series.
268 
269  \param item A time series item.
270  */
271  void add(const TimeSeriesObservation& item);
272 
273  /*!
274  \brief It returns the size of the time series observation set.
275 
276  \return The observation set size of the time series.
277  */
278  std::size_t size() const;
279 
280  /*! \name TimeSeries Iterator
281 
282  An example of use:
283 
284  TimeSeriesIterator it = tj.begin();
285  while(it!=tj.end())
286  {
287  DateTime* t = it.getTime();
288  double v = it.getDouble(); //or getValue() or getInt()...
289  ++it;
290  }
291  */
292  //@{
293  /*!
294  \brief It returns an iterator that points to the first observation of the time series.
295 
296  \return The time series iterator.
297  */
298  TimeSeriesIterator begin() const;
299 
300  /*!
301  \brief It returns an iterator that points to the end of the time series.
302 
303  \return The time series iterator.
304  */
305  TimeSeriesIterator end() const;
306 
307  /*!
308  \brief It returns an iterator that points to an observation at a given time.
309 
310  If there is no observation at this given time, the returned iterator
311  points to the end of the trajectory.
312 
313  \return The time series iterator.
314  \note This does not take the ownership of the given pointer.
315  */
317  //@}
318 
319  /*!
320  \brief It returns the value associated to a given date and time.
321 
322  If there is no value associated to the given date and time, it will
323  use internally its interpolation function.
324 
325  \param t A date and time.
326 
327  \return A pointer to the value associated to the given date and time.
328 
329  \note The caller will take the ownership of the returned pointer.
330  */
331  std::auto_ptr<te::dt::AbstractData> getValue(te::dt::DateTime* t) const;
332 
333  /*!
334  \brief It returns the value as a double associated to a given date and time.
335 
336  If there is no value associated to the given date and time, it will
337  use internally its interpolation function.
338 
339  \param t A date and time.
340 
341  \return The value associated to the given date and time.
342  */
343  double getDouble(te::dt::DateTime* t) const;
344 
345  /*!
346  \brief It returns the value as an integer associated to a given date and time.
347 
348  If there is no value associated to the given date and time, it will
349  use internally its interpolation function.
350 
351  \param t A date and time.
352 
353  \return The value associated to the given date and time.
354  */
355  int getInt(te::dt::DateTime* t) const;
356 
357  /*!
358  \brief It returns the value as a string associated to a given date and time.
359 
360  If there is no value associated to the given date and time, it will
361  use internally its interpolation function.
362 
363  \param t A date and time.
364 
365  \return The value associated to the given date and time.
366  */
367  std::string getString(te::dt::DateTime* t) const;
368 
369  /*!
370  \brief It returns the temporal extent or range of the time series.
371 
372  \return The temporal extent or range of the time series.
373 
374  \note The caller will take the ownership of the output pointer.
375  */
376  std::auto_ptr<te::dt::DateTimePeriod> getTemporalExtent() const;
377 
378  /*!
379  \brief It returns the minimal and maximun values of the time series.
380 
381  \param minValue The minumun value of the time series.
382  \param maxValue The maximun value of the time series.
383  */
384  void getValueExtent(double& minValue, double& maxValue);
385 
386  /*!
387  \brief It returns the minimal and maximun values of the time series.
388 
389  \param minValue The minumun value of the time series.
390  \param maxValue The maximun value of the time series.
391  */
392  void getValueExtent(int& minValue, int& maxValue);
393 
394  /*!
395  \brief It returns the minimal and maximun values of the time series.
396 
397  \param minValue The minumun value of the time series.
398  \param maxValue The maximun value of the time series.
399  */
400  void getValueExtent(std::string& minValue, std::string& maxValue);
401 
402  /*! \name Time Series Patch
403 
404  These methods return patches of a time series, as TimeSeriesPatch objects,
405  that satisfy given restrictions.
406  A TimeSeriesPatch object contains only pointers to the initial and
407  final observations that delimit a patch of a TimeSeries. The
408  end() method of a TimeSeriesPatch object returns an iterator
409  that points to the position AFTER the last required observation.
410 
411  Example of use:
412 
413  TimeSeriesPatch patch = tj->getTimeSeries(period, "DURING");
414  TimeSeriesIterator it = patch.begin();
415  while(it!=patch.end())
416  {
417  DateTime* t = it.getTime();
418  double v = it.getDouble(); //or getInt() or get Value()
419  ++it;
420  }
421 
422  Other option is to create a new TimeSeries from the returned patch:
423 
424  TimeSeriesPatch patch = tj->getTimeSeries(period, "DURING");
425  TimeSeries tsnew(patch);
426  */
427  //@{
428  /*!
429  \brief It returns a time series subset that satisfies a given temporal relation.
430 
431  The possible temporal relations are: AFTER (2);
432  AFTER | EQUALS (10); 3. BEFORE (1); 4. BEFORE | EQUALS (9);
433  DURING (4); EQUALS (8)
434 
435  \param dt A given date and time.
436  \param r A given temporal relation.
437 
438  \return A patch of the time series.
439 
440  \note When the temporal relation is DURING, dt must be a time period.
441  */
443 
444  /*!
445  \brief It returns time series subsets that satisfy a given relation.
446 
447  The possible basic relation is: LESS (1); MORE (2); EQUAL (4);
448  LESS | EQUAL (5); MORE | EQUAL (6).
449 
450  \param v A given value.
451  \param r A given basic relation.
452  \param result The returned patches.
453  */
454  void getPatches( const double& v, te::dt::BasicRelation r,
455  std::vector<TimeSeriesPatch>& result) const;
456 
457  /*!
458  \brief It returns time series subsets that satisfy a given relation.
459 
460  The possible basic relation is: LESS (1); MORE (2); EQUAL (4);
461  LESS | EQUAL (5); MORE | EQUAL (6).
462 
463  \param v1 A given first value.
464  \param r1 A given relation associated to the first value.
465  \param v2 A given second value.
466  \param r2 A given relation associated to the second value.
467  \param result The returned patches.
468  */
469  //void getTimeSeries( const double& v1, te::dt::BasicRelation r1,
470  // const double& v2, te::dt::BasicRelation r2,
471  // std::vector<TimeSeriesPatch>& result) const;
472 
473  /*!
474  \brief It returns time series subsets that satisfy a the given relations.
475 
476  The possible basic relations are: LESS (1); MORE (2); EQUAL (4);
477  LESS | EQUAL (5); MORE | EQUAL (6).
478 
479  The possible temporal relations are: AFTER (2);
480  AFTER | EQUALS (10); 3. BEFORE (1); 4. BEFORE | EQUALS (9);
481  DURING (4); EQUALS (8) .
482 
483  \param v A given value.
484  \param r A basic relation.
485  \param dt A given date and time.
486  \param tr A given temporal relation.
487  \param result The returned patches.
488 
489  \note When the temporal relation is DURING, dt must be a time period.
490  */
491  void getPatches( const double& v, te::dt::BasicRelation r,
493  std::vector<TimeSeriesPatch>& result) const;
494 
495  /*!
496  \brief It returns time series subsets that satisfy the given relations.
497 
498  The possible basic relations are: LESS (1); MORE (2); EQUAL (4);
499  LESS | EQUAL (5); MORE | EQUAL (6).
500 
501  The possible temporal relations are: AFTER (2);
502  AFTER | EQUALS (10); 3. BEFORE (1); 4. BEFORE | EQUALS (9);
503  DURING (4); EQUALS (8) .
504 
505  \param v1 A given first value.
506  \param r1 A given relation associated to the first value.
507  \param v2 A given second value.
508  \param r2 A given relation associated to the second value.
509  \param dt A given date and time.
510  \param tr A given temporal relation.
511  \param result The returned patches.
512 
513  \note When the temporal relation is DURING, dt must be a time period.
514  */
515  //void getTimeSeries( const double& v1, te::dt::BasicRelation r1,
516  // const double& v2, te::dt::BasicRelation r2,
517  // const te::dt::DateTime& dt, te::dt::TemporalRelation tr,
518  // std::vector<TimeSeriesPatch>& result) const;
519  //@}
520 
521  /*! \brief Virtual destructor. */
522  virtual ~TimeSeries();
523 
524  private:
525 
526  /*! \brief It returns the result of a basic relation ordered by time */
527  void getResultOrderedByTime( const double& v, te::dt::BasicRelation r, std::map<te::dt::DateTime*,te::dt::AbstractData*, te::dt::CompareDateTime>& result) const;
528 
529  private:
530 
531  TimeSeriesObservationSet m_observations; //!< The time series observations
532  AbstractTimeSeriesInterp* m_interpolator; //!< The interpolator used to estimate values at non-observed times.
533  std::auto_ptr<te::gm::Geometry> m_location; //!< The time series location.
534  std::string m_id; //!< The time series identification.
535  };
536 
537  } // end namespace st
538 } // end namespace te
539 
540 #endif // __TERRALIB_ST_INTERNAL_TIMESERIES_H
541 
#define TESTEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:88
BasicRelation
Relations between simple attribute values.
Definition: Enums.h:158
A class to traverse the observations of a TimeSeries.
TemporalRelation
Temporal relations between date and time (Source: Allen, 1991).
Definition: Enums.h:140
A class to represent an observation (time and value) of a time series.
URI C++ Library.
AbstractTimeSeriesInterp * m_interpolator
The interpolator used to estimate values at non-observed times.
Definition: TimeSeries.h:532
A base class for values that can be retrieved from the data access module.
Definition: AbstractData.h:57
A struct to represent a patch or a continuous piece of a time series.
Geometry is the root class of the geometries hierarchy, it follows OGC and ISO standards.
Definition: Geometry.h:73
TimeSeriesObservationSet m_observations
The time series observations.
Definition: TimeSeries.h:531
An abstract class for an interpolation function or interpolator that estimate a value at non-observav...
A class to represent time series.
Definition: TimeSeries.h:66
std::string m_id
The time series identification.
Definition: TimeSeries.h:534
std::auto_ptr< te::gm::Geometry > m_location
The time series location.
Definition: TimeSeries.h:533
boost::multi_index_container< TimeSeriesObservation, boost::multi_index::indexed_by< boost::multi_index::ordered_unique< boost::multi_index::identity< TimeSeriesObservation > >, boost::multi_index::ordered_non_unique< boost::multi_index::const_mem_fun< TimeSeriesObservation, double,&TimeSeriesObservation::getDouble > >, boost::multi_index::ordered_non_unique< boost::multi_index::const_mem_fun< TimeSeriesObservation, std::string,&TimeSeriesObservation::getString > > > > TimeSeriesObservationSet
This file contains a time series iterator.