Dynare Reference Manual: Dates

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

### 6.1 Dates

Next: dates class, 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: dates in a mod file, 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: dates in a mod file, Up: Dates [Contents][Index]