Extract Time Series
Data at Unique Time Specification
extractTimeSeriesDataForTimeSpecification(
string timeLevelString,
string rangeString,
boolean isInclusive,
integer intervalWindow,
boolean setAsIrregular )
Select/extract data points from the current regular or irregular interval time series data set based upon user defined time specifications. For example, the function may be used to extract from hourly interval data, the values observed every day at noon.
timeLevelString defines the time
level/interval for extraction (year, month, day of the month, day of the week, or 24-hour
time). rangeString defines
the interval range for data extraction applicable to the time level. For example,
if timeLevelString is "MONTH”, a
valid range would be "JAN-MAR". The rangeString variable can define a single interval
value (e.g. "JAN" - select data from January only) or a beginning and ending range (e.g.
"JAN-MAR" - select data for January through March). The valid timeLevelString and rangeString values are shown below.
Valid timeLevelString and rangeString Values
|
timeLevelString |
rangeString |
Example rangeString |
|
"YEAR” |
Four-digit year value |
"1938" or "1938-1945" |
|
"MONTH” |
Standard three-character abbreviation for month |
"JAN" or "JAN-MAR" or “OCT-FEB” |
|
"DAYMON(TH)" |
Day of the month or "LASTDAY" string |
"15" or "1-15 or “27-5” or “16-LASTDAY" |
|
"DAYWEE(K)" |
Standard three-character abbreviation for day of the week |
"MON" or "SUN-TUE" or “FRI-WED” |
|
"TIME" |
Four digit 24-hour military-style clock time |
"2400" or "0300-0600" or “2200-0130” |
If desired, you may use one of the enumerated string constants to specify timeLevelString:
| Year | TimeSeriesMath.LEVEL_YEAR_STRING | |
| Month |
TimeSeriesMath. LEVEL_MONTH_STRING |
|
| Day of Month | TimeSeriesMath. LEVEL_DAYMONTH_STRING | |
| Day of Week | TimeSeriesMath.LEVEL_DAYWEEK_STRING | |
| 24-hour time | TimeSeriesMath.LEVEL_TIME_STRING |
The parameter isInclusive
determines whether the data extraction operation is either inclusive or exclusive of the
specified range. For example, if isInclusive is “true” and the range is set to
"JAN-MAR" for the "MONTH" time level, the extracted data will include all data in the
months January through March for all the years of time series data. If isInclusive is “false” for this example, the
extracted data covers the time April through December (is exclusive of the period January
through March).
intervalWindow is only used when
the timeLevelString is
"TIME.” intervalWindow is
the minutes before and after the time of day within which the data will be extracted.
intervalWindow effectively
increases the time range at the beginning and end intervalWindow minutes. For example, with a
rangeString of “0300” and an intervalWindow of 10, data will be extracted
from the selected time series if times falls within in the period 0250 to 0310.
setAsIrregular defines whether
the extracted data is saved as regular interval or irregular interval data. Most
often the time series data formed by the extraction process will no longer be regular
interval, and setAsIrregular
should be set to “true.” Setting setAsIrregular to “false” will force an attempt to
save the data as regular interval time data.
Parameters:
timeLevelString – A string specifying the time level selection.
rangeString – A string specifying time or time range for selection.
Must be consistent with timeLevelString.
isInclusive – Either Constants.TRUE, or Constants.FALSE, value.
If true, data is extracted inclusive of the range specified by rangeString.
If false, data is extracted exclusive of the range specified by rangeString.
intervalWindow – An integer value representing the minutes before and after
the time of day within which the data will be extracted. Only applied when the
timeLevelString is “TIME.”
setAsIrregular – Either Constants.TRUE, or Constants.FALSE, value. If
true, data is automatically set as irregular time interval data. If false, the
function will attempt to classify the data as regular time interval data.
Example:
SelectedData =
tsData.extractTimeSeriesDataForTimeSpecification(
“DAYMONTH”,
“16-LASTDAY”,
Constants.TRUE,
0,
Constants.TRUE)
Returns: A new TimeSeriesMath object
Generated Exceptions: Throws
a hec.hecmath.HecMathException if the
function could not successfully interpret timeLevelString or rangeString.