6.1 Dates

6.1.1 dates in a mod file

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

1990Y
1990Q3
1990M11
1990W49

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

plus binary operator (+)

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

plus unary operator (+)

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

minus binary operator (-)

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

minus unary operator (-)

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

colon operator (:)

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

horzcat operator ([,])

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

vertcat operator ([;])

Same as horzcat operator.

eq operator (equal, ==)

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

ne operator (not equal, ~=)

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

lt operator (less than, <)

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

gt operator (greater than, >)

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

le operator (less or equal, <=)

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

ge operator (greater or equal, >=)

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

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 1, a(end)==1951Q1 returns 1 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 dates class

The dates class has three members:

freq

an integer equal to 1, 4, 12 or 52 (resp. for annual, quarterly, monthly or weekly dates).

ndat

an integer scalar, the number of declared dates in the object.

time

a ndat*2 array of integers, the years are stored in the first column, the subperiods (1 for annual dates, 1-4 for quarterly dates, 1-12 for monthly dates and 1-52 for weekly dates) are stored in the second column.

Each member is private, one can display the content of a member but cannot change its value:

>> d = dates('2009Q2');
>> d.time

ans =

        2009           2

>>

Note that it is not possible to mix frequencies in a dates object: all the elements must have common frequency. The dates class has five constructors:

dates: dates ()

dates: dates (FREQ)

Returns an empty dates 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, ’Q’ for quarterly dates, ’M’ for monthly dates or ’W’ for weekly dates. Note that FREQ 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), 4 (quarterly), 12 (monthly) or 52 (weekly). The instantiation of empty objects can be used to rename the dates class. For instance, if one only works with quarterly dates, he can create qq as:

qq = dates('Q')

and a dates object holding the date 2009Q2:

d0 = qq(2009,2);

which is much simpler if dates objects have to be defined programmatically.

dates: dates (STRING)

dates: dates (STRING, STRING, ...)

Returns a dates object that represents a date as given by the string STRING. This string has to be interpretable as a date (only strings of the following forms are admitted: '1990Y', '1990A', '1990Q1', '1990M2', '1990W5'), the routine isdate 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 resulting dates object contains as many elements as arguments to the constructor.

dates: dates (DATES)

dates: dates (DATES, DATES, ...)

Returns a copy of the dates object DATES passed as input arguments. If more than one argument is provided, they should all be dates objects. The number of elements in the instantiated dates object is equal to the sum of the elements in the dates passed as arguments to the constructor.

dates: dates (FREQ, YEAR, SUBPERIOD)

where FREQ is a single character (’Y’, ’A’, ’Q’, ’M’, ’W’) or integer (1, 4, 12 or 52) specifying the frequency, YEAR and SUBPERIOD are n*1 vectors of integers. Returns a dates object with n elements. If FREQ is equal to 'Y', 'A' or 1, the third argument is not needed (because SUBPERIOD is necessarily a vector of ones in this case).

Examples

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

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

Y = X.multiplybytwo()

or equivalently:

Y = multiplybytwo(X)

the object X is left unchanged, and the object Y is a modified copy of X.

dates: C = append (A, B)

Appends dates object B, or a string that can be interpreted as a date, to the dates object A. If B is a dates 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>

dates: C = colon (A, B)

dates: C = colon (A, i, B)

Overloads the Matlab/Octave colon (:) operator. A and B are dates objects. The optional increment i is a scalar integer (default value is i=1). This method returns a dates 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>

dates: B = double (A)

Overloads the Matlab/Octave double function. A is a dates object. The method returns a floating point representation of a dates 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, 12 or 52).

Example

>> a = dates('1950Q1'):dates('1950Q4'); >> a.double() ans = 1950.00 1950.25 1950.50 1950.75

dates: C = eq (A, B)

Overloads the Matlab/Octave eq (equal, ==) operator. dates objects A and B must have the same number of elements (say, n). The returned argument is a n by 1 vector of zeros and ones. The i-th element of C is equal to 1 if and only if the dates A(i) and B(i) are the same.

Example

>> A = dates('1950Q1','1951Q2'); >> B = dates('1950Q1','1950Q2'); >> A==B ans = 1 0

dates: C = ge (A, B)

Overloads the Matlab/Octave ge (greater or equal, >=) operator. dates objects A and B must have the same number of elements (say, n). The returned argument is a n by 1 vector of zeros and ones. The i-th element of C is equal to 1 if and only if the date A(i) is posterior or equal to the date B(i).

Example

>> A = dates('1950Q1','1951Q2'); >> B = dates('1950Q1','1950Q2'); >> A>=B ans = 1 1

dates: C = gt (A, B)

Overloads the Matlab/Octave gt (greater than, >=) operator. dates objects A and B must have the same number of elements (say, n). The returned argument is a n by 1 vector of zeros and ones. The i-th element of C is equal to 1 if and only if the date A(i) is posterior to the date B(i).

Example

>> A = dates('1950Q1','1951Q2'); >> B = dates('1950Q1','1950Q2'); >> A>B ans = 0 1

dates: D = horzcat (A, B, C, ...)

Overloads the Matlab/Octave horzcat operator. All the input arguments must be dates objects. The returned argument is a dates 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>

dates: C = intersect (A, B)

Overloads the Matlab/Octave intersect function. All the input arguments must be dates objects. The returned argument is a dates object gathering all the common dates given in the input arguments. If A and B are disjoint dates objects, the function returns an empty dates object. Returned dates in dates object C 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>

dates: C = setdiff (A, B)

