time-series.rst

Time Series

Dynare provides a MATLAB/Octave class for handling time series data, which is based on a class for handling dates. Dynare also provides a new type for dates, so that the user does not have to worry about class and methods for dates. Below, you will first find the class and methods used for creating and dealing with dates and then the class used for using time series. Dynare also provides an interface to the X-13 ARIMA-SEATS seasonal adjustment program produced, distributed, and maintained by the U.S. Census Bureau (2020).

Dates

Dates in a mod file

Dynare understands dates in a mod file. Users can declare annual, bi-annual, quarterly, or monthly dates using the following syntax:

1990Y
1990S2
1990Q4
1990M11

Behind the scene, Dynare’s preprocessor translates these expressions into instantiations of the MATLAB/Octave’s class dates described below. Basic operations can be performed on dates:

plus binary operator (+)

An integer scalar, interpreted as a number of periods, can be added to a date. For instance, if a = 1950Q1 then b = 1951Q2 and b = a + 5 are identical.

plus unary operator (+)

Increments a date by one period. +1950Q1 is identical to 1950Q2, ++++1950Q1 is identical to 1951Q1.

minus binary operator (-)

Has two functions: difference and subtraction. If the second argument is a date, calculates the difference between the first date and the secmond date (e.g. 1951Q2-1950Q1 is equal to 5). If the second argument is an integer X, subtracts X periods from the date (e.g. 1951Q2-2 is equal to 1950Q4).

minus unary operator (-)

Subtracts one period to a date. -1950Q1 is identical to 1949Q4. The unary minus operator is the reciprocal of the unary plus operator, +-1950Q1 is identical to 1950Q1.

colon operator (:)

Can be used to create a range of dates. For instance, r = 1950Q1:1951Q1 creates a dates object with five elements: 1950Q1, 1950Q2, 1950Q3, 1950Q4 and 1951Q1. By default the increment between each element is one period. This default can be changed using, for instance, the following instruction: 1950Q1:2:1951Q1 which will instantiate a dates object with three elements: 1950Q1, 1950Q3 and 1951Q1.

horzcat operator ([,])

Concatenates dates objects without removing repetitions. For instance [1950Q1, 1950Q2] is a dates object with two elements (1950Q1 and 1950Q2).

vertcat operator ([;])

Same as horzcat operator.

eq operator (equal, ==)

Tests if two dates objects are equal. +1950Q1==1950Q2 returns true, 1950Q1==1950Q2 returns false. If the compared objects have both n>1 elements, the eq operator returns a column vector, n by 1, of logicals.

ne operator (not equal, ~=)

Tests if two dates objects are not equal. +1950Q1~= returns false while 1950Q1~=1950Q2 returns true. If the compared objects both have n>1 elements, the ne operator returns an n by 1 column vector of logicals.

lt operator (less than, <)

Tests if a dates object preceeds another dates object. For instance, 1950Q1<1950Q3 returns true. If the compared objects have both n>1 elements, the lt operator returns a column vector, n by 1, of logicals.

gt operator (greater than, >)

Tests if a dates object follows another dates object. For instance, 1950Q1>1950Q3 returns false. If the compared objects have both n>1 elements, the gt operator returns a column vector, n by 1, of logicals.

le operator (less or equal, <=)

Tests if a dates object preceeds another dates object or is equal to this object. For instance, 1950Q1<=1950Q3 returns true. If the compared objects have both n>1 elements, the le operator returns a column vector, n by 1, of logicals.

ge operator (greater or equal, >=)

Tests if a dates object follows another dates object or is equal to this object. For instance, 1950Q1>=1950Q3 returns false. If the compared objects have both n>1 elements, the ge operator returns a column vector, n by 1, of logicals.

One can select an element, or some elements, in a dates object as he would extract some elements from a vector in MATLAB/Octave. Let a = 1950Q1:1951Q1 be a dates object, then a(1)==1950Q1 returns true, a(end)==1951Q1 returns true and a(end-1:end) selects the two last elements of a (by instantiating the dates object [1950Q4, 1951Q1]).

Remark: Dynare substitutes any occurrence of dates in the .mod file into an instantiation of the dates class regardless of the context. For instance, d = 1950Q1 will be translated as d = dates('1950Q1');. This automatic substitution can lead to a crash if a date is defined in a string. Typically, if the user wants to display a date:

disp('Initial period is 1950Q1');

Dynare will translate this as:

disp('Initial period is dates('1950Q1')');

which will lead to a crash because this expression is illegal in MATLAB. For this situation, Dynare provides the $ escape parameter. The following expression:

disp('Initial period is $1950Q1');

will be translated as:

disp('Initial period is 1950Q1');

in the generated MATLAB script.

The dates class

arg freq:	equal to 1, 2, 4, 12 or 365 (resp. for annual, bi-annual, quarterly, monthly, or daily dates).
arg time:	a n*1 array of integers, the number of periods since year 0 ().

