Calendar data type

The Calendar data type controls the times at which time series data can be stored.

The Calendar data type is an opaque data type that is composed of:

A calendar starting time stamp
A calendar pattern
A calendar pattern starting time stamp

For regular time series, calendars are also used to convert the time periods of interest to offsets of values in the vector, and vice versa.

The input format for the Calendar data type is a quoted text string.

Notes:

¹ See CalendarPattern data type.

Table 1. Calendar data type parameter values
Value	Data type	Description
`start_date`	DATETIME YEAR TO FRACTION(5)	Defines when the calendar starts. If you do not specify a start date, the calendar pattern start date is used. The calendar start date does not affect the origin of the time series. The origin of the time series specifies the earliest date for elements in the time series. The origin can be before the calendar start date.
`pattern_date`	DATETIME YEAR TO FRACTION(5)	Defines when the calendar pattern starts. If both the calendar start date and the pattern start date are included, the pattern start date must be the same as or later than the calendar start data by a number of intervals that is less than or equal to the number of interval lengths in the pattern length. If you do not specify a calendar pattern start date, the calendar start date is used.
`pattern_name`	VARCHAR	Name of calendar pattern to use from CalendarPatterns table.

Usage

To create a calendar, insert the keywords and their values into the CalendarTable table.

Set the calendar start date and calendar pattern start dates at the logical beginning of an interval. For example, if the interval size is a day, specify a start date time of midnight.

Calendars can be combined with functions that form the Boolean AND, OR, and NOT of the calendars. The resulting calendars can be stored in the CalendarTable table or used as arguments to other functions.

You can define both a calendar pattern starting time and a calendar starting time if the calendar and calendar pattern starting times do not coincide. The calendar start date and the pattern start date can be one or more intervals apart, depending on the calendar pattern length. For example, if the calendar pattern is {1 on, 14 off}, the pattern length is 15. The calendar start date and the pattern start date can be from 0 to 15 intervals apart.

Occasionally, if you have a regular time series, you have elements for which there is no data. For example, if you have a daily calendar you might not obtain data on holidays. These exceptions to your calendar are marked as null elements. However, you can hide exceptions so that they are not included in calculations or analysis by using the HideElem function.

Examples

The following example inserts a calendar called weekcal into the CalendarTable table:

INSERT INTO CalendarTable(c_name, c_calendar)
  VALUES ('weekcal',
          'startdate(2011-01-02 00:00:00.00000), 
           pattstart(2011-01-02 00:00:00.00000), 
           pattname(workweek_day)');

This calendar starts on 2011-01-02 and uses a pattern named workweek_day.

The following example creates an hourly calendar with the specified pattern:

INSERT INTO CalendarTable(c_name, c_calendar)
   VALUES('my_cal',
      'startdate(2011-01-01 00:00:00.00000),
       pattstart(2011-01-02 00:00:00.00000), 
       pattern({24 off, 120 on, 24 off}, hour)');

The calendar start date is 24 hours before the pattern start date. The pattern length is 168 hours, or one week.