Overloads the Matlab/Octave setdiff function. All the input arguments must be dates objects. The returned argument is a dates object all dates present in A but not in B. If A and B are disjoint dates objects, the function returns A. Returned dates in dates object C are sorted by increasing order.

Example

>> A = dates('1950Q1'):dates('1969Q4') ; >> B = dates('1960Q1'):dates('1969Q4') ; >> C = dates('1970Q1'):dates('1979Q4') ; >> d1 = setdiff(d1,d2); >> d2 = setdiff(d1,d3); d1 = <dates: 1950Q1, 1950Q2, ..., 1959Q3, 1959Q4> d2 = <dates: 1950Q1, 1950Q2, ..., 1969Q3, 1969Q4>

dates: B = isempty (A)

Overloads the Matlab/Octave isempty function for dates object.

Example

>> A = dates('1950Q1'):dates('1951Q4'); >> A.isempty() ans = 0

dates: C = isequal (A, B)

Overloads the Matlab/Octave isequal function for dates objects.

Example

>> A = dates('1950Q1'):dates('1951Q4'); >> isequal(A,A) ans = 1

dates: C = le (A, B)

Overloads the Matlab/Octave le (less or equal, <=) operator. dates objects A and B must have the same number of elements (say, n). The returned argument is a n by 1 vector of zeros and ones. The i-th element of C is equal to 1 if and only if the date A(i) is not posterior to the date B(i).

Example

>> A = dates('1950Q1','1951Q2'); >> B = dates('1950Q1','1950Q2'); >> A<=B ans = 1 0

dates: B = length (A)

Overloads the Matlab/Octave length function. Returns the number of dates in dates object A (B is a scalar integer).

Example

>> A = dates('1950Q1','1951Q2'); >> A.length() ans = 2

dates: C = lt (A, B)

Overloads the Matlab/Octave lt (less than, <=) operator. dates objects A and B must have the same number of elements (say, n). The returned argument is a n by 1 vector of zeros and ones. The i-th element of C is equal to 1 if and only if the date A(i) preceeds the date B(i).

Example

>> A = dates('1950Q1','1951Q2'); >> B = dates('1950Q1','1950Q2'); >> A<B ans = 0 0

dates: D = max (A, B, C, ...)

Overloads the Matlab/Octave max function. All input arguments must be dates objects. The function returns a single element dates object containing the greatest date.

Example

>> A = {dates('1950Q2'), dates('1953Q4','1876Q2'), dates('1794Q3')}; >> max(A{:}) ans = <dates: 1953Q4>

dates: D = min (A, B, C, ...)

Overloads the Matlab/Octave min function. All input arguments must be dates objects. The function returns a single element dates object containing the smallest date.

Example

>> A = {dates('1950Q2'), dates('1953Q4','1876Q2'), dates('1794Q3')}; >> min(A{:}) ans = <dates: 1794Q3>

dates: C = minus (A, B)

Overloads the Matlab/Octave minus operator (-). If both input arguments are dates objects, then number of periods between A and B is returned (so that A+C=B). If B is a vector of integers, the minus operator shifts the dates object by B 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>

dates: C = ne (A, B)

Overloads the Matlab/Octave ne (not equal, ~=) operator. dates objects A and B must have the same number of elements (say, n) or one of the inputs must be a single element dates object. The returned argument is a n by 1 vector of zeros and ones. The i-th element of C is equal to 1 if and only if the dates A(i) and B(i) are different.

Example

>> A = dates('1950Q1','1951Q2'); >> B = dates('1950Q1','1950Q2'); >> A~=B ans = 0 1

dates: C = plus (A, B)

Overloads the Matlab/Octave plus operator (+). If both input arguments are dates objects, then the method combines A and B without removing repetitions. If B is a vector of integers, the plus operator shifts the dates object by B 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>

dates: C = pop (A)

dates: C = pop (A,B)

Pop method for dates class. If only one input is provided, the method removes the last element of a dates object. If a second input argument is provided, a scalar integer between 1 and A.length(), the method removes element number B from dates object A.

Example

>> d1 = dates('1950Q1','1950Q2'); >> d1.pop() ans = <dates: 1950Q1> >> d1.pop(1) ans = <dates: 1950Q2>

dates: B = sort (A)

Sort method for dates objects. Returns a dates object with elements sorted by increasing order.

Example

>> dd = dates('1945Q3','1938Q4','1789Q3'); >> dd.sort() ans = <dates: 1789Q3, 1938Q4, 1945Q3>

dates: B = uminus (A)

Overloads the Matlab/Octave unary minus operator. Returns a dates object with elements shifted one period backward.

Example

>> dd = dates('1945Q3','1938Q4','1973Q1'); >> -dd ans = <dates: 1945Q2, 1938Q3, 1972Q4>

dates: D = union (A, B, C, ...)

Overloads the Matlab/Octave union function. Returns a dates object with elements sorted by increasing order (repetitions are removed, to keep the repetitions use the horzcat or plus operators).

Example

>> d1 = dates('1945Q3','1973Q1','1938Q4'); >> d2 = dates('1973Q1','1976Q1'); >> union(d1,d2) ans = <dates: 1938Q4, 1945Q3, 1973Q1, 1976Q1>

dates: B = unique (A)

Overloads the Matlab/Octave unique function. Returns a dates 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>

dates: B = uplus (A)

Overloads the Matlab/Octave unary plus operator. Returns a dates object with elements shifted one period ahead.

Example

>> dd = dates('1945Q3','1938Q4','1973Q1'); >> +dd ans = <dates: 1945Q4, 1939Q1, 1973Q2>

This document was generated by Stéphane Adjemian on June 11, 2017 using texi2html 1.82.