Scripting > DataContainer Class


TimeSeriesContainer Class

TimeSeriesContainer is a type of DataContainer that contains information about time series data.  TimeSeriesContainer objects are returned by the get () method and are required in the put() method of HecDss objects.

 

TimeSeriesContainer objects have all the data fields described under the DataContainerClass section in addition to those described in the table below .  New TimeSeriesContainer objects can be created by a script if the TimeSeriesContainer class has been imported from the hec.io module (e.g. “from hec.io import *” or “from hec.io import TimeSeriesContainer”) The new object can be created by calling TimeSeriesContainer () (e.g. “myTSC = TimeSeriesContainer ()”).

 

TimeSeriesContainer Data Fields

Field

Type

Description

endTime

Integer1

 

The end time of the time window.  If the data were retrieved, the end time may be later than the last time in the times list.

interval

Integer

The interval, in minutes, between each set of consecutive times in the times list.  For irregular-interval times, the interval field is set to –1.

numberValues

Integer

The length of values and times lists.

parameter

string

The parameter associated with the data.

quality

list of integers2

The optional list of quality flags.  If this list is present, there must be a quality for each value in the values array.  If this list is not present, the quality field is set to None.

startTime

integer2

The start time of the time window.  If the data were retrieved, the start time may be earlier than the first time in the times list.

subLocation

string

The sub-location associated with the data.

subParameter

string

The sub-parameter associated with the data.

times

list of integers1

The list of times.  There must be a time for each value in the values list, and times must increase from one index to the next.

timeZoneID

string

The time-zone for times in the times list.  If unknown, the timeZoneID field is set to None

timeZoneRawOffset

integer

The offset, in milliseconds, from UTC to the time zone for the times in the times list.

type

string

The type of the data (e.g. “INST-VAL”, “INST-CUM”, “PER-AVER”, “PER-CUM”).

units

String

The units of the data.

values

list of floating-point

The data values, each of which has a corresponding time in the times list and optionally a corresponding quality in the quality list.  All lists must be the same length.

 

1 Integer times from this field can be converted to string representations by using the set() and dateAndTime() methods of HecTime objects discussed under the HecTime class section.  Additionally, integer times suitable for this field can be generated by the HecTime value() method.

2 Quality values are interpreted according to the table below.

 

Data Quality Bits

Bit(s)

Description

1

Set when the datum has been tested (screened).

2

Set when the datum passed all tests.

3

Set when the datum is missing (either originally missing or set to missing by a test).

4

Set when at least one test classified the datum as questionable.

5

Set when at least one test classified the datum as rejected.

6-7

Set by the RANGE test.  Interpreted as a 2-bit unsigned integer  with values having the following meanings:

0

value of datum < than 1st limit

1

1st limit <= value of datum < 2nd limit

2

2nd limit <= value of datum < 3rd limit

3

3rd limit <= value of datum

 

8

Set when the datum has been changed from the original value.

9-11

Datum replacement indicator.  Interpreted as a 3-bit unsigned integer with values having the following meanings:

0

datum was not replaced (original value)

1

datum was replaced by DATCHK

2

datum was replaced by DATVUE

3

datum was replaced by manual edit in DATVUE

4

original value was accepted in DATVUE

5-7

reserved for future use

 

12-15

Datum replacement value computation method.  Interpreted as a 4-bit unsigned integer with values having the following meanings:

0

datum was not replaced (original value)

1

datum value computed by linear interpolation

2

datum value was entered manually

3

datum value was replaced with a missing value

4-15

reserved for future use

 

16

set when datum failed an absolute magnitude test

17

set when datum failed a constant value test

18

set when datum failed a rate of change test

19

set when datum failed a relative magnitude test

20

set when datum failed a duration magnitude test

21

set when datum failed a negative incremental value test

22

reserved for future use

23

set when datum is excluded from testing (e.g. DATCHK GAGEFILE entry)

24

reserved for future use

25

set when datum failed a user-defined test

26

set when datum failed a distribution test

27-31

reserved for future use

32

set when datum is protected from being replaced

 

Example: Using a TimeSeriesContainer Object

 

from hec.script import *

from hec.heclib.dss import *

from hec.io import TimeSeriesContainer

from hec.heclib.util import HecTime

 

watershed = “GREEN RIVER”

loc = “OAKVILLE”

param = “STAGE”

ver = “OBS”

startTime = “12Oct2003 0100”

values = [12.36, 12.37, 12.42, 12.55, 12.51, 12.47, 12.43, 12.39]

hecTime = HecTime()

tsc = TimeSeriesContainer()

tsc.watershed = watershed

tsc.location = loc

tsc.parameter = param

tsc.version = ver

tsc.fullName = “/%s/%s/%s//1HOUR/%s/” % \

     (watershed, loc, param, ver)

tsc.interval = 60

hecTime.set(startTime)

times = []

for value in values :

     times.append(hecTime.value())

     hecTime.add(tsc.interval)

tsc.values = values

tsc.times = times

tsc.startTime = times[0]

tsc.endTime = times[-1]

tsc.numberValues = len(values)

tsc.units = “FEET”

tsc.type = “INST-VAL”

dssFile = HecDss.open(“myFile.dss”)

dssFile.put(tsc)

dssFile.done()