Each member is private, one can display the content of a member but cannot change its value directly. Note also that it is not possible to mix frequencies in a dates object: all the elements must have common frequency.

The dates class has the following constructors:

Example

do1 = dates('1950Q1');
do2 = dates('1950Q2','1950Q3');
do3 = dates(do1,do2);
do4 = dates('Q',1950, 1);
do5 = dates('D',1973, 1, 25);

A list of the available methods, by alphabetical order, is given below. Note that by default the methods do not allow in place modifications: when a method is applied to an object a new object is instantiated. For instance, to apply the method multiplybytwo to an object X we write:

>> X = 2;
>> Y = X.multiplybytwo();
>> X

2

>> Y

4

or equivalently:

>> Y = multiplybytwo(X);

the object X is left unchanged, and the object Y is a modified copy of X (multiplied by two). This behaviour is altered if the name of the method is postfixed with an underscore. In this case the creation of a copy is avoided. For instance, following the previous example, we would have:

>> X = 2;
>> X.multiplybytwo_();
>> X

4

Modifying the objects in place, with underscore methods, is particularly useful if the methods are called in loops, since this saves the object instantiation overhead.

The dseries class

|br| The MATLAB/Octave dseries class handles time series data. As any MATLAB/Octave statements, this class can be used in a Dynare’s mod file. A dseries object has six members:

arg name:	A vobs*1 cell of strings or a vobs*p character array, the names of the variables.
arg tex:	A vobs*1 cell of strings or a vobs*p character array, the tex names of the variables.
arg dates dates:	An object with nobs elements, the dates of the sample.
arg double data:	A nobs by vobs array, the data.
arg ops:	The history of operations on the variables.
arg tags:	The user-defined tags on the variables.

data, name, tex, and ops are private members. The following constructors are available:

One can easily create subsamples from a dseries object using the overloaded parenthesis operator. If ds is a dseries object with T observations and d is a dates object with S<T elements, such that \min(d) is not smaller than the date associated to the first observation in ds and \max(d) is not greater than the date associated to the last observation, then ds(d) instantiates a new dseries object containing the subsample defined by d.

A list of the available methods, by alphabetical order, is given below. As in the previous section the in place modifications versions of the methods are postfixed with an underscore.

X-13 ARIMA-SEATS interface

|br| The x13 class provides a method for each X-13 command as documented in the X-13 ARIMA-SEATS reference manual (x11, automdl, estimate, ...). The respective options (see Chapter 7 of U.S. Census Bureau (2020)) can then be passed by key/value pairs. The x13 class has 22 members:

arg y:	dseries object with a single variable.
arg x:	dseries object with an arbitrary number of variables (to be used in the REGRESSION block).
arg arima:	structure containing the options of the ARIMA model command.
arg automdl:	structure containing the options of the ARIMA model selection command.
arg regression:	structure containing the options of the Regression command.
arg estimate:	structure containing the options of the estimation command.
arg transform:	structure containing the options of the transform command.
arg outlier:	structure containing the options of the outlier command.
arg forecast:	structure containing the options of the forecast command.
arg check:	structure containing the options of the check command.
arg x11:	structure containing the options of the X11 command.
arg force:	structure containing the options of the force command.
arg history:	structure containing the options of the history command.
arg metadata:	structure containing the options of the metadata command.
arg identify:	structure containing the options of the identify command.
arg pickmdl:	structure containing the options of the pickmdl command.
arg seats:	structure containing the options of the seats command.
arg slidingspans:	structure containing the options of the slidingspans command.
arg spectrum:	structure containing the options of the spectrum command.
arg x11regression:	structure containing the options of the x11Regression command.
arg results:	structure containing the results returned by x13.
arg commands:	cell array containing the list of commands.

All these members are private. The following constructors are available:

The following methods allow to set sequence of X-13 commands, write an .spc file, and run the X-13 binary:

Example

>> ts = dseries(rand(100,1),'1999M1');
>> o = x13(ts);

>> o.x11('save','(d11)');
>> o.automdl('savelog','amd','mixed','no');
>> o.outlier('types','all','save','(fts)');
>> o.check('maxlag',24,'save','(acf pcf)');
>> o.estimate('save','(mdl est)');
>> o.forecast('maxlead',18,'probability',0.95,'save','(fct fvr)');

>> o.run();

The above example shows a run of X13 with various commands an options specified.

Example

