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
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
thenb = 1951Q2
andb = a + 5
are identical.
plus unary operator (+)
Increments a date by one period.
+1950Q1
is identical to1950Q2
,++++1950Q1
is 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 secmond date (e.g.
1951Q2-1950Q1
is equal to5
). If the second argument is an integerX
, subtractsX
periods from the date (e.g.1951Q2-2
is equal to1950Q4
).
minus unary operator (-)
Subtracts one period to a date.
-1950Q1
is identical to1949Q4
. The unary minus operator is the reciprocal of the unary plus operator,+-1950Q1
is identical to1950Q1
.
colon operator (:)
Can be used to create a range of dates. For instance,
r = 1950Q1:1951Q1
creates adates
object with five elements:1950Q1, 1950Q2, 1950Q3, 1950Q4
and1951Q1
. 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 adates
object with three elements:1950Q1
,1950Q3
and1951Q1
.
horzcat operator ([,])
Concatenates dates objects without removing repetitions. For instance
[1950Q1, 1950Q2]
is adates
object with two elements (1950Q1
and1950Q2
).
vertcat operator ([;])
Same as
horzcat
operator.
eq operator (equal, ==)
Tests if two
dates
objects are equal.+1950Q1==1950Q2
returnstrue
,1950Q1==1950Q2
returnsfalse
. If the compared objects have bothn>1
elements, theeq
operator returns a column vector,n
by1
, of logicals.
ne operator (not equal, ~=)
Tests if two
dates
objects are not equal.+1950Q1~=
returnsfalse
while1950Q1~=1950Q2
returnstrue
. If the compared objects both haven>1
elements, thene
operator returns ann
by1
column vector of logicals.
lt operator (less than, <)
Tests if a
dates
object preceeds anotherdates
object. For instance,1950Q1<1950Q3
returnstrue
. If the compared objects have bothn>1
elements, thelt
operator returns a column vector,n
by1
, of logicals.
gt operator (greater than, >)
Tests if a
dates
object follows anotherdates
object. For instance,1950Q1>1950Q3
returnsfalse
. If the compared objects have bothn>1
elements, thegt
operator returns a column vector,n
by1
, of logicals.
le operator (less or equal, <=)
Tests if a
dates
object preceeds anotherdates
object or is equal to this object. For instance,1950Q1<=1950Q3
returnstrue
. If the compared objects have bothn>1
elements, thele
operator returns a column vector,n
by1
, of logicals.
ge operator (greater or equal, >=)
Tests if a
dates
object follows anotherdates
object or is equal to this object. For instance,1950Q1>=1950Q3
returnsfalse
. If the compared objects have bothn>1
elements, thege
operator returns a column vector,n
by1
, 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*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:- Constructor: dates()
- Constructor: dates(FREQ)
Returns an emptydates
object with a given frequency (if the constructor is called with one input argument).FREQ
is 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 thatFREQ
is 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 thedates
class. For instance, if one only works with quarterly dates, objectqq
can be created as:qq = dates('Q')
and a
dates
object holding the date2009Q2
:d0 = qq(2009,2);
which is much simpler if
dates
objects have to be defined programmatically. For daily dates, we would instantiate an empty daily dates object as:dd = dates('D')
and a
dates
object holding the date2020-12-31
:d1 = dd(2020,12,31);
- Constructor: dates(STRING)
- Constructor: dates(STRING, STRING, ...)
Returns adates
object 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 routineisdate
can 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 resultingdates
object 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 thedates
objectDATES
passed as input arguments. If more than one argument is provided, they should all bedates
objects. The number of elements in the instantiateddates
object is equal to the sum of the elements in thedates
passed as arguments to the constructor.
- Constructor: dates(FREQ, YEAR, SUBPERIOD[, S])
whereFREQ
is a single character (’Y’, ’A’, ’S’, ’H’, ’Q’, ’M’, ’D’) or integer (1, 2, 4, 12, or 365) specifying the frequency,YEAR
andSUBPERIOD
andS
aren*1
vectors of integers. Returns adates
object withn
elements. The last argument,S
, is only to be used for daily frequency. IfFREQ
is equal to'Y'
,'A'
or1
, the third argument is not needed (becauseSUBPERIOD
is 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 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 objectX
we write:>> X = 2; >> Y = X.multiplybytwo(); >> X 2 >> Y 4
or equivalently:
>> Y = multiplybytwo(X);
the object
X
is left unchanged, and the objectY
is 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: C = append_(A, B)¶
Appendsdates
objectB
, or a string that can be interpreted as a date, to thedates
objectA
. IfB
is adates
object 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/Octavechar
function. Converts adates
object 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 aredates
objects. The optional incrementi
is a scalar integer (default value isi=1
). This method returns adates
object 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 adates
object.
- Method: disp(A)¶
Overloads the MATLAB/Octave disp function fordates
object.
- Method: display(A)¶
Overloads the MATLAB/Octave display function fordates
object.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/Octavedouble
function.A
is adates
object. The method returns a floating point representation of adates
object, 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.dates
objectsA
andB
must have the same number of elements (say,n
). The returned argument is an
by1
vector of logicals. The i-th element ofC
is equal totrue
if 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.dates
objectsA
andB
must have the same number of elements (say,n
). The returned argument is an
by1
vector of logicals. The i-th element ofC
is equal totrue
if 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.dates
objectsA
andB
must have the same number of elements (say,n
). The returned argument is an
by1
vector of logicals. The i-th element ofC
is equal to1
if 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/Octavehorzcat
operator. All the input arguments must bedates
objects. The returned argument is adates
object 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/Octaveintersect
function. All the input arguments must bedates
objects. The returned argument is adates
object gathering all the common dates given in the input arguments. IfA
andB
are disjointdates
objects, the function returns an emptydates
object. Returned dates indates
objectC
are 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/Octaveisempty
function.Example
>> A = dates('1950Q1'); >> A.isempty() ans = logical 0 >> B = dates(); >> B.isempty() ans = logical 1
- Method: C = isequal(A, B)¶
Overloads the MATLAB/Octaveisequal
function.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.dates
objectsA
andB
must have the same number of elements (say,n
). The returned argument is an
by1
vector of logicals. The i-th element ofC
is equal totrue
if 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/Octavelength
function. Returns the number of elements in adates
object.Example
>> A = dates('1950Q1'):dates(2000Q3); >> A.length() ans = 203
- Method: C = lt(A, B)¶
Overloads the MATLAB/Octavelt
(less than,<
) operator.dates
objectsA
andB
must have the same number of elements (say,n
). The returned argument is an
by1
vector of logicals. The i-th element ofC
is equal totrue
if 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/Octavemax
function. All input arguments must bedates
objects. The function returns a single elementdates
object 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/Octavemin
function. All input arguments must bedates
objects. The function returns a single elementdates
object 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/Octaveminus
operator (-
). If both input arguments aredates
objects, then number of periods betweenA
andB
is returned (so thatA+C=B
). IfB
is a vector of integers, the minus operator shifts thedates
object byB
periods 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/Octavemtimes
operator (*
).A
andB
are respectively expected to be adates
object and a scalar integer. Returnsdates
objectA
replicatedB
times.Example
>> d = dates('1950Q1'); >> d*2 ans = <dates: 1950Q1, 1950Q1>
- Method: C = ne(A, B)¶
Overloads the MATLAB/Octavene
(not equal,~=
) operator.dates
objectsA
andB
must have the same number of elements (say,n
) or one of the inputs must be a single elementdates
object. The returned argument is an
by1
vector of logicals. The i-th element ofC
is equal totrue
if 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/Octaveplus
operator (+
). If both input arguments aredates
objects, then the method combinesA
andB
without removing repetitions. IfB
is a vector of integers, theplus
operator shifts thedates
object byB
periods 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: C = pop_(A)¶
- Method: C = pop_(A, B)
Pop method fordates
class. If only one input is provided, the method removes the last element of adates
object. If a second input argument is provided, a scalar integer between1
andA.length()
, the method removes element numberB
fromdates
objectA
.Example
>> d = dates('1950Q1','1950Q2'); >> d.pop() ans = <dates: 1950Q1> >> d.pop_(1) ans = <dates: 1950Q2>
- Method: C = remove(A, B)¶
- Method: C = remove_(A, B)¶
Remove method fordates
class. Both inputs have to bedates
objects, removes dates inB
fromA
.Example
>> d = dates('1950Q1','1950Q2'); >> d.remove(dates('1950Q2')) ans = <dates: 1950Q1>
- Method: C = setdiff(A, B)¶
Overloads the MATLAB/Octavesetdiff
function. All the input arguments must bedates
objects. The returned argument is adates
object all dates present inA
but not inB
. IfA
andB
are disjointdates
objects, the function returnsA
. Returned dates indates
objectC
are 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: B = sort_(A)¶
Sort method fordates
objects. Returns adates
object with elements sorted by increasing order.Example
>> dd = dates('1945Q3','1938Q4','1789Q3'); >> dd.sort() ans = <dates: 1789Q3, 1938Q4, 1945Q3>
- Method: B = strings(A)¶
Converts adates
object 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 adates
object 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/Octaveunion
function. Returns adates
object with elements sorted by increasing order (repetitions are removed, to keep the repetitions use thehorzcat
orplus
operators).Example
>> d1 = dates('1945Q3','1973Q1','1938Q4'); >> d2 = dates('1973Q1','1976Q1'); >> union(d1,d2) ans = <dates: 1938Q4, 1945Q3, 1973Q1, 1976Q1>
- Method: B = unique(A)¶
- Method: B = unique_(A)¶
Overloads the MATLAB/Octaveunique
function. Returns adates
object 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 adates
object 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/Octavehorzcat
operator. All the input arguments must bedates
objects. The returned argument is adates
object 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/Octavedseries
class handles time series data. As any MATLAB/Octave statements, this class can be used in a Dynare’s mod file. Adseries
object has six members:- Members:
name – A
vobs*1
cell of strings or avobs*p
character array, the names of the variables.tex – A
vobs*1
cell of strings or avobs*p
character array, the tex names of the variables.dates (
dates
) – An object withnobs
elements, the dates of the sample.data (
double
) – Anobs
byvobs
array, the data.ops – The history of operations on the variables.
tags – The user-defined tags on the variables.
data
,name
,tex
, andops
are private members. The following constructors are available:- Constructor: dseries()
- Constructor: dseries(INITIAL_DATE)
Instantiates an emptydseries
object with, if defined, an initial date given by the single elementdates
object INITIAL_DATE.
- Constructor: dseries(FILENAME[, INITIAL_DATE])
Instantiates and populates adseries
object with a data file specified by FILENAME, a string passed as input. Valid file types are.m
,.mat
,.csv
and.xls/.xlsx
(Octave only supports.xlsx
files and the io package from Octave-Forge must be installed). The extension of the file should be explicitly provided.A typical
.m
file 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
.mat
file 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 adates
object or a string which could be used to instantiate the samedates
object. IfINIT__
is not provided in the.mat
or.m
file, the initial is by default set equal todates('1Y')
. If a second input argument is passed to the constructor,dates
object 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
.xlsx
file 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 adates
object representing the period of the first observation or a string which would be used to instantiate adates
object. 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 columni
of 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 columni
of DATA_MATRIX isVariable\_i
. If the optional second input argument is a range of dates,dates
object 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
dseries
object given the MATLAB Table provided as the sole argument. It is assumed that the first column of the table contains the dates of thedseries
and the first row contains the names. This feature is not available under Octave or MATLAB R2013a or earlier.Example
Various ways to create a
dseries
object: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
dseries
object using the overloaded parenthesis operator. Ifds
is adseries
object with \(T\) observations andd
is adates
object with \(S<T\) elements, such that \(\min(d)\) is not smaller than the date associated to the first observation inds
and \(\max(d)\) is not greater than the date associated to the last observation, thends(d)
instantiates a newdseries
object 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_(B)¶
Overloads theabs()
function fordseries
objects. Returns the absolute value of the variables in dseriesobject
B
.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
- Method: [A, B] = align(A, B)¶
- Method: align_(A, B)¶
If
dseries
objectsA
andB
are defined on different time ranges, this function extendsA
and/orB
with NaNs so that they are defined on the same time range. Note that bothdseries
objects 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
- Method: C = backcast(A, B[, diff])¶
- Method: backcast_(A, B[, diff])¶
Backcasts
dseries
objectA
withdseries
object B’s growth rates (except if the last optional argument,diff
, is true in which case first differences are used). Bothdseries
objects must have the same frequency.
- Method: B = baxter_king_filter(A, hf, lf, K)¶
- Method: baxter_king_filter_(A, hf, lf, K)¶
Implementation of the Baxter and King (1999) band pass filter fordseries
objects. 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 forhf
is6
, forlf
is32
, and forK
is12
.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_(A[, geometric])¶
Centers variables indseries
objectA
around their arithmetic means, except if the optional argumentgeometric
is set equal totrue
in which case all the variables are divided by their geometric means.
- Method: C = chain(A, B)¶
- Method: chain_(A, B)¶
Merge twodseries
objects along the time dimension. The two objects must have the same number of observed variables, and the initial date inB
must not be posterior to the last date inA
. The returneddseries
object,C
, is built by extendingA
with 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
- Method: [error_flag, message ] = check(A)¶
Sanity check ofdseries
objectA
. Returns1
if there is an error,0
otherwise. 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
, objectB
will not be affected. Note that ifA
is assigned toC
,C = A
, then any in place modification method applied toA
will 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_(A[, d[, v]])¶
Overloads the MATLAB/Octavecumprod
function fordseries
objects. The cumulated product cannot be computed if the variables indseries
objectA
have NaNs. If adates
objectd
is provided as a second argument, then the method computes the cumulated product with the additional constraint that the variables in thedseries
objectB
are equal to one in periodd
. If a single-observationdseries
objectv
is provided as a third argument, the cumulated product inB
is normalized such thatB(d)
matchesv
(dseries
objectsA
andv
must 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(A[, d[, v]])¶
Overloads the MATLAB/Octavecumsum
function fordseries
objects. The cumulated sum cannot be computed if the variables indseries
objectA
have NaNs. If adates
objectd
is provided as a second argument, then the method computes the cumulated sum with the additional constraint that the variables in thedseries
objectB
are zero in periodd
. If a single observationdseries
objectv
is provided as a third argument, the cumulated sum inB
is such thatB(d)
matchesv
(dseries
objectsA
andv
must 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_(A, m)¶
Detrendsdseries
objectA
with a fitted polynomial of orderm
. Note that each variable is detrended with a different polynomial.
- Method: disp(A)
Overloads the MATLAB/Octave disp function fordseries
object.
- Method: display(A)
Overloads the MATLAB/Octave display function fordseries
object.display
is 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 thedseries
object is defined over a too large time span, only the first and last periods will be printed. If thedseries
object contains too many variables, only the first and last variables will be printed. If all the periods and variables are required, thedisp
method should be used instead.
- Method: C = eq(A, B)
Overloads the MATLAB/Octaveeq
(equal,==
) operator.dseries
objectsA
andB
must 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)\) ofC
is equal totrue
if and only if observation \(i\) for variable \(j\) inA
andB
are 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 variablevarname
exists indseries
objectA
. Returnstrue
iff 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/Octaveexp
function fordseries
objects.Example
>> ts0 = dseries(rand(10,1)); >> ts1 = ts0.exp();
- Method: C = extract(A, B[, ...])¶
Extracts some variables from adseries
objectA
and returns adseries
objectC
. The input arguments followingA
are strings representing the variables to be selected in the newdseries
objectC
. To simplify the creation of sub-objects, thedseries
class 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: f = firstdate(A)¶
Returns the first period indseries
objectA
.
- Method: f = firstobservedperiod(A)¶
Returns the first period where all the variables indseries
objectA
are 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 indseries
objectB
.Example
>> ts = dseries(randn(3,2),'1973Q1'); >> ts.frequency ans = 4
- Method: D = horzcat(A, B[, ...])
Overloads thehorzcat
MATLAB/Octave’s method fordseries
objects. Returns adseries
objectD
containing the variables indseries
objects 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 thedseries
objects 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_(A[, lambda])¶
Extracts the cycle component from adseries
A
object using the Hodrick and Prescott (1997) filter and returns adseries
object,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_(A[, lambda])¶
Extracts the trend component from adseries
A object using the Hodrick and Prescott (1997) filter and returns adseries
object,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 indseries
objectB
indseries
objectA
at positions specified by integer scalars in vectorI
, returns augmenteddseries
objectC
. The integer scalars inI
must take values between `` andA.length()+1
and refers toA
’s column numbers. Thedseries
objectsA
andB
need 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’sisempty
function. Returnstrue
ifdseries
objectA
is empty.
- Method: C = isequal(A, B)
Overloads the MATLAB/octave’sisequal
function. Returnstrue
ifdseries
objectsA
andB
are identical.
- Method: C = isinf(A)¶
Overloads the MATLAB/octave’sisinf
function. Returns a logical array, with element(i,j)
equal totrue
if and only if variablej
is finite in periodA.dates(i)
.
- Method: C = isnan(A)¶
Overloads the MATLAB/octave’sisnan
function. Returns a logical array, with element(i,j)
equal totrue
if and only if variablej
isn’t NaN in periodA.dates(i)
.
- Method: C = isreal(A)¶
Overloads the MATLAB/octave’sisreal
function. Returns a logical array, with element(i,j)
equal totrue
if and only if variablej
is real in periodA.dates(i)
.
- Method: B = lag(A[, p])¶
- Method: lag_(A[, p])¶
Returns lagged time series. Default value of integer scalarp
, the number of lags, is1
.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)¶
Returns the last period indseries
objectB
.Example
>> ts = dseries(randn(3,2),'1973Q1'); >> ts.lastdate() ans = <dates: 1973Q3>
- Method: f = lastobservedperiod(A)¶
Returns the last period where all the variables indseries
objectA
are observed (non NaN).
- Method: f = lastobservedperiods(A)¶
Returns for each variable the last period without missing observations indseries
objectA
. Output argumentf
is a structure, each field name is the name of a variable inA
, each field content is a singletondate
object.
- Method: B = lead(A[, p])¶
- Method: lead_(A[, p])¶
Returns lead time series. Default value of integer scalarp
, the number of leads, is1
. As in thelag
method, thedseries
class overloads the parenthesis so thatts.lead(p)
is 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 overloading of the parenthesis for
dseries
objects, allows to easily create newdseries
objects by copying/pasting equations declared in themodel
block. For instance, if an Euler equation is defined in themodel
block:model; ... 1/C - beta/C(1)*(exp(A(1))*K^(alpha-1)+1-delta) ; ... end;
and if variables
, ``A
andK
are defined asdseries
objects, then by writing:Residuals = 1/C - beta/C(1)*(exp(A(1))*K^(alpha-1)+1-delta) ;
outside of the
model
block, we create a newdseries
object, calledResiduals
, for the residuals of the Euler equation (the conditional expectation of the equation defined in themodel
block 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 ofdseries
objectA
(the number of periods).Example
>> ts = dseries(ones(3,1)); >> ts.lineartrend() ans = -1 0 1
- Method: B = log(A)¶
- Method: log_(A)¶
Overloads the MATLAB/Octavelog
function fordseries
objects.Example
>> ts0 = dseries(rand(10,1)); >> ts1 = ts0.log();
- Method: B = mdiff(A)¶
- Method: mdiff_(A)¶
- Method: B = mgrowth(A)¶
- Method: mgrowth_(A)¶
Computes monthly differences or growth rates of variables indseries
objectA
.
- Method: B = mean(A[, geometric])¶
Overloads the MATLAB/Octavemean
function fordseries
objects. Returns the mean of each variable indseries
objectA
. If the second argument istrue
the geometric mean is computed, otherwise (default) the arithmetic mean is reported.
- Method: C = merge(A, B[, legacy])¶
Merges twodseries
objectsA
andB
indseries
objectC
. ObjectsA
andB
need to have common frequency but can be defined on different time ranges. If a variable, sayx
, is defined both indseries
objectsA
andB
, then themerge
will select the variablex
as defined in the second input argument,B
, except for the NaN elements inB
if corresponding elements inA
(ie same periods) are well defined numbers. This behaviour can be changed by setting the optional argumentlegacy
equal to true, in which case the second variable overwrites the first one even if the second variable has NaNs.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 fordseries
objects, element by element subtraction. If bothA
andB
aredseries
objects, they do not need to be defined over the same time ranges. IfA
andB
aredseries
objects 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)
returns1
and \(N_A=N_B\), then theminus
operator will compute for each couple \((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 smallerdseries
object (B
) is “broadcast” across the largerdseries
(A
) so that they have compatible shapes, theminus
operator will subtract the variable defined inB
from each variable inA
. IfB
is a double scalar, then the methodminus
will subtractB
from all the observations/variables inA
. IfB
is a row vector of length \(N_A\), then theminus
method will subtractB(i)
from all the observations of variablei
, for \(i=1,...,N_A\). IfB
is a column vector of length \(T_A\), then theminus
method will subtractB
from 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 fordseries
objects and computes element-by-element power.A
is adseries
object withN
variables andT
observations. IfB
is a real scalar, thenmpower(A,B)
returns adseries
objectC
withC.data(t,n)=A.data(t,n)^C
. IfB
is adseries
object withN
variables andT
observations thenmpower(A,B)
returns adseries
objectC
withC.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 fordseries
objects, element by element division (like the./
MATLAB/Octave operator). If bothA
andB
aredseries
objects, they do not need to be defined over the same time ranges. IfA
andB
aredseries
objects 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)
returns1
and \(N_A=N_B\), then themrdivide
operator will compute for each couple \((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 smallerdseries
object (B
) is “broadcast” across the largerdseries
(A
) so that they have compatible shapes. In this case themrdivide
operator will divide each variable defined in A by the variable in B, observation per observation. If B is a double scalar, thenmrdivide
will divide all the observations/variables inA
byB
. IfB
is a row vector of length \(N_A\), thenmrdivide
will divide all the observations of variablei
byB(i)
, for \(i=1,...,N_A\). IfB
is a column vector of length \(T_A\), thenmrdivide
will perform a division of all the variables byB
, element by element.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 fordseries
objects and the Hadammard product (the .* MATLAB/Octave operator). If bothA
andB
aredseries
objects, they do not need to be defined over the same time ranges. IfA
andB
aredseries
objects with \(T_A\) and \(_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)
returns1
and \(N_A=N_B\), then themtimes
operator will compute for each couple \((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 smallerdseries
object (B
) is “broadcast” across the largerdseries
(A
) so that they have compatible shapes,mtimes
operator will multiply each variable defined inA
by the variable inB
, observation per observation. IfB
is a double scalar, then the methodmtimes
will multiply all the observations/variables inA
byB
. IfB
is a row vector of length \(N_A\), then themtimes
method will multiply all the observations of variablei
byB(i)
, for \(i=1,...,N_A\). IfB
is a column vector of length \(T_A\), then themtimes
method will perform a multiplication of all the variables byB
, element by element.
- Method: B = nanmean(A[, geometric])¶
Overloads the MATLAB/Octavenanmean
function fordseries
objects. Returns the mean of each variable indseries
objectA
ignoring the NaN values. If the second argument istrue
the geometric mean is computed, otherwise (default) the arithmetic mean is reported.
- Method: B = nanstd(A[, geometric])¶
Overloads the MATLAB/Octavenanstd
function fordseries
objects. Returns the standard deviation of each variable indseries
objectA
ignoring the NaN values. If the second argument istrue
the geometric std is computed, default value of the second argument isfalse
.
- Method: C = ne(A, B)
Overloads the MATLAB/Octavene
(not equal,~=
) operator.dseries
objectsA
andB
must have the same number of observations (say, \(T\)) and variables (\(N\)). The returned argument is a \(T\) by \(N\) matrix of zeros and ones. Element \((i,j)\) ofC
is equal to1
if and only if observation \(i\) for variable \(j\) inA
andB
are 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 indseries
objectA
.Example
>> ts0 = dseries(randn(10)); >> ts0.nobs ans = 10
- Method: B = onesidedhpcycle(A[, lambda[, init]])¶
- Method: onesidedhpcycle_(A[, lambda[, init]])¶
Extracts the cycle component from adseries
A
object using a one sided HP filter (with a Kalman filter) and returns adseries
object,B
. The default value forlambda
, the smoothing parameter, is1600
. By default, ifìnit
is not provided, the initial value is based on the first two observations.
- Method: B = onesidedhptrend(A[, lambda[, init]])¶
- Method: onesidedhptrend_(A[, lambda[, init]])¶
Extracts the trend component from adseries
A
object using a one sided HP filter (with a Kalman filter) and returns adseries
object,B
. The default value forlambda
, the smoothing parameter, is1600
. By default, ifìnit
is not provided, the initial value is based on the first two observations.
- Method: h = plot(A)¶
- Method: h = plot(A, B)
- Method: h = plot(A[, ...])
- Method: h = plot(A, B[, ...])
Overloads MATLAB/Octave’splot
function fordseries
objects. Returns a MATLAB/Octave plot handle, that can be used to modify the properties of the plotted time series. If only onedseries
object,A
, is passed as argument, then the plot function will put the associated dates on the x-abscissa. If thisdseries
object contains only one variable, additional arguments can be passed to modify the properties of the plot (as one would do with the MATLAB/Octave’s version of the plot function). Ifdseries
objectA
contains more than one variable, it is not possible to pass these additional arguments and the properties of the plotted time series must be modified using the returned plot handle and the MATLAB/Octaveset
function (see example below). If twodseries
objects,A
andB
, are passed as input arguments, the plot function will plot the variables inA
against the variables inB
(the number of variables in each object must be the same otherwise an error is issued). Again, if each object contains only one variable, additional arguments can be passed to modify the properties of the plotted time series, otherwise the MATLAB/Octaveset
command has to be used.Example
Define a
dseries
object with two variables (named by defaultVariable_1
andVariable_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
ts
on 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_1
againstexp(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
set
function:>> h = plot(ts, ts.exp()); >> set(h(1),'ok'); >> set(h(2),'+r');
- Method: C = plus(A, B)
Overloads the MATLAB/Octaveplus
(+
) operator fordseries
objects, element by element addition. If bothA
andB
aredseries
objects, they do not need to be defined over the same time ranges. IfA
andB
aredseries
objects 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)
returns1
and \(N_A=N_B\), then theplus
operator will compute for each couple \((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 smallerdseries
object (B
) is “broadcast” across the largerdseries
(A
) so that they have compatible shapes, the plus operator will add the variable defined inB
to each variable inA
. IfB
is a double scalar, then the methodplus
will addB
to all the observations/variables inA
. IfB
is a row vector of length \(N_A\), then theplus
method will addB(i)
to all the observations of variablei
, for \(i=1,...,N_A\). IfB
is a column vector of length \(T_A\), then theplus
method will addB
to all the variables.
- Method: C = pop(A[, B])
- Method: pop_(A[, B])¶
Removes variableB
fromdseries
objectA
. By default, if the second argument is not provided, 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 dseries objectA
.info
is is a \(n \times 3\) cell array. Each row provides informations necessary to project a variable. The first column contains the name of variable (row char array). the second column contains the name of the method used to project the associated variable (row char array), possible values are'Trend'
,'Constant'
, and'AR'
. Last column provides quantitative information about the projection. If the second column value is'Trend'
, the third column value is the growth factor of the (exponential) trend. If the second column value is'Constant'
, the third column value is the level of the variable. If the second column value is'AR'
, the third column value is the autoregressive parameter. The variables can be projected with an AR(p) model, if the third column contains a 1×p vector of doubles. The stationarity of the AR(p) model is not tested. The case of the constant projection, using the last value of the variable, is covered with ‘Trend’ and a growth factor equal to 1, or ‘AR’ with an autoregressive parameter equal to one (random walk). This projection routine only deals with 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_(A)¶
- Method: qgrowth_(A)¶
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_(A, B)¶
IfB
is a row char array, the name of a variable, these methods are aliases forpop
andpop_
methods with two arguments. They remove variableB
fromdseries
objectA
. To remove more than one variable, one can pass a cell of row char 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 shorter syntax is available:
remove(ts,'Variable_2')
is equivalent tots{'Variable_2'} = []
([]
can be replaced by any empty object). This alternative syntax is useful if more than one variable has to be removed. For instance:ts{'Variable_@2,3,4@'} = [];
will remove
Variable_2
,Variable_3
andVariable_4
fromdseries
objectts
(if these variables exist). Regular expressions cannot be used but implicit loops can.
- Method: B = rename(A, oldname, newname)¶
- Method: rename_(A, oldname, newname)¶
Rename variableoldname
tonewname
indseries
objectA
. Returns adseries
object. If more than one variable needs to be renamed, it is possible to pass cells of char arrays as 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_(A, newname)
Replace the names inA
with those passed in the cell string arraynewname
.newname
must have the same number of elements asdseries
objectA
has variables. Returns adseries
object.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)¶
Redefineops
member.
- Method: A = resetags(A, ops)¶
Redefinetags
member.
- Method: B = round(A[, n])¶
- Method: round_(A[, n])¶
Rounds to the nearest decimal or integer.n
is the precision parameter (number of decimals), default value is 0 meaning that that by default the method rounds to the nearest integer.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/Octavesave
function and savesdseries
objectA
to disk. Possible formats aremat
(this is the default),m
(MATLAB/Octave script), andcsv
(MATLAB binary data file). The name of the file without 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 adseries
object as explained above.
- Method: B = set_names(A, s1, s2, ...)¶
Renames variables indseries
objectA
and returns adseries
objectB
with new namess1
,s2
, … The number of input arguments after the first one (dseries
objectA
) must be equal toA.vobs
(the number of variables inA
).s1
will be the name of the first variable inB
,s2
the name of the second variable inB
, and so on.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’s
size
function. Returns the number of observations indseries
objectA
(i.e.A.nobs
) and the number of variables (i.e.A.vobs
). If a second input argument is passed, thesize
function returns the number of observations ifdim=1
or the number of variables ifdim=2
(for all other values ofdim
an error is issued).Example
>> ts0 = dseries(ones(1,3)); >> ts0.size() ans = 1 3
- Method: B = std(A[, geometric])¶
Overloads the MATLAB/Octavestd
function fordseries
objects. Returns the standard deviation of each variable indseries
objectA
. If the second argument istrue
the geometric standard deviation is computed (default value of the second argument isfalse
).
- Method: B = subsample(A, d1, d2)¶
Returns a subsample, for periods betweendates
d1
andd2
. The same can be achieved by indexing adseries
object with adates
object, but thesubsample
method is easier to use programmatically.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])¶
Add a tag to a variable indseries
objectA
.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_(A, name, newtexname)¶
- Method: tex_rename_(A, newtexname)
Redefines the tex name of variablename
tonewtexname
indseries
objectA
. Returns adseries
object.With only two arguments
A
andnewtexname
, it redefines the tex names of theA
to those contained innewtexname
. Here,newtexname
is a cell string array with the same number of entries as variables inA
.
- Method: B = uminus(A)
Overloadsuminus
(-
, unary minus) fordseries
object.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 thevertcat
MATLAB/Octave method fordseries
objects. This method is used to append more observations to adseries
object. Returns adseries
objectD
containing the variables indseries
objects passed as inputs. All the input arguments must bedseries
objects with the same variables defined on 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 number of variables indseries
objectA
.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. Thex13
class has 22 members:- Members:
y –
dseries
object with a single variable.x –
dseries
object 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 anx13
object with dseries objecty
. Thedseries
object passed as an argument must contain only one variable, the one we need to pass to X-13.
- Constructor: x13(y, x)
Instantiates anx13
object with dseries objectsy
andx
. The firstdseries
object passed as an argument must contain only one variable, the seconddseries
object 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
arima
command, 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
automdl
command, 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
regression
command, 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
estimate
command, 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
transform
command, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs. For example, the key/value pairfunction,log
instructs the use of a multiplicative instead of an additive seasonal pattern, whilefunction,auto
triggers an automatic selection between the two based on their fit.
- Method: A = outlier(A, key, value[, key, value[, [...]]])¶
Interface to the
outlier
command, 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
forecast
command, 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
check
command, 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
x11
command, 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
force
command, 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
history
command, 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
metadata
command, 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
identify
command, 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
pickmdl
command, 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
seats
command, 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
slidingspans
command, 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
spectrum
command, 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
x11regression
command, see the X-13 ARIMA-SEATS reference manual. All the options must be passed by key/value pairs.
- Method: print(A[, basefilename])¶
Prints an
.spc
file 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 indseries
objects (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)')
instructsx11
to save both the final seasonally adjusted seriesd11
and the final seasonal factord10
intodseries
with 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:
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.
All these routines have two mandatory input arguments: the first one is adseries
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
6.4.2. Create time series with a univariate model¶
It is possible to expand adseries
object recursively with thefrom
command. For instance to create adseries
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.79661The 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. Thefrom
command must be followed by a range, which is separated from the (recursive) expression to be evaluated by thedo
command.