Time Series Variables

Last updated on 26th March 2024

Basic Concepts

Time series variables are data pieces inside an agent that keep track of that agent's previous values. Since they must hold multiple values in a series, these variables are windowed values, storing data for a specific number of time steps. Modellers can specify how many time steps a time series variable should hold.

Once created, a time series variable will hold values of one specific agent attribute for a specific number of time steps. The default value of each tick in the time series variable is 0. Modellers can use the offset parameter of the time series variable creation methods to determine how many historical values should be kept at the same time. The variable will only store the latest offset ticks.

For example, suppose a model saves historical values corresponding to the number of ticks that have been run so far. Assume further that this model contains a time series variable with an offset of 3, and the model has run for 2 ticks. At this point, since the model has run for 2 ticks, the values in the time series variable will be 0,1,2. The 0 represents an uninitialized variable, while the 2 represents the most recent tick. If the model runs for another tick, the time series variable will now contain the values 1,2,3. The uninitialized value has been replaced with the next most recent value of 1, while the new value of 3 has been added into the variable.

Examples

The Simudyne SDK allows modellers to create time series variables with the WindowedDouble and WindowedLong classes.

// Create new windowed value, storing 10 ticks of data.
WindowedDouble mortgages = createWindowedDouble(10);
WindowedLong balances = createWindowedLong(10);

The time series variable objects allow modellers to access specific ticks.

WindowedLong balance = createWindowedLong(10);

// Retrieves the value of balance from 2 ticks ago.
balance.offset(2);

// Both of these calls retrieve the current value of the balance.
balance.offset(0);
balance.get();

// Throws an exception because it is larger than the number of held values.
balance.offset(11);