6. 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).
6.1. Dates¶
6.1.1. 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
1990A
1990S2
1990H2
1990Q4
1990M11
Note that there are two syntaxes for annual dates (1990A is equivalent to 1990Y), and for bi-annual dates (1990H2 is equivalent to 1990S2).
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 = 1950Q1thenb = 1951Q2andb = a + 5are identical.
plus unary operator (+)
Increments a date by one period.
+1950Q1is identical to1950Q2,++++1950Q1is identical to1951Q1.
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 second date (e.g.
1951Q2-1950Q1is equal to5). If the second argument is an integerX, subtractsXperiods from the date (e.g.1951Q2-2is equal to1950Q4).
minus unary operator (-)
Subtracts one period to a date.
-1950Q1is identical to1949Q4. The unary minus operator is the reciprocal of the unary plus operator,+-1950Q1is identical to1950Q1.
colon operator (:)
Can be used to create a range of dates. For instance,
r = 1950Q1:1951Q1creates adatesobject with five elements:1950Q1,1950Q2,1950Q3,1950Q4and1951Q1. By default the increment between each element is one period. This default can be changed using, for instance, the following instruction:1950Q1:2:1951Q1which will instantiate adatesobject with three elements:1950Q1,1950Q3and1951Q1.
horzcat operator ([,])
Concatenates dates objects without removing repetitions. For instance
[1950Q1, 1950Q2]is adatesobject with two elements (1950Q1and1950Q2).
vertcat operator ([;])
Same as
horzcatoperator.
eq operator (equal, ==)
Tests if two
datesobjects are equal.+1950Q1==1950Q2returnstrue,1950Q1==1950Q2returnsfalse. If the compared objects have bothn>1elements, theeqoperator returns a column vector,nby1, of logicals.
ne operator (not equal, ~=)
Tests if two
datesobjects are not equal.+1950Q1~=returnsfalsewhile1950Q1~=1950Q2returnstrue. If the compared objects both haven>1elements, theneoperator returns annby1column vector of logicals.
lt operator (less than, <)
Tests if a
datesobject preceeds anotherdatesobject. For instance,1950Q1<1950Q3returnstrue. If the compared objects have bothn>1elements, theltoperator returns a column vector,nby1, of logicals.
gt operator (greater than, >)
Tests if a
datesobject follows anotherdatesobject. For instance,1950Q1>1950Q3returnsfalse. If the compared objects have bothn>1elements, thegtoperator returns a column vector,nby1, of logicals.
le operator (less or equal, <=)
Tests if a
datesobject preceeds anotherdatesobject or is equal to this object. For instance,1950Q1<=1950Q3returnstrue. If the compared objects have bothn>1elements, theleoperator returns a column vector,nby1, of logicals.
ge operator (greater or equal, >=)
Tests if a
datesobject follows anotherdatesobject or is equal to this object. For instance,1950Q1>=1950Q3returnsfalse. If the compared objects have bothn>1elements, thegeoperator returns a column vector,nby1, 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.
6.1.2. The dates class¶
- Dynare class: dates
- Members:
freq – equal to 1, 2, 4, 12 or 365 (resp. for annual, bi-annual, quarterly, monthly, or daily dates).
time – a
n*1array 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
datesobject: all the elements must have common frequency.The
datesclass has the following constructors:- Constructor: dates()
- Constructor: dates(FREQ)
Returns an emptydatesobject with a given frequency (if the constructor is called with one input argument).FREQis a character equal to ’Y’ or ’A’ for annual dates, ’S’ or ’H’ for bi-annual dates, ’Q’ for quarterly dates, ’M’ for monthly dates, or ’D’ for daily dates. Note thatFREQis not case sensitive, so that, for instance, ’q’ is also allowed for quarterly dates. The frequency can also be set with an integer scalar equal to 1 (annual), 2 (bi-annual), 4 (quarterly), 12 (monthly), or 365 (daily). The instantiation of empty objects can be used to rename thedatesclass. For instance, if one only works with quarterly dates, objectqqcan be created as:qq = dates('Q')
and a
datesobject holding the date2009Q2:d0 = qq(2009,2);
which is much simpler if
datesobjects have to be defined programmatically. For daily dates, we would instantiate an empty daily dates object as:dd = dates('D')
and a
datesobject holding the date2020-12-31:d1 = dd(2020,12,31);
- Constructor: dates(STRING)
- Constructor: dates(STRING, STRING, ...)
Returns adatesobject that represents a date as given by the stringSTRING. This string has to be interpretable as a date (only strings of the following forms are admitted:'1990Y','1990A',1990S1,1990H1,'1990Q1','1990M2', or'2020-12-31'), the routineisdatecan be used to test if a string is interpretable as a date. If more than one argument is provided, they should all be dates represented as strings, the resultingdatesobject contains as many elements as arguments to the constructor. For the daily dates, the string must be of the form yyyy-mm-dd with two digits for the months (mm) and days (dd), even if the number of days or months is smaller than ten (in this case a leading 0 is required).
- Constructor: dates(DATES)
- Constructor: dates(DATES, DATES, ...)
Returns a copy of thedatesobjectDATESpassed as input arguments. If more than one argument is provided, they should all bedatesobjects. The number of elements in the instantiateddatesobject is equal to the sum of the elements in thedatespassed as arguments to the constructor.
- Constructor: dates(FREQ, YEAR, SUBPERIOD[, S])
whereFREQis a single character (’Y’, ’A’, ’S’, ’H’, ’Q’, ’M’, ’D’) or integer (1, 2, 4, 12, or 365) specifying the frequency,YEARandSUBPERIODandSaren*1vectors of integers. Returns adatesobject withnelements. The last argument,S, is only to be used for daily frequency. IfFREQis equal to'Y','A'or1, the third argument is not needed (becauseSUBPERIODis necessarily a vector of ones in this case).
Example
do1 = dates('1950Q1'); do2 = dates('1950Q2','1950Q3'); do3 = dates(do1,do2); do4 = dates('Q',1950, 1); do5 = dates('D',1973, 1, 25);
A
datesobject with multiple elements can be considered a one-dimensional array of dates. Standard array operations can be applied to adatesobject:square brackets can be used to concatenate dates objects:
>> A = dates('1938Q4'); >> B = dates('1945Q3'); >> C = [A, B];
semicolons can be used to create ranges of dates:
>> A = dates('2009Q2'); >> B = A:A+2; >> B B = <dates: 2009Q2, 2009Q3, 2009Q4>
objects can be indexed by an integer or a vector of integer:
>> B(1) ans = <dates: 2009Q2> >> B(end) ans = <dates: 2009Q4> >> B(1:2) ans = <dates: 2009Q2, 2009Q3>
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
multiplybytwoto an objectXwe write:>> X = 2; >> Y = X.multiplybytwo(); >> X 2 >> Y 4
or equivalently:
>> Y = multiplybytwo(X);
the object
Xis left unchanged, and the objectYis a modified copy ofX(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.
- Method: C = append(A, B)¶
- Method: append_(B)¶
AppendsdatesobjectB, or a string that can be interpreted as a date, to thedatesobjectA. IfBis adatesobject it is assumed that it has no more than one element.Example
>> D = dates('1950Q1','1950Q2'); >> d = dates('1950Q3'); >> E = D.append(d); >> F = D.append('1950Q3'); >> isequal(E,F) ans = 1 >> F F = <dates: 1950Q1, 1950Q2, 1950Q3> >> D D = <dates: 1950Q1, 1950Q2> >> D.append_('1950Q3') ans = <dates: 1950Q1, 1950Q2, 1950Q3>
- Method: B = char(A)¶
Overloads the MATLAB/Octavecharfunction. Converts adatesobject into a character array.Example
>> A = dates('1950Q1'); > A.char() ans = '1950Q1'
- Method: C = colon(A, B)¶
- Method: C = colon(A, i, B)
Overloads the MATLAB/Octave colon (:) operator. A and B aredatesobjects. The optional incrementiis a scalar integer (default value isi=1). This method returns adatesobject and can be used to create ranges of dates.Example
>> A = dates('1950Q1'); >> B = dates('1951Q2'); >> C = A:B C = <dates: 1950Q1, 1950Q2, 1950Q3, 1950Q4, 1951Q1> >> D = A:2:B D = <dates: 1950Q1, 1950Q3, 1951Q1>
- Method: B = copy(A)¶
Returns a copy of adatesobject.
- Method: disp(A)¶
Overloads the MATLAB/Octave disp function fordatesobject.
- Method: display(A)¶
Overloads the MATLAB/Octave display function fordatesobject.Example
>> disp(B) B = <dates: 1950Q1, 1950Q2, 1950Q3, 1950Q4, 1951Q1, 1951Q2, 1951Q3, 1951Q4, 1952Q1, 1952Q2, 1952Q3> >> display(B) B = <dates: 1950Q1, 1950Q2, ..., 1952Q2, 1952Q3>
- Method: B = double(A)¶
Overloads the MATLAB/Octavedoublefunction.Ais adatesobject. The method returns a floating point representation of adatesobject, the integer and fractional parts respectively corresponding to the year and the subperiod. The fractional part is the subperiod number minus one divided by the frequency (1,4, or12).Example:
>> a = dates('1950Q1'):dates('1950Q4'); >> a.double() ans = 1950.00 1950.25 1950.50 1950.75
- Method: C = eq(A, B)¶
Overloads the MATLAB/Octaveeq(equal,==) operator.datesobjectsAandBmust have the same number of elements (say,n). The returned argument is anby1vector of logicals. The i-th element ofCis equal totrueif and only if the datesA(i)andB(i)are the same.Example
>> A = dates('1950Q1','1951Q2'); >> B = dates('1950Q1','1950Q2'); >> A==B ans = 2x1 logical array 1 0
- Method: C = ge(A, B)¶
Overloads the MATLAB/Octavege(greater or equal,>=) operator.datesobjectsAandBmust have the same number of elements (say,n). The returned argument is anby1vector of logicals. The i-th element ofCis equal totrueif and only if the dateA(i)is posterior or equal to the dateB(i).Example
>> A = dates('1950Q1','1951Q2'); >> B = dates('1950Q1','1950Q2'); >> A>=B ans = 2x1 logical array 1 1
- Method: C = gt(A, B)¶
Overloads the MATLAB/Octavegt(greater than,>) operator.datesobjectsAandBmust have the same number of elements (say,n). The returned argument is anby1vector of logicals. The i-th element ofCis equal to1if and only if the dateA(i)is posterior to the dateB(i).Example
>> A = dates('1950Q1','1951Q2'); >> B = dates('1950Q1','1950Q2'); >> A>B ans = 2x1 logical array 0 1
- Method: D = horzcat(A, B, C, ...)¶
Overloads the MATLAB/Octavehorzcatoperator. All the input arguments must bedatesobjects. The returned argument is adatesobject gathering all the dates given in the input arguments (repetitions are not removed).Example
>> A = dates('1950Q1'); >> B = dates('1950Q2'); >> C = [A, B]; >> C C = <dates: 1950Q1, 1950Q2>
- Method: C = intersect(A, B)¶
Overloads the MATLAB/Octaveintersectfunction. All the input arguments must bedatesobjects. The returned argument is adatesobject gathering all the common dates given in the input arguments. IfAandBare disjointdatesobjects, the function returns an emptydatesobject. Returned dates indatesobjectCare sorted by increasing order.Example
>> A = dates('1950Q1'):dates('1951Q4'); >> B = dates('1951Q1'):dates('1951Q4'); >> C = intersect(A, B); >> C C = <dates: 1951Q1, 1951Q2, 1951Q3, 1951Q4>
- Method: B = isempty(A)¶
Overloads the MATLAB/Octaveisemptyfunction.Example
>> A = dates('1950Q1'); >> A.isempty() ans = logical 0 >> B = dates(); >> B.isempty() ans = logical 1
- Method: C = isequal(A, B)¶
Overloads the MATLAB/Octaveisequalfunction.Example
>> A = dates('1950Q1'); >> B = dates('1950Q2'); >> isequal(A, B) ans = logical 0
- Method: C = le(A, B)¶
Overloads the MATLAB/Octavele(less or equal,<=) operator.datesobjectsAandBmust have the same number of elements (say,n). The returned argument is anby1vector of logicals. The i-th element ofCis equal totrueif and only if the dateA(i)is anterior or equal to the dateB(i).Example
>> A = dates('1950Q1','1951Q2'); >> B = dates('1950Q1','1950Q2'); >> A<=B ans = 2x1 logical array 1 0
- Method: B = length(A)¶
Overloads the MATLAB/Octavelengthfunction. Returns the number of elements in adatesobject.Example
>> A = dates('1950Q1'):dates(2000Q3); >> A.length() ans = 203
- Method: C = lt(A, B)¶
Overloads the MATLAB/Octavelt(less than,<) operator.datesobjectsAandBmust have the same number of elements (say,n). The returned argument is anby1vector of logicals. The i-th element ofCis equal totrueif and only if the dateA(i)is anterior or equal to the dateB(i).Example
>> A = dates('1950Q1','1951Q2'); >> B = dates('1950Q1','1950Q2'); >> A<B ans = 2x1 logical array 0 0
- Method: D = max(A, B, C, ...)¶
Overloads the MATLAB/Octavemaxfunction. All input arguments must bedatesobjects. The function returns a single elementdatesobject containing the greatest date.Example
>> A = {dates('1950Q2'), dates('1953Q4','1876Q2'), dates('1794Q3')}; >> max(A{:}) ans = <dates: 1953Q4>
- Method: D = min(A, B, C, ...)¶
Overloads the MATLAB/Octaveminfunction. All input arguments must bedatesobjects. The function returns a single elementdatesobject containing the smallest date.Example
>> A = {dates('1950Q2'), dates('1953Q4','1876Q2'), dates('1794Q3')}; >> min(A{:}) ans = <dates: 1794Q3>
- Method: C = minus(A, B)¶
Overloads the MATLAB/Octaveminusoperator (-). If both input arguments aredatesobjects, then number of periods betweenAandBis returned (so thatA+C=B). IfBis a vector of integers, the minus operator shifts thedatesobject byBperiods backward.Example
>> d1 = dates('1950Q1','1950Q2','1960Q1'); >> d2 = dates('1950Q3','1950Q4','1960Q1'); >> ee = d2-d1 ee = 2 2 0 >> d1-(-ee) ans = <dates: 1950Q3, 1950Q4, 1960Q1>
- Method: C = mtimes(A, B)¶
Overloads the MATLAB/Octavemtimesoperator (*).AandBare respectively expected to be adatesobject and a scalar integer. ReturnsdatesobjectAreplicatedBtimes.Example
>> d = dates('1950Q1'); >> d*2 ans = <dates: 1950Q1, 1950Q1>
- Method: C = ne(A, B)¶
Overloads the MATLAB/Octavene(not equal,~=) operator.datesobjectsAandBmust have the same number of elements (say,n) or one of the inputs must be a single elementdatesobject. The returned argument is anby1vector of logicals. The i-th element ofCis equal totrueif and only if the datesA(i)andB(i)are different.Example
>> A = dates('1950Q1','1951Q2'); >> B = dates('1950Q1','1950Q2'); >> A~=B ans = 2x1 logical array 0 1
- Method: C = plus(A, B)¶
Overloads the MATLAB/Octaveplusoperator (+). If both input arguments aredatesobjects, then the method combinesAandBwithout removing repetitions. IfBis a vector of integers, theplusoperator shifts thedatesobject byBperiods forward.Example
>> d1 = dates('1950Q1','1950Q2')+dates('1960Q1'); >> d2 = (dates('1950Q1','1950Q2')+2)+dates('1960Q1'); >> ee = d2-d1; ee = 2 2 0 >> d1+ee ans = <dates: 1950Q3, 1950Q4, 1960Q1>
- Method: C = pop(A)¶
- Method: C = pop(A, B)
- Method: pop_()¶
- Method: pop_(B)
Pop method fordatesclass. If only one input is provided, the method removes the last element of adatesobject. If a second input argument is provided, a scalar integer between1andA.length(), the method removes element numberBfromdatesobjectA.Example
>> d = dates('1950Q1','1950Q2'); >> d.pop() ans = <dates: 1950Q1> >> d.pop_(1) ans = <dates: 1950Q2>
- Method: C = remove(A, B)¶
- Method: remove_(B)¶
Remove method fordatesclass. Both inputs have to bedatesobjects, removes dates inBfromA.Example
>> d = dates('1950Q1','1950Q2'); >> d.remove(dates('1950Q2')) ans = <dates: 1950Q1>
- Method: C = setdiff(A, B)¶
Overloads the MATLAB/Octavesetdifffunction. All the input arguments must bedatesobjects. The returned argument is adatesobject all dates present inAbut not inB. IfAandBare disjointdatesobjects, the function returnsA. Returned dates indatesobjectCare sorted by increasing order.Example
>> A = dates('1950Q1'):dates('1969Q4'); >> B = dates('1960Q1'):dates('1969Q4'); >> C = dates('1970Q1'):dates('1979Q4'); >> setdiff(A, B) ans = <dates: 1950Q1, 1950Q2, ..., 1959Q3, 1959Q4> >> setdiff(A, C) ans = <dates: 1950Q1, 1950Q2, ..., 1969Q3, 1969Q4>
- Method: B = sort(A)¶
- Method: sort_()¶
Sort method fordatesobjects. Returns adatesobject with elements sorted by increasing order.Example
>> dd = dates('1945Q3','1938Q4','1789Q3'); >> dd.sort() ans = <dates: 1789Q3, 1938Q4, 1945Q3>
- Method: B = strings(A)¶
Converts adatesobject into a cell of char arrays.Example
>> A = dates('1950Q1'); >> A = A:A+1; >> A.strings() ans = 1x2 cell array {'1950Q1'} {'1950Q2'}
- Method: B = subperiod(A)¶
Returns the subperiod of a date (an integer scalar between 1 andA.freq). This method is not implemented for daily dates.Example
>> A = dates('1950Q2'); >> A.subperiod() ans = 2
- Method: B = uminus(A)¶
Overloads the MATLAB/Octave unary minus operator. Returns adatesobject with elements shifted one period backward.Example
>> dd = dates('1945Q3','1938Q4','1973Q1'); >> -dd ans = <dates: 1945Q2, 1938Q3, 1972Q4>
- Method: D = union(A, B, C, ...)¶
Overloads the MATLAB/Octaveunionfunction. Returns adatesobject with elements sorted by increasing order (repetitions are removed, to keep the repetitions use thehorzcatorplusoperators).Example
>> d1 = dates('1945Q3','1973Q1','1938Q4'); >> d2 = dates('1973Q1','1976Q1'); >> union(d1,d2) ans = <dates: 1938Q4, 1945Q3, 1973Q1, 1976Q1>
- Method: B = unique(A)¶
- Method: unique_()¶
Overloads the MATLAB/Octaveuniquefunction. Returns adatesobject with repetitions removed (only the last occurence of a date is kept).Example
>> d1 = dates('1945Q3','1973Q1','1945Q3'); >> d1.unique() ans = <dates: 1973Q1, 1945Q3>
- Method: B = uplus(A)¶
Overloads the MATLAB/Octave unary plus operator. Returns adatesobject with elements shifted one period ahead.Example
>> dd = dates('1945Q3','1938Q4','1973Q1'); >> +dd ans = <dates: 1945Q4, 1939Q1, 1973Q2>
- Method: D = vertcat(A, B, C, ...)¶
Overloads the MATLAB/Octavehorzcatoperator. All the input arguments must bedatesobjects. The returned argument is adatesobject gathering all the dates given in the input arguments (repetitions are not removed).
- Method: B = year(A)¶
Returns the year of a date (an integer scalar between 1 andA.freq).Example
>> A = dates('1950Q2'); >> A.subperiod() ans = 1950
6.2. The dseries class¶
- Dynare class: dseries¶
The MATLAB/Octavedseriesclass handles time series data. As any MATLAB/Octave statements, this class can be used in a Dynare’s mod file. Adseriesobject has six members:- arg name:
A
vobs*1cell of strings or avobs*pcharacter array, the names of the variables.- arg tex:
A
vobs*1cell of strings or avobs*pcharacter array, the tex names of the variables.- arg dates dates:
An object with
nobselements, the dates of the sample.- arg double data:
A
nobsbyvobsarray, the data.- arg ops:
The history of operations on the variables.
- arg tags:
The user-defined tags on the variables.
data,name,tex, andopsare private members. The following constructors are available:- Constructor: dseries()
- Constructor: dseries(INITIAL_DATE)
Instantiates an emptydseriesobject with, if defined, an initial date given by the single elementdatesobject INITIAL_DATE.
- Constructor: dseries(FILENAME[, INITIAL_DATE])
Instantiates and populates adseriesobject with a data file specified by FILENAME, a string passed as input. Valid file types are.m,.mat,.csvand.xls/.xlsx(Octave only supports.xlsxfiles and the io package from Octave-Forge must be installed). The extension of the file should be explicitly provided.A typical
.mfile will have the following form:FREQ__ = 4; INIT__ = '1994Q3'; NAMES__ = {'azert';'yuiop'}; TEX__ = {'azert';'yuiop'}; azert = randn(100,1); yuiop = randn(100,1);
If a
.matfile is used instead, it should provide the same informations, except that the data should not be given as a set of vectors, but as a single matrix of doubles namedDATA__. This array should have as many columns as elements inNAMES__(the number of variables). Note that theINIT__variable can be either adatesobject or a string which could be used to instantiate the samedatesobject. IfINIT__is not provided in the.mator.mfile, the initial is by default set equal todates('1Y'). If a second input argument is passed to the constructor,datesobject INITIAL_DATE, the initial date defined in FILENAME is reset to INITIAL_DATE. This is typically usefull ifINIT__is not provided in the data file.If an
.xlsxfile is used, the first row should be a header containing the variable names. The first column may contain date information that must correspond to a valid date format recognized by Dynare. If such date information is specified in the first column, its header name must be left empty.
- Constructor: dseries(DATA_MATRIX[,INITIAL_DATE[,LIST_OF_NAMES[,TEX_NAMES]]])
- Constructor: dseries(DATA_MATRIX[,RANGE_OF_DATES[,LIST_OF_NAMES[,TEX_NAMES]]])
If the data is not read from a file, it can be provided via a \(T \times N\) matrix as the first argument todseries’ constructor, with \(T\) representing the number of observations on \(N\) variables. The optional second argument, INITIAL_DATE, can be either adatesobject representing the period of the first observation or a string which would be used to instantiate adatesobject. Its default value isdates('1Y'). The optional third argument, LIST_OF_NAMES, is a \(N \times 1\) cell of strings with one entry for each variable name. The default name associated with columniof DATA_MATRIX isVariable_i. The final argument, TEX_NAMES, is a \(N \times 1\) cell of strings composed of the LaTeX names associated with the variables. The default LaTeX name associated with columniof DATA_MATRIX isVariable\_i. If the optional second input argument is a range of dates,datesobject RANGE_OF_DATES, the number of rows in the first argument must match the number of elements RANGE_OF_DATES or be equal to one (in which case the single observation is replicated).
- Constructor: dseries(TABLE)
Creates a
dseriesobject given the MATLAB Table provided as the sole argument. It is assumed that the first column of the table contains the dates of thedseriesand the first row contains the names. This feature is not available under Octave or MATLAB R2013a or earlier.Example
Various ways to create a
dseriesobject:do1 = dseries(1999Q3); do2 = dseries('filename.csv'); do3 = dseries([1; 2; 3], 1999Q3, {'var123'}, {'var_{123}'}); >> do1 = dseries(dates('1999Q3')); >> do2 = dseries('filename.csv'); >> do3 = dseries([1; 2; 3], dates('1999Q3'), {'var123'}, {'var_{123}'});
One can easily create subsamples from a
dseriesobject using the overloaded parenthesis operator. Ifdsis adseriesobject with \(T\) observations anddis adatesobject with \(S<T\) elements, such that \(\min(d)\) is not smaller than the date associated to the first observation indsand \(\max(d)\) is not greater than the date associated to the last observation, thends(d)instantiates a newdseriesobject containing the subsample defined byd.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.
- Method: A = abs(B)¶
- Method: abs_()¶
Overloads theabs()function fordseriesobjects. Returns the absolute value of the variables in dseriesobjectB.Example
>> ts0 = dseries(randn(3,2),'1973Q1',{'A1'; 'A2'},{'A_1'; 'A_2'}); >> ts1 = ts0.abs(); >> ts0 ts0 is a dseries object: | A1 | A2 1973Q1 | -0.67284 | 1.4367 1973Q2 | -0.51222 | -0.4948 1973Q3 | 0.99791 | 0.22677 >> ts1 ts1 is a dseries object: | abs(A1) | abs(A2) 1973Q1 | 0.67284 | 1.4367 1973Q2 | 0.51222 | 0.4948 1973Q3 | 0.99791 | 0.22677
Example (in-place modification version)
>> ts0 = dseries(randn(3,2),'1973Q1',{'A1'; 'A2'},{'A_1'; 'A_2'}); >> ts0 ts0 is a dseries object: | A1 | A2 1973Q1 | -0.67284 | 1.4367 1973Q2 | -0.51222 | -0.4948 1973Q3 | 0.99791 | 0.22677 >> ts0.abs_(); >> ts0 ts0 is a dseries object: | abs(A1) | abs(A2) 1973Q1 | 0.67284 | 1.4367 1973Q2 | 0.51222 | 0.4948 1973Q3 | 0.99791 | 0.22677
- Method: [A, B] = align(A, B)¶
- Method: align_(B)¶
If
dseriesobjectsAandBare defined on different time ranges, this function extendsAand/orBwith NaNs so that they are defined on the same time range. Note that bothdseriesobjects must have the same frequency.Example
>> ts0 = dseries(rand(5,1),dates('2000Q1')); % 2000Q1 -> 2001Q1 >> ts1 = dseries(rand(3,1),dates('2000Q4')); % 2000Q4 -> 2001Q2 >> [ts0, ts1] = align(ts0, ts1); % 2000Q1 -> 2001Q2 >> ts0 ts0 is a dseries object: | Variable_1 2000Q1 | 0.81472 2000Q2 | 0.90579 2000Q3 | 0.12699 2000Q4 | 0.91338 2001Q1 | 0.63236 2001Q2 | NaN >> ts1 ts1 is a dseries object: | Variable_1 2000Q1 | NaN 2000Q2 | NaN 2000Q3 | NaN 2000Q4 | 0.66653 2001Q1 | 0.17813 2001Q2 | 0.12801 >> ts0 = dseries(rand(5,1),dates('2000Q1')); % 2000Q1 -> 2001Q1 >> ts1 = dseries(rand(3,1),dates('2000Q4')); % 2000Q4 -> 2001Q2 >> align_(ts0, ts1); % 2000Q1 -> 2001Q2 >> ts1 ts1 is a dseries object: | Variable_1 2000Q1 | NaN 2000Q2 | NaN 2000Q3 | NaN 2000Q4 | 0.66653 2001Q1 | 0.17813 2001Q2 | 0.12801
Example (in-place modification version)
>> ts0 = dseries(rand(5,1),dates('2000Q1')); % 2000Q1 -> 2001Q1 >> ts1 = dseries(rand(3,1),dates('2000Q4')); % 2000Q4 -> 2001Q2 >> ts0 ts0 is a dseries object: | Variable_1 2000Q1 | 0.80028 2000Q2 | 0.14189 2000Q3 | 0.42176 2000Q4 | 0.91574 2001Q1 | 0.79221 >> ts1 ts1 is a dseries object: | Variable_1 2000Q4 | 0.95949 2001Q1 | 0.65574 2001Q2 | 0.035712 >> align_(ts0, ts1); % 2000Q1 -> 2001Q2 >> ts0 ts0 is a dseries object: | Variable_1 2000Q1 | 0.80028 2000Q2 | 0.14189 2000Q3 | 0.42176 2000Q4 | 0.91574 2001Q1 | 0.79221 2001Q2 | NaN >> ts1 ts1 is a dseries object: | Variable_1 2000Q1 | NaN 2000Q2 | NaN 2000Q3 | NaN 2000Q4 | 0.95949 2001Q1 | 0.65574 2001Q2 | 0.035712
- Method: C = backcast(A, B[, diff])¶
- Method: backcast_(B[, diff])¶
Backcasts
dseriesobjectAwithdseriesobject B’s growth rates (except if the last optional argument,diff, is true in which case first differences are used). Bothdseriesobjects must have the same frequency.
- Method: B = baxter_king_filter(A[, hf[, lf[, K]]])¶
- Method: baxter_king_filter_([hf[, lf[, K]]])¶
Implementation of the Baxter and King (1999) band pass filter fordseriesobjects. This filter isolates business cycle fluctuations with a period of length ranging betweenhf(high frequency) tolf(low frequency) using a symmetric moving average smoother with \(2K+1\) points, so that \(K\) observations at the beginning and at the end of the sample are lost in the computation of the filter. The default value forhfis6, forlfis32, and forKis12.Example
% Simulate a component model (stochastic trend, deterministic % trend, and a stationary autoregressive process). e = 0.2*randn(200,1); u = randn(200,1); stochastic_trend = cumsum(e); deterministic_trend = .1*transpose(1:200); x = zeros(200,1); for i=2:200 x(i) = .75*x(i-1) + u(i); end y = x + stochastic_trend + deterministic_trend; % Instantiates time series objects. ts0 = dseries(y,'1950Q1'); ts1 = dseries(x,'1950Q1'); % stationary component. % Apply the Baxter-King filter. ts2 = ts0.baxter_king_filter(); % Plot the filtered time series. plot(ts1(ts2.dates).data,'-k'); % Plot of the stationary component. hold on plot(ts2.data,'--r'); % Plot of the filtered y. hold off axis tight id = get(gca,'XTick'); set(gca,'XTickLabel',strings(ts1.dates(id)));
- Method: B = center(A[, geometric])¶
- Method: center_([geometric])¶
Centers variables indseriesobjectAaround their arithmetic means, except if the optional argumentgeometricis set equal totruein which case all the variables are divided by their geometric means.
- Method: C = chain(A, B)¶
- Method: chain_(B)¶
Merge twodseriesobjects along the time dimension. The two objects must have the same number of observed variables, and the initial date inBmust not be posterior to the last date inA. The returneddseriesobject,C, is built by extendingAwith the cumulated growth factors ofB.Example
>> ts = dseries([1; 2; 3; 4],dates('1950Q1')) ts is a dseries object: | Variable_1 1950Q1 | 1 1950Q2 | 2 1950Q3 | 3 1950Q4 | 4 >> us = dseries([3; 4; 5; 6],dates('1950Q3')) us is a dseries object: | Variable_1 1950Q3 | 3 1950Q4 | 4 1951Q1 | 5 1951Q2 | 6 >> chain(ts, us) ans is a dseries object: | Variable_1 1950Q1 | 1 1950Q2 | 2 1950Q3 | 3 1950Q4 | 4 1951Q1 | 5 1951Q2 | 6
Example (in-place modification version)
>> ts = dseries([1; 2; 3; 4],dates('1950Q1')) >> us = dseries([3; 4; 5; 6],dates('1950Q3')) >> ts.chain_(us); >> ts ts is a dseries object: | Variable_1 1950Q1 | 1 1950Q2 | 2 1950Q3 | 3 1950Q4 | 4 1951Q1 | 5 1951Q2 | 6
- Method: [error_flag, message ] = check(A)¶
Sanity check ofdseriesobjectA. Returns1if there is an error,0otherwise. The second output argument is a string giving brief informations about the error.
- Method: B = copy(A)
Returns a copy ofA. If an inplace modification method is applied toA, objectBwill not be affected. Note that ifAis assigned toC,C = A, then any in place modification method applied toAwill changeC.Example
>> a = dseries(randn(5,1)) a is a dseries object: | Variable_1 1Y | -0.16936 2Y | -1.1451 3Y | -0.034331 4Y | -0.089042 5Y | -0.66997 >> b = copy(a); >> c = a; >> a.abs(); >> a.abs_(); >> a a is a dseries object: | Variable_1 1Y | 0.16936 2Y | 1.1451 3Y | 0.034331 4Y | 0.089042 5Y | 0.66997 >> b b is a dseries object: | Variable_1 1Y | -0.16936 2Y | -1.1451 3Y | -0.034331 4Y | -0.089042 5Y | -0.66997 >> c c is a dseries object: | Variable_1 1Y | 0.16936 2Y | 1.1451 3Y | 0.034331 4Y | 0.089042 5Y | 0.66997
- Method: B = cumprod(A[, d[, v]])¶
- Method: cumprod_([d[, v]])¶
Overloads the MATLAB/Octavecumprodfunction fordseriesobjects. The cumulated product cannot be computed if the variables indseriesobjectAhave NaNs. If adatesobjectdis provided as a second argument, then the method computes the cumulated product with the additional constraint that the variables in thedseriesobjectBare equal to one in periodd. If a single-observationdseriesobjectvis provided as a third argument, the cumulated product inBis normalized such thatB(d)matchesv(dseriesobjectsAandvmust have the same number of variables).Example
>> ts1 = dseries(2*ones(7,1)); >> ts2 = ts1.cumprod(); >> ts2 ts2 is a dseries object: | cumprod(Variable_1) 1Y | 2 2Y | 4 3Y | 8 4Y | 16 5Y | 32 6Y | 64 7Y | 128 >> ts3 = ts1.cumprod(dates('3Y')); >> ts3 ts3 is a dseries object: | cumprod(Variable_1) 1Y | 0.25 2Y | 0.5 3Y | 1 4Y | 2 5Y | 4 6Y | 8 7Y | 16 >> ts4 = ts1.cumprod(dates('3Y'),dseries(pi)); >> ts4 ts4 is a dseries object: | cumprod(Variable_1) 1Y | 0.7854 2Y | 1.5708 3Y | 3.1416 4Y | 6.2832 5Y | 12.5664 6Y | 25.1327 7Y | 50.2655
- Method: B = cumsum(A[, d[, v]])¶
- Method: cumsum_([d[, v]])¶
Overloads the MATLAB/Octavecumsumfunction fordseriesobjects. The cumulated sum cannot be computed if the variables indseriesobjectAhave NaNs. If adatesobjectdis provided as a second argument, then the method computes the cumulated sum with the additional constraint that the variables in thedseriesobjectBare zero in periodd. If a single observationdseriesobjectvis provided as a third argument, the cumulated sum inBis such thatB(d)matchesv(dseriesobjectsAandvmust have the same number of variables).Example
>> ts1 = dseries(ones(10,1)); >> ts2 = ts1.cumsum(); >> ts2 ts2 is a dseries object: | cumsum(Variable_1) 1Y | 1 2Y | 2 3Y | 3 4Y | 4 5Y | 5 6Y | 6 7Y | 7 8Y | 8 9Y | 9 10Y | 10 >> ts3 = ts1.cumsum(dates('3Y')); >> ts3 ts3 is a dseries object: | cumsum(Variable_1) 1Y | -2 2Y | -1 3Y | 0 4Y | 1 5Y | 2 6Y | 3 7Y | 4 8Y | 5 9Y | 6 10Y | 7 >> ts4 = ts1.cumsum(dates('3Y'),dseries(pi)); >> ts4 ts4 is a dseries object: | cumsum(Variable_1) 1Y | 1.1416 2Y | 2.1416 3Y | 3.1416 4Y | 4.1416 5Y | 5.1416 6Y | 6.1416 7Y | 7.1416 8Y | 8.1416 9Y | 9.1416 10Y | 10.1416
- Method: B = detrend(A[, m])¶
- Method: detrend_([m])¶
DetrendsdseriesobjectAwith a fitted polynomial of orderm. Default value firmis 0 (time series are detrended by removing the average). Note that each variable is detrended with a different polynomial.
- Method: disp(A)
Overloads the MATLAB/Octave disp function fordseriesobject.
- Method: display(A)
Overloads the MATLAB/Octave display function fordseriesobject.displayis the function called by MATLAB to print the content of an object if a semicolon is missing at the end of a MATLAB statement. If thedseriesobject is defined over a too large time span, only the first and last periods will be printed. If thedseriesobject contains too many variables, only the first and last variables will be printed. If all the periods and variables are required, thedispmethod should be used instead.
- Method: C = eq(A, B)
Overloads the MATLAB/Octaveeq(equal,==) operator.dseriesobjectsAandBmust have the same number of observations (say, \(T\)) and variables (\(N\)). The returned argument is a \(T \times N\) matrix of logicals. Element \((i,j)\) ofCis equal totrueif and only if observation \(i\) for variable \(j\) inAandBare the same.Example
>> ts0 = dseries(2*ones(3,1)); >> ts1 = dseries([2; 0; 2]); >> ts0==ts1 ans = 3x1 logical array 1 0 1
- Method: l = exist(A, varname)¶
Tests if variablevarnameexists indseriesobjectA. Returnstrueiff variable exists inA.Example
>> ts = dseries(randn(100,1)); >> ts.exist('Variable_1') ans = logical 1 >> ts.exist('Variable_2') ans = logical 0
- Method: B = exp(A)¶
- Method: exp_(A)¶
Overloads the MATLAB/Octaveexpfunction fordseriesobjects.Example
>> ts0 = dseries(rand(10,1)); >> ts1 = ts0.exp();
Exemple (in-place modification version)
>> ts0 = dseries(rand(3,1)) ts0 is a dseries object: | Variable_1 1Y | 0.82953 2Y | 0.84909 3Y | 0.37253 >> ts0.exp_(); >> ts0 ts0 is a dseries object: | Variable_1 1Y | 2.2922 2Y | 2.3375 3Y | 1.4514
- Method: C = extract(A, B[, ...])¶
Extracts some variables from adseriesobjectAand returns adseriesobjectC. The input arguments followingAare strings representing the variables to be selected in the newdseriesobjectC. To simplify the creation of sub-objects, thedseriesclass overloads the curly braces (D = extract (A, B, C)is equivalent toD = A{B,C}) and allows implicit loops (defined between a pair of@symbol, see examples below) or MATLAB/Octave’s regular expressions (introduced by square brackets).Example
The following selections are equivalent:
>> ts0 = dseries(ones(100,10)); >> ts1 = ts0{'Variable_1','Variable_2','Variable_3'}; >> ts2 = ts0{'Variable_@1,2,3@'}; >> ts3 = ts0{'Variable_[1-3]$'}; >> isequal(ts1,ts2) && isequal(ts1,ts3) ans = logical 1
It is possible to use up to two implicit loops to select variables:
names = {'GDP_1';'GDP_2';'GDP_3'; 'GDP_4'; 'GDP_5'; 'GDP_6'; 'GDP_7'; 'GDP_8'; ... 'GDP_9'; 'GDP_10'; 'GDP_11'; 'GDP_12'; ... 'HICP_1';'HICP_2';'HICP_3'; 'HICP_4'; 'HICP_5'; 'HICP_6'; 'HICP_7'; 'HICP_8'; ... 'HICP_9'; 'HICP_10'; 'HICP_11'; 'HICP_12'}; ts0 = dseries(randn(4,24),dates('1973Q1'),names); ts0{'@GDP,HICP@_@1,3,5@'} ans is a dseries object: | GDP_1 | GDP_3 | GDP_5 | HICP_1 | HICP_3 | HICP_5 1973Q1 | 1.7906 | -1.6606 | -0.57716 | 0.60963 | -0.52335 | 0.26172 1973Q2 | 2.1624 | 3.0125 | 0.52563 | 0.70912 | -1.7158 | 1.7792 1973Q3 | -0.81928 | 1.5008 | 1.152 | 0.2798 | 0.88568 | 1.8927 1973Q4 | -0.03705 | -0.35899 | 0.85838 | -1.4675 | -2.1666 | -0.62032
- Method: fill_(name, v)¶
Assign the valuevto the variablenamein a dseries object. Ifnameis a character row array, it should correspond to an existing variable within the dseries object. Whenvis a scalar, its value will be applied to all periods uniformly. Ifvis a vector, its length must match the number of observations in the dseries object.You can invoke this method for a batch of variables by providing a 1 by n cell array of character row arrays as the first argument. When “v” is a row vector with n elements, the method will be applied uniformly across all periods. If “v” is a matrix, it must have n columns, and the number of rows should correspond to the number of periods.Example
>> ts = dseries(rand(3,3)); >> ts.fill_({'Variable_1', 'Variable_3'}, [1 3]); >> ts ts is a dseries object: | Variable_1 | Variable_2 | Variable_3 1Y | 1 | 0.91338 | 3 2Y | 1 | 0.63236 | 3 3Y | 1 | 0.09754 | 3
- Method: f = firstdate(A)¶
Returns the initial period in thedseriesobjectA.
- Method: f = firstobservedperiod(A)¶
Returns the first period where all the variables indseriesobjectAare observed (non NaN).
- Method: B = flip(A)¶
- Method: flip_(A)¶
Flips the rows in the data member (without changing the periods order).
- Method: f = frequency(B)¶
Returns the frequency of the variables indseriesobjectB.Example
>> ts = dseries(randn(3,2),'1973Q1'); >> ts.frequency ans = 4
- Method: l = ge(A, B)¶
- Method: l = gt(A, B)¶
Overloads thegt(>) andge(>=) binary operators. Returns a logical array.Example
>> ts = dseries(randn(3,1)) ts is a dseries object: | Variable_1 1Y | -1.2075 2Y | 0.71724 3Y | 1.6302 >> ts>1 ans = 3x1 logical array 0 0 1 >> ds = dseries(randn(3,1)) ds is a dseries object: | Variable_1 1Y | 0.48889 2Y | 1.0347 3Y | 0.72689 >> ds>ts ans = 3x1 logical array 1 1 0
- Method: D = horzcat(A, B[, ...])
Overloads thehorzcatMATLAB/Octave’s method fordseriesobjects. Returns adseriesobjectDcontaining the variables indseriesobjects passed as inputs:A, B, ...If the inputs are not defined on the same time ranges, the method adds NaNs to the variables so that the variables are redefined on the smallest common time range. Note that the names in thedseriesobjects passed as inputs must be different and these objects must have common frequency.Example
>> ts0 = dseries(rand(5,2),'1950Q1',{'nifnif';'noufnouf'}); >> ts1 = dseries(rand(7,1),'1950Q3',{'nafnaf'}); >> ts2 = [ts0, ts1]; >> ts2 ts2 is a dseries object: | nifnif | noufnouf | nafnaf 1950Q1 | 0.17404 | 0.71431 | NaN 1950Q2 | 0.62741 | 0.90704 | NaN 1950Q3 | 0.84189 | 0.21854 | 0.83666 1950Q4 | 0.51008 | 0.87096 | 0.8593 1951Q1 | 0.16576 | 0.21184 | 0.52338 1951Q2 | NaN | NaN | 0.47736 1951Q3 | NaN | NaN | 0.88988 1951Q4 | NaN | NaN | 0.065076 1952Q1 | NaN | NaN | 0.50946
- Method: B = hpcycle(A[, lambda])¶
- Method: hpcycle_([lambda])¶
Extracts the cycle component from adseriesAobject using the Hodrick and Prescott (1997) filter and returns adseriesobject,B. The default value forlambda, the smoothing parameter, is1600.Example
% Simulate a component model (stochastic trend, deterministic % trend, and a stationary autoregressive process). e = 0.2*randn(200,1); u = randn(200,1); stochastic_trend = cumsum(e); deterministic_trend = .1*transpose(1:200); x = zeros(200,1); for i=2:200 x(i) = .75*x(i-1) + u(i); end y = x + stochastic_trend + deterministic_trend; % Instantiates time series objects. ts0 = dseries(y,'1950Q1'); ts1 = dseries(x,'1950Q1'); % stationary component. % Apply the HP filter. ts2 = ts0.hpcycle(); % Plot the filtered time series. plot(ts1(ts2.dates).data,'-k'); % Plot of the stationary component. hold on plot(ts2.data,'--r'); % Plot of the filtered y. hold off axis tight id = get(gca,'XTick'); set(gca,'XTickLabel',strings(ts.dates(id)));
- Method: B = hptrend(A[, lambda])¶
- Method: hptrend_([lambda])¶
Extracts the trend component from adseriesA object using the Hodrick and Prescott (1997) filter and returns adseriesobject,B. Default value forlambda, the smoothing parameter, is1600.Example
% Using the same generating data process % as in the previous example: ts1 = dseries(stochastic_trend + deterministic_trend,'1950Q1'); % Apply the HP filter. ts2 = ts0.hptrend(); % Plot the filtered time series. plot(ts1.data,'-k'); % Plot of the nonstationary components. hold on plot(ts2.data,'--r'); % Plot of the estimated trend. hold off axis tight id = get(gca,'XTick'); set(gca,'XTickLabel',strings(ts0.dates(id)));
- Method: C = insert(A, B, I)¶
Inserts variables contained indseriesobjectBindseriesobjectAat positions specified by integer scalars in vectorI, returns augmenteddseriesobjectC. The integer scalars inImust take values between `` andA.length()+1and refers toA’s column numbers. ThedseriesobjectsAandBneed not be defined over the same time ranges, but it is assumed that they have common frequency.Example
>> ts0 = dseries(ones(2,4),'1950Q1',{'Sly'; 'Gobbo'; 'Sneaky'; 'Stealthy'}); >> ts1 = dseries(pi*ones(2,1),'1950Q1',{'Noddy'}); >> ts2 = ts0.insert(ts1,3) ts2 is a dseries object: | Sly | Gobbo | Noddy | Sneaky | Stealthy 1950Q1 | 1 | 1 | 3.1416 | 1 | 1 1950Q2 | 1 | 1 | 3.1416 | 1 | 1 >> ts3 = dseries([pi*ones(2,1) sqrt(pi)*ones(2,1)],'1950Q1',{'Noddy';'Tessie Bear'}); >> ts4 = ts0.insert(ts1,[3, 4]) ts4 is a dseries object: | Sly | Gobbo | Noddy | Sneaky | Tessie Bear | Stealthy 1950Q1 | 1 | 1 | 3.1416 | 1 | 1.7725 | 1 1950Q2 | 1 | 1 | 3.1416 | 1 | 1.7725 | 1
- Method: B = isempty(A)
Overloads the MATLAB/octave’sisemptyfunction. ReturnstrueifdseriesobjectAis empty.
- Method: C = isequal(A, B)
Overloads the MATLAB/octave’sisequalfunction. ReturnstrueifdseriesobjectsAandBare identical.
- Method: C = isinf(A)¶
Overloads the MATLAB/octave’sisinffunction. Returns a logical array, with element(i,j)equal totrueif and only if variablejis finite in periodA.dates(i).
- Method: C = isnan(A)¶
Overloads the MATLAB/octave’sisnanfunction. Returns a logical array, with element(i,j)equal totrueif and only if variablejisn’t NaN in periodA.dates(i).
- Method: C = isreal(A)¶
Overloads the MATLAB/octave’sisrealfunction. Returns a logical array, with element(i,j)equal totrueif and only if variablejis real in periodA.dates(i).
- Method: B = lag(A[, p])¶
- Method: lag_([p])¶
Returns lagged time series. Default value of integer scalarp, the number of lags, is1. The dseries class overloads the parentheses, so that ts.lag(p) is equivalent to ts(-p).Example
>> ts0 = dseries(transpose(1:4), '1950Q1') ts0 is a dseries object: | Variable_1 1950Q1 | 1 1950Q2 | 2 1950Q3 | 3 1950Q4 | 4 >> ts1 = ts0.lag() ts1 is a dseries object: | Variable_1 1950Q1 | NaN 1950Q2 | 1 1950Q3 | 2 1950Q4 | 3 >> ts2 = ts0.lag(2) ts2 is a dseries object: | Variable_1 1950Q1 | NaN 1950Q2 | NaN 1950Q3 | 1 1950Q4 | 2 % dseries class overloads the parenthesis % so that ts.lag(p) can be written more % compactly as ts(-p). For instance: >> ts0.lag(1) ans is a dseries object: | Variable_1 1950Q1 | NaN 1950Q2 | 1 1950Q3 | 2 1950Q4 | 3
or alternatively:
>> ts0(-1) ans is a dseries object: | Variable_1 1950Q1 | NaN 1950Q2 | 1 1950Q3 | 2 1950Q4 | 3
- Method: l = lastdate(B)¶
Retrieves the final period from thedseriesobjectB.Example
>> ts = dseries(randn(3,2),'1973Q1'); >> ts.lastdate() ans = <dates: 1973Q3>
- Method: f = lastobservedperiod(A)¶
Returns the last period in which all variables of thedseriesobjectAare fully observed (i.e., contain no NaN values).
- Method: f = lastobservedperiods(A)¶
Returns the last period without missing observations for each variable in thedseriesobjectA. The output argumentfis a structure where each field name corresponds to a variable inA, and the content of each field is a singletondateobject.
- Method: l = le(A, B)¶
- Method: l = lt(A, B)¶
Overloads thegt(<) andge(<=) binary operators. Returns a logical array.Example
>> ts = dseries(randn(3,1)) ts is a dseries object: | Variable_1 1Y | -1.2075 2Y | 0.71724 3Y | 1.6302 >> ts<1 ans = 3x1 logical array 1 1 0 >> ds = dseries(randn(3,1)) ds is a dseries object: | Variable_1 1Y | 0.48889 2Y | 1.0347 3Y | 0.72689 >> ds<ts ans = 3x1 logical array 0 0 1
- Method: B = lead(A[, p])¶
- Method: lead_([p])¶
Returns a lead time series. The default value for the integer scalarp, which represents the number of leads, is1. Similar to thelagmethod, thedseriesclass overloads the parentheses, makingts.lead(p)equivalent tots(p).Example
>> ts0 = dseries(transpose(1:4),'1950Q1'); >> ts1 = ts0.lead() ts1 is a dseries object: | Variable_1 1950Q1 | 2 1950Q2 | 3 1950Q3 | 4 1950Q4 | NaN >> ts2 = ts0(2) ts2 is a dseries object: | Variable_1 1950Q1 | 3 1950Q2 | 4 1950Q3 | NaN 1950Q4 | NaN
Remark
The overload of parentheses for
dseriesobjects simplifies the creation of newdseriesinstances by enabling the direct copying and pasting of equations defined within themodelblock. For example, if an Euler equation is specified in themodelblock,:model; ... 1/C - beta/C(1)*(exp(A(1))*K^(alpha-1)+1-delta) ; ... end;
and if variables
, ``AandKare defined asdseriesobjects, then by writing:Residuals = 1/C - beta/C(1)*(exp(A(1))*K^(alpha-1)+1-delta) ;
outside of the
modelblock, we create a newdseriesobject, calledResiduals, for the residuals of the Euler equation (the conditional expectation of the equation defined in themodelblock is zero, but the residuals are non zero).
- Method: B = lineartrend(A)¶
Returns a linear trend centered on 0, the length of the trend is given by the size ofdseriesobjectA(the number of periods).Example
>> ts = dseries(ones(3,1)); >> ts.lineartrend() ans = -1 0 1
- Method: B = log(A)¶
- Method: log_()¶
Overloads the MATLAB/Octavelogfunction fordseriesobjects.Example
>> ts0 = dseries(rand(10,1)); >> ts1 = ts0.log();
- Method: B = mdiff(A)¶
- Method: mdiff_()¶
- Method: B = mgrowth(A)¶
- Method: mgrowth_()¶
Calculates the monthly differences or growth rates of variables in thedseriesobjectA.
- Method: B = mean(A[, geometric])¶
This function overloads the MATLAB/Octavemeanfunction specifically fordseriesobjects. It calculates the mean for each variable within thedseriesobjectA. If the second argument is set totrue, the geometric mean is calculated; otherwise, the arithmetic mean is computed by default.
- Method: C = merge(A, B[, legacy])¶
Merges twodseriesobjects,AandB, into a newdseriesobjectC. The objectsAandBmust share a common frequency, although they can cover different time ranges. If a variable, such asx, exists in bothdseriesobjects, themergefunction will prioritize the definition from the second input,B, while retaining the values fromAfor any corresponding periods whereBhas NaN values. This behavior can be altered by setting the optional argumentlegacyto true, in which case the second variable will replace the first, even if it contains NaN values.Example
>> ts0 = dseries(rand(3,2),'1950Q1',{'A1';'A2'}) ts0 is a dseries object: | A1 | A2 1950Q1 | 0.96284 | 0.5363 1950Q2 | 0.25145 | 0.31866 1950Q3 | 0.34447 | 0.4355 >> ts1 = dseries(rand(3,1),'1950Q2',{'A1'}) ts1 is a dseries object: | A1 1950Q2 | 0.40161 1950Q3 | 0.81763 1950Q4 | 0.97769 >> merge(ts0,ts1) ans is a dseries object: | A1 | A2 1950Q1 | 0.96284 | 0.5363 1950Q2 | 0.40161 | 0.31866 1950Q3 | 0.81763 | 0.4355 1950Q4 | 0.97769 | NaN >> merge(ts1,ts0) ans is a dseries object: | A1 | A2 1950Q1 | 0.96284 | 0.5363 1950Q2 | 0.25145 | 0.31866 1950Q3 | 0.34447 | 0.4355 1950Q4 | 0.97769 | NaN
- Method: C = minus(A, B)
Overloads the MATLAB/Octaveminus(-) operator fordseriesobjects, allowing for element-by-element subtraction. When bothAandBaredseriesobjects, they do not need to be defined over the same time ranges. IfAandBhave \(T_A\) and \(T_B\) observations and \(N_A\) and \(N_B\) variables, then \(N_A\) must equal \(N_B\) or \(1\), and \(N_B\) must equal \(N_A\) or \(1\). If \(T_A=T_B\),isequal(A.init,B.init)returns1, and \(N_A=N_B\), then theminusoperator will compute for each pair \((t,n)\), where \(1\le t\le T_A\) and \(1\le n\le N_A\), the operationC.data(t,n)=A.data(t,n)-B.data(t,n). If \(N_B\) equals \(1\) and \(N_A>1\), the smallerdseriesobject (B) is “broadcasted” across the largerdseries(A), ensuring compatible shapes for the subtraction of the variable defined inBfrom each variable inA. IfBis a double scalar, theminusmethod will subtractBfrom all observations and variables inA. IfBis a row vector of length \(N_A\), theminusmethod will subtractB(i)from all observations of variablei, for \(i=1,...,N_A\). IfBis a column vector of length \(T_A\), theminusmethod will subtractBfrom all the variables.Example
>> ts0 = dseries(rand(3,2)); >> ts1 = ts0{'Variable_2'}; >> ts0-ts1 ans is a dseries object: | Variable_1 | Variable_2 1Y | -0.48853 | 0 2Y | -0.50535 | 0 3Y | -0.32063 | 0 >> ts1 ts1 is a dseries object: | Variable_2 1Y | 0.703 2Y | 0.75415 3Y | 0.54729 >> ts1-ts1.data(1) ans is a dseries object: | Variable_2 1Y | 0 2Y | 0.051148 3Y | -0.15572 >> ts1.data(1)-ts1 ans is a dseries object: | Variable_2 1Y | 0 2Y | -0.051148 3Y | 0.15572
- Method: C = mpower(A, B)¶
Overloads the MATLAB/Octavempower(^) operator fordseriesobjects, performing element-wise exponentiation. Given adseriesobjectAwithNvariables andTobservations, ifBis a real scalar, thenmpower(A,B)yields adseriesobjectCwhereC.data(t,n) = A.data(t,n)^B. IfBis also adseriesobject withNvariables andTobservations, thenmpower(A,B)produces adseriesobjectCsuch thatC.data(t,n) = A.data(t,n)^{C.data(t,n)}.Example
>> ts0 = dseries(transpose(1:3)); >> ts1 = ts0^2 ts1 is a dseries object: | Variable_1 1Y | 1 2Y | 4 3Y | 9 >> ts2 = ts0^ts0 ts2 is a dseries object: | Variable_1 1Y | 1 2Y | 4 3Y | 27
- Method: C = mrdivide(A, B)¶
Overloads the MATLAB/Octavemrdivide(/) operator fordseriesobjects, enabling element-wise division similar to the./operator in MATLAB/Octave. When bothAandBaredseriesobjects, they can have different time ranges. IfAcontains \(T_A\) observations and \(N_A\) variables, andBhas \(T_B\) observations and \(N_B\) variables, then \(N_A\) must equal \(N_B\) or \(1\), and vice versa. If \(T_A=T_B\) andisequal(A.init,B.init)returns1, along with \(N_A=N_B\), themrdivideoperator calculates for each pair \((t,n)\), where \(1\le t\le T_A\) and \(1\le n\le N_A\), the value ofC.data(t,n)=A.data(t,n)/B.data(t,n). If \(N_B\) equals \(1\) and \(N_A>1\), the smallerdseriesobject (B) is “broadcast” across the larger one (A) to ensure compatible shapes. In this case, themrdivideoperator divides each variable inAby the variable inB, observation by observation. IfBis a double scalar, thenmrdividewill divide all observations and variables inAbyB. IfBis a row vector of length \(N_A\), thenmrdividewill divide each observation of variableibyB(i), for \(i=1,...,N_A\). IfBis a column vector of length \(T_A\), thenmrdividewill perform an element-wise division of all variables byB.Example
>> ts0 = dseries(rand(3,2)) ts0 is a dseries object: | Variable_1 | Variable_2 1Y | 0.72918 | 0.90307 2Y | 0.93756 | 0.21819 3Y | 0.51725 | 0.87322 >> ts1 = ts0{'Variable_2'}; >> ts0/ts1 ans is a dseries object: | Variable_1 | Variable_2 1Y | 0.80745 | 1 2Y | 4.2969 | 1 3Y | 0.59235 | 1
- Method: C = mtimes(A, B)
Overloads the MATLAB/Octavemtimes(*) operator fordseriesobjects, enabling element-wise multiplication similar to the.*operator in MATLAB/Octave. When bothAandBaredseriesobjects, they can have different time ranges. IfAcontains \(T_A\) observations and \(N_A\) variables, andBhas \(T_B\) observations and \(N_B\) variables, then \(N_A\) must equal \(N_B\) or \(1\), and vice versa. If \(T_A=T_B\) andisequal(A.init,B.init)returns1, along with \(N_A=N_B\), themtimesoperator calculates for each pair \((t,n)\), where \(1\le t\le T_A\) and \(1\le n\le N_A\), the value ofC.data(t,n)=A.data(t,n)*B.data(t,n). If \(N_B\) equals \(1\) and \(N_A>1\), the smallerdseriesobject (B) is “broadcasted” across the larger one (A) to ensure compatible shapes. In this case, themtimesoperator multiply each variable inAby the variable inB, observation by observation. IfBis a double scalar, thenmtimeswill multiply all observations and variables inAbyB. IfBis a row vector of length \(N_A\), thenmtimeswill multiply each observation of variableibyB(i), for \(i=1,...,N_A\). IfBis a column vector of length \(T_A\), thenmtimeswill perform an element-wise multiplication of all variables byB.
- Method: B = nanmean(A[, geometric])¶
Overloads the MATLAB/Octavenanmeanfunction fordseriesobjects. Computes the mean of each variable in thedseriesobjectA, excluding NaN values. If the second argument istrue, the geometric mean is calculated; otherwise, the default is to report the arithmetic mean.
- Method: B = nanstd(A[, geometric])¶
Overloads the MATLAB/Octavenanstdfunction fordseriesobjects. This function calculates the standard deviation for each variable within thedseriesobjectA, while disregarding any NaN values. If the second argument is set totrue, the geometric standard deviation will be computed; the default value for the second argument isfalse.
- Method: C = ne(A, B)
Overloads the MATLAB/Octavene(not equal,~=) operator. ThedseriesobjectsAandBmust contain the same number of observations (denoted as \(T\)) and variables (denoted as \(N\)). The output is a \(T\) by \(N\) matrix consisting of zeros and ones. The element \((i,j)\) of the matrixCis equal to1if and only if observation \(i\) for variable \(j\) inAandBare not equal.Example
>> ts0 = dseries(2*ones(3,1)); >> ts1 = dseries([2; 0; 2]); >> ts0~=ts1 ans = 3x1 logical array 0 1 0
- Method: B = nobs(A)¶
Returns the number of observations indseriesobjectA.Example
>> ts0 = dseries(randn(10)); >> ts0.nobs ans = 10
- Method: B = onesidedhpcycle(A[, lambda[, init]])¶
- Method: onesidedhpcycle_([lambda[, init]])¶
Extracts the cycle component from adseriesAobject using a one-sided HP filter (implemented with a Kalman filter) and returns adseriesobject,B. The default value forlambda, the smoothing parameter, is set to1600. By default, ifinitis not provided, the initial value is determined from the first two observations.
- Method: B = onesidedhptrend(A[, lambda[, init]])¶
- Method: onesidedhptrend_(A[, lambda[, init]])¶
Extracts the trend component from adseriesAobject using a one-sided HP filter (implemented with a Kalman filter) and returns adseriesobject,B. The default value forlambda, the smoothing parameter, is set to1600. By default, ifinitis not provided, the initial value is derived from the first two observations.
- Method: h = plot(A)¶
- Method: h = plot(A, B)
- Method: h = plot(A[, ...])
- Method: h = plot(A, B[, ...])
Overloads the MATLAB/Octaveplotfunction fordseriesobjects. This function returns a MATLAB/Octave plot handle, which can be utilized to modify the properties of the plotted time series. If a singledseriesobject,A, is provided as an argument, the plot function will place the corresponding dates on the x-axis. If thisdseriesobject contains only one variable, additional arguments can be included to adjust the plot properties, similar to how one would with MATLAB/Octave’s original plot function. However, if thedseriesobjectAhas more than one variable, additional arguments cannot be passed, and modifications to the plotted time series properties must be done using the returned plot handle alongside the MATLAB/Octavesetfunction (refer to the example below). When twodseriesobjects,AandB, are passed as input arguments, the plot function will display the variables inAagainst those inB(it is essential that both objects contain the same number of variables; otherwise, an error will occur). Once more, if each object includes only one variable, additional arguments can be utilized to alter the plotted time series properties; otherwise, the MATLAB/Octavesetcommand must be employed.Example
Define a
dseriesobject with two variables (named by defaultVariable_1andVariable_2):>> ts = dseries(randn(100,2),'1950Q1');
The following command will plot the first variable in
ts:>> plot(ts{'Variable_1'},'-k','linewidth',2);
The next command will draw all the variables in
tson the same figure:>> h = plot(ts);
If one wants to modify the properties of the plotted time series (line style, colours, …), the set function can be used (see MATLAB’s documentation):
>> set(h(1),'-k','linewidth',2); >> set(h(2),'--r');
The following command will plot
Variable_1againstexp(Variable_1):>> plot(ts{'Variable_1'},ts{'Variable_1'}.exp(),'ok');
Again, the properties can also be modified using the returned plot handle and the
setfunction:>> h = plot(ts, ts.exp()); >> set(h(1),'ok'); >> set(h(2),'+r');
- Method: C = plus(A, B)
Overloads the MATLAB/Octaveplus(+) operator fordseriesobjects, allowing for element-wise addition. When bothAandBaredseriesobjects, they do not need to be defined over the same time ranges. IfAandBaredseriesobjects with \(T_A\) and \(T_B\) observations and \(N_A\) and \(N_B\) variables, then \(N_A\) must be equal to \(N_B\) or \(1\) and \(N_B\) must be equal to \(N_A\) or \(1\). If \(T_A=T_B\),isequal(A.init,B.init)returns1and \(N_A=N_B\), then theplusoperator will compute for each pair \((t,n)\), with \(1\le t\le T_A\) and \(1\le n\le N_A\),C.data(t,n)=A.data(t,n)+B.data(t,n). If \(N_B\) is equal to \(1\) and \(N_A>1\), the smallerdseriesobject (B) is “broadcasted” across the largerdseries(A) to ensure compatible shapes, the plus operator will add the variable defined inBto each variable inA. IfBis a double scalar, then the methodpluswill addBto all the observations/variables inA. IfBis a row vector of length \(N_A\), then theplusmethod will addB(i)to all the observations of variablei, for \(i=1,\ldots,N_A\). IfBis a column vector of length \(T_A\), then theplusmethod will addBto all the variables.
- Method: C = pop(A[, B])
- Method: pop_([B])
Removes the variableBfrom thedseriesobjectA. By default, if the second argument is not specified, the last variable is removed.Example
>> ts0 = dseries(ones(3,3)); >> ts1 = ts0.pop('Variable_2'); ts1 is a dseries object: | Variable_1 | Variable_3 1Y | 1 | 1 2Y | 1 | 1 3Y | 1 | 1
- Method: A = projection(A, info, periods)¶
Projects variables in the dseries objectA. Theinfovariable is a \(n \times 3\) cell array, where each row contains essential information for projecting a variable. The first column holds the variable name (as a character array), while the second column indicates the projection method used (also a character array). The possible values for this column are'Trend','Constant', and'AR'. The third column provides quantitative details related to the projection: if the second column is'Trend', the third column specifies the growth factor of the (exponential) trend; if'Constant', it indicates the variable’s level; and if'AR', it denotes the autoregressive parameter. Variables can be projected using an AR(p) model if the third column contains a 1×p vector of doubles. Note that the stationarity of the AR(p) model is not tested. For constant projections, one can use either ‘Trend’ with a growth factor of 1 or ‘AR’ with an autoregressive parameter of one (indicating a random walk). This projection routine solely addresses exponential trends.Example
>> data = ones(10,4); >> ts = dseries(data, '1990Q1', {'A1', 'A2', 'A3', 'A4'}); >> info = {'A1', 'Trend', 1.2; 'A2', 'Constant', 0.0; 'A3', 'AR', .5; 'A4', 'AR', [.4, -.2]}; >> ts.projection(info, 10);
- Method: B = qdiff(A)¶
- Method: B = qgrowth(A)¶
- Method: qdiff_()¶
- Method: qgrowth_()¶
Computes quarterly differences or growth rates.Example
>> ts0 = dseries(transpose(1:4),'1950Q1'); >> ts1 = ts0.qdiff() ts1 is a dseries object: | Variable_1 1950Q1 | NaN 1950Q2 | 1 1950Q3 | 1 1950Q4 | 1 >> ts0 = dseries(transpose(1:6),'1950M1'); >> ts1 = ts0.qdiff() ts1 is a dseries object: | Variable_1 1950M1 | NaN 1950M2 | NaN 1950M3 | NaN 1950M4 | 3 1950M5 | 3 1950M6 | 3
- Method: C = remove(A, B)
- Method: remove_(B)
IfBis a row character array representing the name of a variable, these methods serve as aliases for thepopandpop_methods that accept two arguments. They remove the variableBfrom thedseriesobjectA. To remove multiple variables, you can pass a cell array of row character arrays forB.Example
>> ts0 = dseries(ones(3,3)); >> ts1 = ts0.remove('Variable_2'); ts1 is a dseries object: | Variable_1 | Variable_3 1Y | 1 | 1 2Y | 1 | 1 3Y | 1 | 1
A more concise syntax is available:
remove(ts, 'Variable_2'), which is equivalent tots{'Variable_2'} = [](where[]can be substituted with any empty object). This alternative syntax proves useful when removing multiple variables. For example:ts{'Variable_@2,3,4@'} = [];
will remove
Variable_2,Variable_3andVariable_4fromdseriesobjectts(if these variables exist). Regular expressions cannot be used but implicit loops can.
- Method: B = rename(A, oldname, newname)¶
- Method: rename_(oldname, newname)¶
Renames the variableoldnametonewnamein thedseriesobjectA. This function returns adseriesobject. If multiple variables need to be renamed, you can provide cell arrays of row character arrays as the second and third arguments.Example
>> ts0 = dseries(ones(2,2)); >> ts1 = ts0.rename('Variable_1','Stinkly') ts1 is a dseries object: | Stinkly | Variable_2 1Y | 1 | 1 2Y | 1 | 1
- Method: C = rename(A, newname)¶
- Method: rename_(newname)
Replace the names inAwith those specified in the cell of row character arraysnewname. The cellnewnamemust contain the same number of elements as there are variables in thedseriesobjectA.Example
>> ts0 = dseries(ones(2,3)); >> ts1 = ts0.rename({'TinkyWinky','Dipsy','LaaLaa'}) ts1 is a dseries object: | TinkyWinky | Dipsy | LaaLaa 1Y | 1 | 1 | 1 2Y | 1 | 1 | 1
- Method: A = resetops(A, ops)¶
Redefineopsmember.
- Method: A = resetags(A, ops)¶
Redefinetagsmember.
- Method: B = round(A[, n])¶
- Method: round_([n])¶
Rounds each value to the nearest decimal or integer. The parameternspecifies the precision (number of decimal places), with a default value of 0, indicating that the method will round to the nearest integer by default.Example
>> ts = dseries(pi) ts is a dseries object: | Variable_1 1Y | 3.1416 >> ts.round_(); >> ts ts is a dseries object: | Variable_1 1Y | 3
- Method: save(A, basename[, format])¶
Overloads the MATLAB/Octavesavefunction to save thedseriesobjectAto disk. The available formats includemat(default, MATLAB binary data file),m(MATLAB/Octave script), andcsv(comma-separated values file). The base name of the file, excluding the extension, is specified bybasename.Example
>> ts0 = dseries(ones(2,2)); >> ts0.save('ts0', 'csv');
The last command will create a file ts0.csv with the following content:
,Variable_1,Variable_2 1Y, 1, 1 2Y, 1, 1
To create a MATLAB/Octave script, the following command:
>> ts0.save('ts0','m');
will produce a file ts0.m with the following content:
% File created on 14-Nov-2013 12:08:52. FREQ__ = 1; INIT__ = ' 1Y'; NAMES__ = {'Variable_1'; 'Variable_2'}; TEX__ = {'Variable_{1}'; 'Variable_{2}'}; OPS__ = {}; TAGS__ = struct(); Variable_1 = [ 1 1]; Variable_2 = [ 1 1];
The generated (
csv,m, ormat) files can be loaded when instantiating adseriesobject as explained above.
- Method: B = set_names(A, s1, s2, ...)¶
Renames the variables in thedseriesobjectAand returns a newdseriesobjectBwith the updated namess1,s2, and so forth. The number of input arguments following the first one (thedseriesobjectA) must be equal toA.vobs(the total number of variables inA). The names1will correspond to the first variable inB,s2to the second variable inB, and this pattern continues for the remaining variables.Example
>> ts0 = dseries(ones(1,3)); >> ts1 = ts0.set_names('Barbibul',[],'Barbouille') ts1 is a dseries object: | Barbibul | Variable_2 | Barbouille 1Y | 1 | 1 | 1
- Method: [T, N ] = size(A[, dim])¶
Overloads the MATLAB/Octave
sizefunction to return the number of observations in thedseriesobjectA(i.e.,A.nobs) as well as the number of variables (i.e.,A.vobs). If a second input argument is provided, thesizefunction will return the number of observations whendim=1or the number of variables whendim=2. An error will be issued for any other values ofdim.Example
>> ts0 = dseries(ones(1,3)); >> ts0.size() ans = 1 3
- Method: B = std(A[, geometric])¶
Overloads the MATLAB/Octavestdfunction fordseriesobjects. This function returns the standard deviation of each variable within thedseriesobjectA. If the second argument is set totrue, the geometric standard deviation is calculated (the default value for the second argument isfalse).
- Method: B = subsample(A, d1, d2)¶
Returns a subsample for the period betweend1andd2. While you can achieve the same result by indexing adseriesobject with adatesobject, thesubsamplemethod offers a more straightforward approach for programmatic use.Example
>> o = dseries(transpose(1:5)); >> o.subsample(dates('2y'),dates('4y')) ans is a dseries object: | Variable_1 2Y | 2 3Y | 3 4Y | 4
- Method: A = tag(A, a[, b, c])¶
Adds a tag to a variable indseriesobjectA.Example
>> ts = dseries(randn(10, 3)); >> tag(ts, 'type'); % Define a tag name. >> tag(ts, 'type', 'Variable_1', 'Stock'); >> tag(ts, 'type', 'Variable_2', 'Flow'); >> tag(ts, 'type', 'Variable_3', 'Stock');
- Method: B = tex_rename(A, name, newtexname)¶
- Method: B = tex_rename(A, newtexname)
- Method: tex_rename_(name, newtexname)¶
- Method: tex_rename_(newtexname)
Updates the TeX name of the variablenametonewtexnamein thedseriesobjectA. Returns an updateddseriesobject.With just two arguments,
Aandnewtexname, this function redefines the TeX names of the entries inAto those specified innewtexname. Thenewtexnameargument must be a cell row character arrays containing the same number of entries as there are variables inA.
- Method: B = uminus(A)
Overloads theuminusoperator (-, unary minus) for thedseriesobject.Example
>> ts0 = dseries(1) ts0 is a dseries object: | Variable_1 1Y | 1 >> ts1 = -ts0 ts1 is a dseries object: | Variable_1 1Y | -1
- Method: D = vertcat(A, B[, ...])
Overloads thevertcatmethod in MATLAB/Octave fordseriesobjects. This method facilitates the appending of additional observations to adseriesobject. It returns a newdseriesobject,D, which contains the variables from the inputdseriesobjects. All input arguments must bedseriesobjects that share the same variables but are defined over different time ranges.Example
>> ts0 = dseries(rand(2,2),'1950Q1',{'nifnif';'noufnouf'}); >> ts1 = dseries(rand(2,2),'1950Q3',{'nifnif';'noufnouf'}); >> ts2 = [ts0; ts1] ts2 is a dseries object: | nifnif | noufnouf 1950Q1 | 0.82558 | 0.31852 1950Q2 | 0.78996 | 0.53406 1950Q3 | 0.089951 | 0.13629 1950Q4 | 0.11171 | 0.67865
- Method: B = vobs(A)¶
Returns the count of variables in thedseriesobjectA.Example
>> ts0 = dseries(randn(10,2)); >> ts0.vobs ans = 2
6.3. X-13 ARIMA-SEATS interface¶
- Dynare class: x13¶
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. Thex13class has 22 members:- Members:
y –
dseriesobject with a single variable.x –
dseriesobject with an arbitrary number of variables (to be used in the REGRESSION block).arima – structure containing the options of the ARIMA model command.
automdl – structure containing the options of the ARIMA model selection command.
regression – structure containing the options of the Regression command.
estimate – structure containing the options of the estimation command.
transform – structure containing the options of the transform command.
outlier – structure containing the options of the outlier command.
forecast – structure containing the options of the forecast command.
check – structure containing the options of the check command.
x11 – structure containing the options of the X11 command.
force – structure containing the options of the force command.
history – structure containing the options of the history command.
metadata – structure containing the options of the metadata command.
identify – structure containing the options of the identify command.
pickmdl – structure containing the options of the pickmdl command.
seats – structure containing the options of the seats command.
slidingspans – structure containing the options of the slidingspans command.
spectrum – structure containing the options of the spectrum command.
x11regression – structure containing the options of the x11Regression command.
results – structure containing the results returned by x13.
commands – cell array containing the list of commands.
All these members are private. The following constructors are available:
- Constructor: x13(y)
Instantiates anx13object with dseries objecty. Thedseriesobject passed as an argument must contain only one variable, the one we need to pass to X-13.
- Constructor: x13(y, x)
Instantiates anx13object with dseries objectsyandx. The firstdseriesobject passed as an argument must contain only one variable, the seconddseriesobject contains the exogenous variables used by some of the X-13 commands. Both objects must be defined on the same time span.
The following methods allow to set sequence of X-13 commands, write an .spc file, and run the X-13 binary:
- Method: A = arima(A, key, value[, key, value[, [...]]])¶
Interface to the
arimacommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = automdl(A, key, value[, key, value[, [...]]])¶
Interface to the
automdlcommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = regression(A, key, value[, key, value[, [...]]])¶
Interface to the
regressioncommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = estimate(A, key, value[, key, value[, [...]]])¶
Interface to the
estimatecommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = transform(A, key, value[, key, value[, [...]]])¶
Interface to the
transformcommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs. For example, the key/value pairfunction,loginstructs the use of a multiplicative instead of an additive seasonal pattern, whilefunction,autotriggers an automatic selection between the two based on their fit.
- Method: A = outlier(A, key, value[, key, value[, [...]]])¶
Interface to the
outliercommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = forecast(A, key, value[, key, value[, [...]]])¶
Interface to the
forecastcommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = check(A, key, value[, key, value[, [...]]])¶
Interface to the
checkcommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = x11(A, key, value[, key, value[, [...]]])¶
Interface to the
x11command, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = force(A, key, value[, key, value[, [...]]])¶
Interface to the
forcecommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = history(A, key, value[, key, value[, [...]]])¶
Interface to the
historycommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = metadata(A, key, value[, key, value[, [...]]])¶
Interface to the
metadatacommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = identify(A, key, value[, key, value[, [...]]])¶
Interface to the
identifycommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = pickmdl(A, key, value[, key, value[, [...]]])¶
Interface to the
pickmdlcommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = seats(A, key, value[, key, value[, [...]]])¶
Interface to the
seatscommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = slidingspans(A, key, value[, key, value[, [...]]])¶
Interface to the
slidingspanscommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = spectrum(A, key, value[, key, value[, [...]]])¶
Interface to the
spectrumcommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: A = x11regression(A, key, value[, key, value[, [...]]])¶
Interface to the
x11regressioncommand, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: print(A[, basefilename])¶
Prints an
.spcfile with all the X-13 commands. The optional second argument is a row char array specifying the name (without extension) of the file.
- Method: run(A)¶
Calls the X-13 binary and run the previously defined commands. All the results are stored in the structure
A.results. When it makes sense these results are saved indseriesobjects (e.g. for forecasts or filtered variables).
- Method: clean(A)¶
Removes the temporary files created by an x13 run that store the intermediate results. This method allows keeping the main folder clean but will also delete potentially important debugging information.
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 subsequento.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. Theo.automdl('savelog','all')automatically selects a fitting ARIMA model and saves all relevant output to the .log-file. Theo.x11('save','(d11, d10)')instructsx11to save both the final seasonally adjusted seriesd11and the final seasonal factord10intodserieswith the respective names in the output structureo.results.o.clean()removes the temporary files created byo.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.
6.4. Miscellaneous¶
6.4.1. Time aggregation¶
A set of functions allows to convert time series to lower frequencies:
dseries2Mconverts daily time series object to monthly time series object.
dseries2Qconverts daily or monthly time series object to quarterly time series object.
dseries2Sconverts daily, monthly, or quarterly time series object to bi-annual time series object.
dseries2Yconverts daily, monthly, quarterly, or bi-annual time series object to annual time series object.
All these routines have two mandatory input arguments: the first one is adseriesobject, 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
6.4.2. Create time series with a univariate model¶
It is possible to expand adseriesobject recursively with thefromcommand. For instance to create adseriesobject 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.79661The expression following the
dokeyword 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. Thefromcommand must be followed by a range, which is separated from the (recursive) expression to be evaluated by thedocommand.