Scripting > Math Functions


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.