Next: , Up: Time Series   [Contents][Index]

6.1 Dates

Next: , Up: Dates   [Contents][Index]

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.

Previous: , Up: Dates   [Contents][Index]

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>
```

Previous: , Up: Dates   [Contents][Index]