User's Guide

Up: Time Series Analysis Next: Transforming the Frequency Previous: Time Series Analysis Contents

Time Series Collections

The TimeSeriesCollection class represents a data set that consists of one or more variables that represent time series data. This class inherits from VariableCollection, and adds several methods and properties that make it easier to handle the time aspect.

Constructing time series collections

The TimeSeriesCollection class has a total of seven constructors. The first constructor takes no arguments. It creates an empty collection. You can add and remove variables using the methods listed in the next section.

Four constructors use a data source to populate the collection. The first of these takes a DataTable as its only argument. The columns of the table are converted into variables according to the following rules:

If the column contains unique values (the DataColumn 's Unique property is True), then the column is interpreted as a KeyVariable.
If the column's data type is numerical, the column is interpreted as a NumericalVariable.
If the column's data type is a date or time value, the column is interpreted as a DateTimeVariable.
Otherwise, the column is interpreted as a CategoricalVariable.

C#	Copy Code
DataTable table; // Connect to a data source and load the data into the DataTable TimeSeriesCollection timeSeries = new TimeSeriesCollection(table);

Visual Basic	Copy Code
Dim table As DataTable ' Connect to a data source and retrieve the column from a DataTable Dim timeSeries As TimeSeriesCollection = New TimeSeriesCollection(table)

You can optionally add a second parameter: an IFormatProvider that is used to convert the data values. If you need more control about how the column conversions are handled, you can create an empty collection and convert the variables individually. For example, if you have dates stored in a specific format,. you can convert the column to a DateTimeVariable, and pass a CultureInfo object that specifies the date format.

Two more constructors are similar, but take an IDataReader as their first parameter. The columns are converted into variables according to the same rules as for data tables.

The first DateTimeVariable is taken as the StartOfPeriodVariable variable. If there is a second DateTimeVariable, it is taken as the EndOfPeriodVariable. You can change this later on by setting these properties to the appropriate variables.

The last group of two constructors lets you create a TimeSeriesCollection based on time values but no actual data. You can add variables later on using the methods described in the next section.

The first constructor in the group takes two parameters. Both are DateTimeVariable objects that specifiy the start and end of period values, respectively. The second takes one DateTimeVariable that specifies the start of period values, and a DateTimeUnit value that specifies the length of each time period. The EndOfPeriodVariable is constructed by adding an interval of this length to the start time.

Adding and Removing Variables

The TimeSeriesCollection class implements the IList interface, and has type safe versions of standard its methods. The Add method adds an individual variable to the collection. A variable can only be added once. The Insert does the same, but lets you specify the position.

The following example illustrates how to create a TimeSeriesCollection from scratch using these methods:

C#	Copy Code
DataColumn column; TimeSeriesCollection timeSeries = new TimeSeriesCollection(); double[] salesArray = new double[] {62, 77, 61, 94, 75, 82}; timeSeries.Add(new NumericalVariable("Sales", salesData)); DateTime fromDate = new DateTime(2006, 1, 1); DateTime toDate = new DateTime(2006, 6, 30); DateTimeVariable period = DateTimeVariable.CreateRange(fromDate, toDate, DateTimeUnit.Month); timeSeries.StartOfPeriodVariable = period;

Copy Code

DataColumn column;
TimeSeriesCollection timeSeries = new TimeSeriesCollection();
double[] salesArray = new double[] {62, 77, 61, 94, 75, 82};
timeSeries.Add(new NumericalVariable("Sales", salesData));
DateTime fromDate = new DateTime(2006, 1, 1);
DateTime toDate = new DateTime(2006, 6, 30);
DateTimeVariable period = 
    DateTimeVariable.CreateRange(fromDate, toDate, DateTimeUnit.Month);
timeSeries.StartOfPeriodVariable = period;

Visual Basic	Copy Code
Dim column As DataColumn Dim timeSeries As TimeSeriesCollection = New TimeSeriesCollection() Dim salesData As Double() = New Double() {62, 77, 61, 94, 75, 82} timeSeries.Add(New NumericalVariable("Sales", salesData)) Dim fromDate As DateTime() = New DateTime(2006, 1, 1) Dim toDate As DateTime() = New DateTime(2006, 6, 30) Dim period As DateTimeVariable() = _ New DateTimeVariable(fromDate, toDate, DateTimeUnit.Month) timeSeries.StartOfPeriodVariable = period

Visual Basic

Copy Code

Dim column As DataColumn
Dim timeSeries As TimeSeriesCollection = New TimeSeriesCollection()
Dim salesData As Double() = New Double() {62, 77, 61, 94, 75, 82}
timeSeries.Add(New NumericalVariable("Sales", salesData))
Dim fromDate As DateTime() = New DateTime(2006, 1, 1)
Dim toDate As DateTime() = New DateTime(2006, 6, 30)
Dim period As DateTimeVariable() = _
    New DateTimeVariable(fromDate, toDate, DateTimeUnit.Month)
timeSeries.StartOfPeriodVariable = period

The AddRange method adds a group of variables to the collection. This method is overloaded. Each overload takes one argument. The options are:

An array of Variable objects.
Another TimeSeriesCollection: All variables in the collection are added to the current instance.
A DataTable: The columns are interpreted as described in the discussion of TimeSeriesCollection constructors.
An IDataReader: The columns are interpreted as described in the discussion of TimeSeriesCollection constructors.

The Remove method removes a variable from the collection. The RemoveAt method removes the variable with the specified index from the collection.

Time series properties and methods.

The StartOfPeriodVariable property is a DateTimeVariable that specifies the beginning of the time period of each observation. When you create a TimeSeriesCollection from a data source, the first column that contains date/time data is assumed to represent the start-of-period variable.

The EndOfPeriodVariable property is similar but specifies the end of each time period. If it is null (Nothing in Visual Basic), it is assumed to be the same as the start of period.

The GetRowIndex method allows you to retrieve the index of the row corresponding to a DateTime value. This method has two overloads and takes one or two parameters. The first is a DateTime value that specifies the value to locate. The second, optional parameter is an integer that specifies a start index. This method is faster when moving through the series in ascending order.

Other Properties and Methods

The Count property returns the number of variables in the collection. The Contains method returns a boolean that indicates whether a variable is a member of the collection. Similarly, the The ContainsName method returns a boolean that indicates whether the collection contains a variable with the specified name. The IndexOf method returns the zero-based index of a variable in the collection. If the variable is not a member of the collection, the value -1 is returned.

The ToArray method returns the variables in the collection in an array. The GetNames method returns a string array containing the names of the variables in the collection.

The GetEnumerator method returns an IEnumerator object that can be used to iterate through the variables in the collection. This includes the start of period and end of period variables.