%   1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960
y = [112  115  145  171  196  204  242  284  315  340  360  417 ...   % Jan
     118  126  150  180  196  188  233  277  301  318  342  391 ...   % Feb
     132  141  178  193  236  235  267  317  356  362  406  419 ...   % Mar
     129  135  163  181  235  227  269  313  348  348  396  461 ...   % Apr
     121  125  172  183  229  234  270  318  355  363  420  472 ...   % May
     135  149  178  218  243  264  315  374  422  435  472  535 ...   % Jun
     148  170  199  230  264  302  364  413  465  491  548  622 ...   % Jul
     148  170  199  242  272  293  347  405  467  505  559  606 ...   % Aug
     136  158  184  209  237  259  312  355  404  404  463  508 ...   % Sep
     119  133  162  191  211  229  274  306  347  359  407  461 ...   % Oct
     104  114  146  172  180  203  237  271  305  310  362  390 ...   % Nov
     118  140  166  194  201  229  278  306  336  337  405  432 ]'; % Dec

ts = dseries(y,'1949M1');
o = x13(ts);
o.transform('function','auto','savelog','atr');
o.automdl('savelog','all');
o.x11('save','(d11 d10)');
o.run();
o.clean();

y_SA=o.results.d11;
y_seasonal_pattern=o.results.d10;

figure('Name','Comparison raw data and SAed data');
plot(ts.dates,log(o.y.data),ts.dates,log(y_SA.data),ts.dates,log(y_seasonal_pattern.data))

The above example shows how to remove a seasonal pattern from a time series. o.transform('function','auto','savelog','atr') instructs the subsequent o.automdl() command to check whether an additional or a multiplicative pattern fits the data better and to save the result. The result is saved in o.results.autotransform, which in the present example indicates that a log transformation, i.e. a multiplicative model was preferred. The o.automdl('savelog','all') automatically selects a fitting ARIMA model and saves all relevant output to the .log-file. The o.x11('save','(d11, d10)') instructs x11 to save both the final seasonally adjusted series d11 and the final seasonal factor d10 into dseries with the respective names in the output structure o.results. o.clean() removes the temporary files created by o.run(). Among these are the .log-file storing summary information, the .err-file storing information on problems encountered, the .out-file storing the raw output, and the .spc-file storing the specification for the x11 run. There may be further files depending on the output requested. The last part of the example reads out the results and plots a comparison of the logged raw data and its log-additive decomposition into a seasonal pattern and the seasonally adjusted series.

Miscellaneous

Time aggregation

|br| A set of functions allows to convert time series to lower frequencies:

• dseries2M converts daily time series object to monthly time series object.
• dseries2Q converts daily or monthly time series object to quarterly time series object.
• dseries2S converts daily, monthly, or quarterly time series object to bi-annual time series object.
• dseries2Y converts daily, monthly, quarterly, or bi-annual time series object to annual time series object.

|br| All these routines have two mandatory input arguments: the first one is a dseries object, the second one the name (row char array) of the aggregation method. Possible values for the second argument are:

• arithmetic-average (for growth rates),
• geometric-average (for growth factors),
• sum (for flow variables), and
• end-of-period (for stock variables).

Example

>> ts = dseries(rand(12,1),'2000M1')

ts is a dseries object:

        | Variable_1
2000M1  | 0.55293
2000M2  | 0.14228
2000M3  | 0.38036
2000M4  | 0.39657
2000M5  | 0.57674
2000M6  | 0.019402
2000M7  | 0.57758
2000M8  | 0.9322
2000M9  | 0.10687
2000M10 | 0.73215
2000M11 | 0.97052
2000M12 | 0.60889

>> ds = dseries2Y(ts, 'end-of-period')

ds is a dseries object:

      | Variable_1
2000Y | 0.60889

Create time series with a univariate model

|br| It is possible to expand a dseries object recursively with the from command. For instance to create a dseries object containing the simulation of an ARMA(1,1) model:

>> e = dseries(randn(100, 1), '2000Q1', 'e', '\varepsilon');
>> y = dseries(zeros(100, 1), '2000Q1', 'y');
>> from 2000Q2 to 2024Q4 do y(t)=.9*y(t-1)+e(t)-.4*e(t-1);
>> y

y is a dseries object:

       | y
2000Q1 | 0
2000Q2 | -0.95221
2000Q3 | -0.6294
2000Q4 | -1.8935
2001Q1 | -1.1536
2001Q2 | -1.5905
2001Q3 | 0.97056
2001Q4 | 1.1409
2002Q1 | -1.9255
2002Q2 | -0.29287
       |
2022Q2 | -1.4683
2022Q3 | -1.3758
2022Q4 | -1.2218
2023Q1 | -0.98145
2023Q2 | -0.96542
2023Q3 | -0.23203
2023Q4 | -0.34404
2024Q1 | 1.4606
2024Q2 | 0.901
2024Q3 | 2.4906
2024Q4 | 0.79661

The expression following the do keyword can be any univariate equation, the only constraint is that the model cannot have leads. It can be a static equation, or a very nonlinear backward equation with an arbitrary number of lags. The from command must be followed by a range, which is separated from the (recursive) expression to be evaluated by the do command.