1.. default-domain:: dynare 2 3.. |br| raw:: html 4 5 <br> 6 7########### 8Time Series 9########### 10 11Dynare provides a MATLAB/Octave class for handling time series data, 12which is based on a class for handling dates. Dynare also provides a 13new type for dates, so that the basic user does not have to worry 14about class and methods for dates. Below, you will first find the 15class and methods used for creating and dealing with dates and then 16the class used for using time series. 17 18 19Dates 20===== 21.. highlight:: matlab 22 23Dates in a mod file 24------------------- 25 26Dynare understands dates in a mod file. Users can declare annual, 27quarterly, or monthly dates using the following syntax:: 28 29 1990Y 30 1990Q3 31 1990M11 32 33Behind the scene, Dynare’s preprocessor translates these expressions 34into instantiations of the MATLAB/Octave’s class ``dates`` described 35below. Basic operations can be performed on dates: 36 37**plus binary operator (+)** 38 39 An integer scalar, interpreted as a number of periods, can be 40 added to a date. For instance, if ``a = 1950Q1`` then ``b = 41 1951Q2`` and ``b = a + 5`` are identical. 42 43**plus unary operator (+)** 44 45 Increments a date by one period. ``+1950Q1`` is identical to 46 ``1950Q2``, ``++++1950Q1`` is identical to ``1951Q1``. 47 48**minus binary operator (-)** 49 50 Has two functions: difference and subtraction. If the second 51 argument is a date, calculates the difference between the first 52 date and the secmond date (e.g. ``1951Q2-1950Q1`` is equal to 53 ``5``). If the second argument is an integer ``X``, subtracts 54 ``X`` periods from the date (e.g. ``1951Q2-2`` is equal to 55 ``1950Q4``). 56 57**minus unary operator (-)** 58 59 Subtracts one period to a date. ``-1950Q1`` is identical to 60 ``1949Q4``. The unary minus operator is the reciprocal of the 61 unary plus operator, ``+-1950Q1`` is identical to ``1950Q1``. 62 63**colon operator (:)** 64 65 Can be used to create a range of dates. For instance, ``r = 66 1950Q1:1951Q1`` creates a ``dates`` object with five elements: 67 ``1950Q1, 1950Q2, 1950Q3, 1950Q4`` and ``1951Q1``. By default the 68 increment between each element is one period. This default can be 69 changed using, for instance, the following instruction: 70 ``1950Q1:2:1951Q1`` which will instantiate a ``dates`` object with 71 three elements: ``1950Q1``, ``1950Q3`` and ``1951Q1``. 72 73**horzcat operator ([,])** 74 75 Concatenates dates objects without removing repetitions. For 76 instance ``[1950Q1, 1950Q2]`` is a ``dates`` object with two 77 elements (``1950Q1`` and ``1950Q2``). 78 79**vertcat operator ([;])** 80 81 Same as ``horzcat`` operator. 82 83**eq operator (equal, ==)** 84 85 Tests if two ``dates`` objects are equal. ``+1950Q1==1950Q2`` 86 returns ``true``, ``1950Q1==1950Q2`` returns ``false``. If the compared 87 objects have both ``n>1`` elements, the ``eq`` operator returns a 88 column vector, ``n`` by ``1``, of zeros and ones. 89 90**ne operator (not equal, ~=)** 91 92 Tests if two ``dates`` objects are not equal. ``+1950Q1~=`` 93 returns ``false`` while ``1950Q1~=1950Q2`` returns ``true``. If the 94 compared objects both have ``n>1`` elements, the ``ne`` operator 95 returns an ``n`` by ``1`` column vector of zeros and ones. 96 97**lt operator (less than, <)** 98 99 Tests if a ``dates`` object preceeds another ``dates`` object. For 100 instance, ``1950Q1<1950Q3`` returns ``true``. If the compared objects 101 have both ``n>1`` elements, the ``lt`` operator returns a column 102 vector, ``n`` by ``1``, of zeros and ones. 103 104**gt operator (greater than, >)** 105 106 Tests if a ``dates`` object follows another ``dates`` object. For 107 instance, ``1950Q1>1950Q3`` returns ``false``. If the compared objects 108 have both ``n>1`` elements, the ``gt`` operator returns a column 109 vector, ``n`` by ``1``, of zeros and ones. 110 111**le operator (less or equal, <=)** 112 113 Tests if a ``dates`` object preceeds another ``dates`` object or 114 is equal to this object. For instance, ``1950Q1<=1950Q3`` returns 115 ``true``. If the compared objects have both ``n>1`` elements, the 116 ``le`` operator returns a column vector, ``n`` by ``1``, of zeros 117 and ones. 118 119**ge operator (greater or equal, >=)** 120 121 Tests if a ``dates`` object follows another ``dates`` object or is 122 equal to this object. For instance, ``1950Q1>=1950Q3`` returns 123 ``false``. If the compared objects have both ``n>1`` elements, the 124 ``ge`` operator returns a column vector, ``n`` by ``1``, of zeros 125 and ones. 126 127One can select an element, or some elements, in a ``dates`` object as 128he would extract some elements from a vector in MATLAB/Octave. Let ``a 129= 1950Q1:1951Q1`` be a ``dates`` object, then ``a(1)==1950Q1`` returns 130``true``, ``a(end)==1951Q1`` returns ``true`` and ``a(end-1:end)`` selects 131the two last elements of ``a`` (by instantiating the ``dates`` object 132``[1950Q4, 1951Q1]``). 133 134Remark: Dynare substitutes any occurrence of dates in the ``.mod`` file 135into an instantiation of the ``dates`` class regardless of the 136context. For instance, ``d = 1950Q1`` will be translated as ``d = 137dates('1950Q1');``. This automatic substitution can lead to a crash if 138a date is defined in a string. Typically, if the user wants to display 139a date:: 140 141 disp('Initial period is 1950Q1'); 142 143Dynare will translate this as:: 144 145 disp('Initial period is dates('1950Q1')'); 146 147which will lead to a crash because this expression is illegal in 148MATLAB. For this situation, Dynare provides the ``$`` escape 149parameter. The following expression:: 150 151 disp('Initial period is $1950Q1'); 152 153will be translated as:: 154 155 disp('Initial period is 1950Q1'); 156 157in the generated MATLAB script. 158 159 160.. _dates-members: 161 162The dates class 163--------------- 164 165.. class:: dates 166 167 :arg int freq: equal to 1, 4, or 12 (resp. for annual, 168 quarterly, or monthly dates). 169 :arg int ndat: the number of declared dates in the object. 170 :arg int time: a ``ndat*2`` array, the years are stored in the 171 first column, the subperiods (1 for annual dates, 172 1-4 for quarterly dates, and 1-12 for monthly 173 dates) are stored in the second column. 174 175 Each member is private, one can display the content of a member 176 but cannot change its value directly. Note that it is not possible 177 to mix frequencies in a ``dates`` object: all the elements must 178 have common frequency. 179 180 The ``dates`` class has the following constructors: 181 182 .. construct:: dates() 183 dates(FREQ) 184 185 |br| Returns an empty ``dates`` object with a given frequency 186 (if the constructor is called with one input 187 argument). ``FREQ`` is a character equal to ’Y’ or ’A’ for 188 annual dates, ’Q’ for quarterly dates, or ’M’ for monthly 189 dates. Note that ``FREQ`` is not case sensitive, so that, for 190 instance, ’q’ is also allowed for quarterly dates. The 191 frequency can also be set with an integer scalar equal to 1 192 (annual), 4 (quarterly), or 12 (monthly). The instantiation of 193 empty objects can be used to rename the ``dates`` class. For 194 instance, if one only works with quarterly dates, object 195 ``qq`` can be created as:: 196 197 qq = dates('Q') 198 199 and a ``dates`` object holding the date ``2009Q2``:: 200 201 d0 = qq(2009,2); 202 203 which is much simpler if ``dates`` objects have to be defined 204 programmatically. 205 206 207 .. construct:: dates(STRING) 208 dates(STRING, STRING, ...) 209 210 |br| Returns a ``dates`` object that represents a date as 211 given by the string ``STRING``. This string has to be 212 interpretable as a date (only strings of the following forms 213 are admitted: ``'1990Y'``, ``'1990A'``, ``'1990Q1'``, 214 ``'1990M2'``), the routine ``isdate`` can be used to test if a 215 string is interpretable as a date. If more than one argument 216 is provided, they should all be dates represented as strings, 217 the resulting ``dates`` object contains as many elements as 218 arguments to the constructor. 219 220 221 .. construct:: dates(DATES) 222 dates(DATES, DATES, ...) 223 224 |br| Returns a copy of the ``dates`` object ``DATES`` passed 225 as input arguments. If more than one argument is provided, 226 they should all be ``dates`` objects. The number of elements 227 in the instantiated ``dates`` object is equal to the sum of 228 the elements in the ``dates`` passed as arguments to the 229 constructor. 230 231 232 .. construct:: dates (FREQ, YEAR, SUBPERIOD) 233 234 |br| where ``FREQ`` is a single character (’Y’, ’A’, ’Q’, ’M’) 235 or integer (1, 4, or 12) specifying the frequency, ``YEAR`` 236 and ``SUBPERIOD`` are ``n*1`` vectors of integers. Returns a 237 ``dates`` object with ``n`` elements. If ``FREQ`` is equal to 238 ``'Y'``, ``'A'`` or ``1``, the third argument is not needed 239 (because ``SUBPERIOD`` is necessarily a vector of ones in this 240 case). 241 242 243 *Example* 244 245 :: 246 247 do1 = dates('1950Q1'); 248 do2 = dates('1950Q2','1950Q3'); 249 do3 = dates(do1,do2); 250 do4 = dates('Q',1950, 1); 251 252 253 A list of the available methods, by alphabetical order, is given 254 below. Note that by default the methods do not allow in place 255 modifications: when a method is applied to an object a new object 256 is instantiated. For instance, to apply the method 257 ``multiplybytwo`` to an object ``X`` we write:: 258 259 >> X = 2; 260 >> Y = X.multiplybytwo(); 261 >> X 262 263 2 264 265 >> Y 266 267 4 268 269 270 or equivalently:: 271 272 >> Y = multiplybytwo(X); 273 274 the object ``X`` is left unchanged, and the object ``Y`` is a 275 modified copy of ``X`` (multiplied by two). This behaviour is 276 altered if the name of the method is postfixed with an 277 underscore. In this case the creation of a copy is avoided. For 278 instance, following the previous example, we would have:: 279 280 >> X = 2; 281 >> X.multiplybytwo_(); 282 >> X 283 284 4 285 286 Modifying the objects in place, with underscore methods, is 287 particularly useful if the methods are called in loops, since this 288 saves the object instantiation overhead. 289 290 .. datesmethod:: C = append (A, B) 291 C = append_ (A, B) 292 293 |br| Appends ``dates`` object ``B``, or a string that can be 294 interpreted as a date, to the ``dates`` object ``A``. If ``B`` 295 is a ``dates`` object it is assumed that it has no more than 296 one element. 297 298 *Example* 299 300 :: 301 302 >> D = dates('1950Q1','1950Q2'); 303 >> d = dates('1950Q3'); 304 >> E = D.append(d); 305 >> F = D.append('1950Q3'); 306 >> isequal(E,F) 307 308 ans = 309 310 1 311 >> F 312 313 F = <dates: 1950Q1, 1950Q2, 1950Q3> 314 315 >> D 316 317 D = <dates: 1950Q1, 1950Q2> 318 319 >> D.append_('1950Q3') 320 321 ans = <dates: 1950Q1, 1950Q2, 1950Q3> 322 323 324 .. datesmethod:: B = char (A) 325 326 |br| Overloads the MATLAB/Octave ``char`` function. Converts a 327 ``dates`` object into a character array. 328 329 *Example* 330 331 :: 332 333 >> A = dates('1950Q1'); 334 > A.char() 335 336 ans = 337 338 '1950Q1' 339 340 341 .. datesmethod:: C = colon (A, B) 342 C = colon (A, i, B) 343 344 |br| Overloads the MATLAB/Octave colon (``:``) operator. A and B 345 are ``dates`` objects. The optional increment ``i`` is a 346 scalar integer (default value is ``i=1``). This method returns 347 a ``dates`` object and can be used to create ranges of dates. 348 349 *Example* 350 351 :: 352 353 >> A = dates('1950Q1'); 354 >> B = dates('1951Q2'); 355 >> C = A:B 356 357 C = <dates: 1950Q1, 1950Q2, 1950Q3, 1950Q4, 1951Q1> 358 359 >> D = A:2:B 360 361 D = <dates: 1950Q1, 1950Q3, 1951Q1> 362 363 364 .. datesmethod:: B = copy (A) 365 366 |br| Returns a copy of a ``dates`` object. 367 368 369 .. datesmethod:: disp (A) 370 371 |br| Overloads the MATLAB/Octave disp function for ``dates`` object. 372 373 374 .. datesmethod:: display (A) 375 376 |br| Overloads the MATLAB/Octave display function for ``dates`` object. 377 378 *Example* 379 380 :: 381 382 >> disp(B) 383 384 B = <dates: 1950Q1, 1950Q2, 1950Q3, 1950Q4, 1951Q1, 1951Q2, 1951Q3, 1951Q4, 1952Q1, 1952Q2, 1952Q3> 385 386 387 >> display(B) 388 389 B = <dates: 1950Q1, 1950Q2, ..., 1952Q2, 1952Q3> 390 391 392 .. datesmethod:: B = double (A) 393 394 |br| Overloads the MATLAB/Octave ``double`` function. ``A`` is 395 a ``dates`` object. The method returns a floating point 396 representation of a ``dates`` object, the integer and 397 fractional parts respectively corresponding to the year and 398 the subperiod. The fractional part is the subperiod number 399 minus one divided by the frequency (``1``, ``4``, or ``12``). 400 401 *Example*: 402 403 :: 404 405 >> a = dates('1950Q1'):dates('1950Q4'); 406 >> a.double() 407 408 ans = 409 410 1950.00 411 1950.25 412 1950.50 413 1950.75 414 415 416 .. datesmethod:: C = eq (A, B) 417 418 |br| Overloads the MATLAB/Octave ``eq`` (equal, ``==``) 419 operator. ``dates`` objects ``A`` and ``B`` must have the same 420 number of elements (say, ``n``). The returned argument is a 421 ``n`` by ``1`` vector of logicals. The i-th element of 422 ``C`` is equal to ``true`` if and only if the dates ``A(i)`` and 423 ``B(i)`` are the same. 424 425 *Example* 426 427 :: 428 429 >> A = dates('1950Q1','1951Q2'); 430 >> B = dates('1950Q1','1950Q2'); 431 >> A==B 432 433 ans = 434 435 2x1 logical array 436 437 1 438 0 439 440 441 .. datesmethod:: C = ge (A, B) 442 443 |br| Overloads the MATLAB/Octave ``ge`` (greater or equal, 444 ``>=``) operator. ``dates`` objects ``A`` and ``B`` must have 445 the same number of elements (say, ``n``). The returned 446 argument is a ``n`` by ``1`` vector of logicals. The 447 i-th element of ``C`` is equal to ``true`` if and only if the 448 date ``A(i)`` is posterior or equal to the date ``B(i)``. 449 450 *Example* 451 452 :: 453 454 >> A = dates('1950Q1','1951Q2'); 455 >> B = dates('1950Q1','1950Q2'); 456 >> A>=B 457 458 ans = 459 460 2x1 logical array 461 462 1 463 1 464 465 466 .. datesmethod:: C = gt (A, B) 467 468 |br| Overloads the MATLAB/Octave ``gt`` (greater than, ``>``) 469 operator. ``dates`` objects ``A`` and ``B`` must have the same 470 number of elements (say, ``n``). The returned argument is a 471 ``n`` by ``1`` vector of logicals. The i-th element of 472 ``C`` is equal to ``1`` if and only if the date ``A(i)`` is 473 posterior to the date ``B(i)``. 474 475 *Example* 476 477 :: 478 479 >> A = dates('1950Q1','1951Q2'); 480 >> B = dates('1950Q1','1950Q2'); 481 >> A>B 482 483 ans = 484 485 2x1 logical array 486 487 0 488 1 489 490 491 .. datesmethod:: D = horzcat (A, B, C, ...) 492 493 |br| Overloads the MATLAB/Octave ``horzcat`` operator. All the 494 input arguments must be ``dates`` objects. The returned 495 argument is a ``dates`` object gathering all the dates given 496 in the input arguments (repetitions are not removed). 497 498 *Example* 499 500 :: 501 502 >> A = dates('1950Q1'); 503 >> B = dates('1950Q2'); 504 >> C = [A, B]; 505 >> C 506 507 C = <dates: 1950Q1, 1950Q2> 508 509 510 .. datesmethod:: C = intersect (A, B) 511 512 |br| Overloads the MATLAB/Octave ``intersect`` function. All 513 the input arguments must be ``dates`` objects. The returned 514 argument is a ``dates`` object gathering all the common dates 515 given in the input arguments. If ``A`` and ``B`` are disjoint 516 ``dates`` objects, the function returns an empty ``dates`` 517 object. Returned dates in ``dates`` object ``C`` are sorted by 518 increasing order. 519 520 *Example* 521 522 :: 523 524 >> A = dates('1950Q1'):dates('1951Q4'); 525 >> B = dates('1951Q1'):dates('1951Q4'); 526 >> C = intersect(A, B); 527 >> C 528 529 C = <dates: 1951Q1, 1951Q2, 1951Q3, 1951Q4> 530 531 532 .. datesmethod:: B = isempty (A) 533 534 |br| Overloads the MATLAB/Octave ``isempty`` function. 535 536 *Example* 537 538 :: 539 540 >> A = dates('1950Q1'); 541 >> A.isempty() 542 543 ans = 544 545 logical 546 547 0 548 549 >> B = dates(); 550 >> B.isempty() 551 552 ans = 553 554 logical 555 556 1 557 558 .. datesmethod:: C = isequal (A, B) 559 560 |br| Overloads the MATLAB/Octave ``isequal`` function. 561 562 *Example* 563 564 :: 565 566 >> A = dates('1950Q1'); 567 >> B = dates('1950Q2'); 568 >> isequal(A, B) 569 570 ans = 571 572 logical 573 574 0 575 576 577 .. datesmethod:: C = le (A, B) 578 579 |br| Overloads the MATLAB/Octave ``le`` (less or equal, 580 ``<=``) operator. ``dates`` objects ``A`` and ``B`` must have 581 the same number of elements (say, ``n``). The returned 582 argument is a ``n`` by ``1`` vector of logicals. The 583 i-th element of ``C`` is equal to ``true`` if and only if the 584 date ``A(i)`` is anterior or equal to the date ``B(i)``. 585 586 *Example* 587 588 :: 589 590 >> A = dates('1950Q1','1951Q2'); 591 >> B = dates('1950Q1','1950Q2'); 592 >> A<=B 593 594 ans = 595 596 2x1 logical array 597 598 1 599 0 600 601 602 .. datesmethod:: B = length (A) 603 604 |br| Overloads the MATLAB/Octave ``length`` function. Returns 605 the number of elements in a ``dates`` object. 606 607 *Example* 608 609 :: 610 611 >> A = dates('1950Q1'):dates(2000Q3); 612 >> A.length() 613 614 ans = 615 616 203 617 618 619 .. datesmethod:: C = lt (A, B) 620 621 |br| Overloads the MATLAB/Octave ``lt`` (less than, 622 ``<``) operator. ``dates`` objects ``A`` and ``B`` must have 623 the same number of elements (say, ``n``). The returned 624 argument is a ``n`` by ``1`` vector of logicals. The 625 i-th element of ``C`` is equal to ``true`` if and only if the 626 date ``A(i)`` is anterior or equal to the date ``B(i)``. 627 628 *Example* 629 630 :: 631 632 >> A = dates('1950Q1','1951Q2'); 633 >> B = dates('1950Q1','1950Q2'); 634 >> A<B 635 636 ans = 637 638 2x1 logical array 639 640 0 641 0 642 643 644 .. datesmethod:: D = max (A, B, C, ...) 645 646 |br| Overloads the MATLAB/Octave ``max`` function. All input 647 arguments must be ``dates`` objects. The function returns a 648 single element ``dates`` object containing the greatest date. 649 650 *Example* 651 652 :: 653 654 >> A = {dates('1950Q2'), dates('1953Q4','1876Q2'), dates('1794Q3')}; 655 >> max(A{:}) 656 657 ans = <dates: 1953Q4> 658 659 660 .. datesmethod:: D = min (A, B, C, ...) 661 662 |br| Overloads the MATLAB/Octave ``min`` function. All input 663 arguments must be ``dates`` objects. The function returns a 664 single element ``dates`` object containing the smallest date. 665 666 *Example* 667 668 :: 669 670 >> A = {dates('1950Q2'), dates('1953Q4','1876Q2'), dates('1794Q3')}; 671 >> min(A{:}) 672 673 ans = <dates: 1794Q3> 674 675 676 .. datesmethod:: C = minus (A, B) 677 678 |br| Overloads the MATLAB/Octave ``minus`` operator 679 (``-``). If both input arguments are ``dates`` objects, then 680 number of periods between ``A`` and ``B`` is returned (so that 681 ``A+C=B``). If ``B`` is a vector of integers, the minus 682 operator shifts the ``dates`` object by ``B`` periods 683 backward. 684 685 *Example* 686 687 :: 688 689 >> d1 = dates('1950Q1','1950Q2','1960Q1'); 690 >> d2 = dates('1950Q3','1950Q4','1960Q1'); 691 >> ee = d2-d1 692 693 ee = 694 695 2 696 2 697 0 698 699 >> d1-(-ee) 700 701 ans = <dates: 1950Q3, 1950Q4, 1960Q1> 702 703 704 .. datesmethod:: C = mtimes (A, B) 705 706 |br| Overloads the MATLAB/Octave ``mtimes`` operator 707 (``*``). ``A`` and ``B`` are respectively expected to be a 708 ``dseries`` object and a scalar integer. Returns ``dates`` 709 object ``A`` replicated ``B`` times. 710 711 *Example* 712 713 :: 714 715 >> d = dates('1950Q1'); 716 >> d*2 717 718 ans = <dates: 1950Q1, 1950Q1> 719 720 721 .. datesmethod:: C = ne (A, B) 722 723 |br| Overloads the MATLAB/Octave ``ne`` (not equal, ``~=``) 724 operator. ``dates`` objects ``A`` and ``B`` must have the same 725 number of elements (say, ``n``) or one of the inputs must be a 726 single element ``dates`` object. The returned argument is a 727 ``n`` by ``1`` vector of logicals. The i-th element of 728 ``C`` is equal to ``true`` if and only if the dates ``A(i)`` and 729 ``B(i)`` are different. 730 731 *Example* 732 733 :: 734 735 >> A = dates('1950Q1','1951Q2'); 736 >> B = dates('1950Q1','1950Q2'); 737 >> A~=B 738 739 ans = 740 741 2x1 logical array 742 743 0 744 1 745 746 747 .. datesmethod:: C = plus (A, B) 748 749 |br| Overloads the MATLAB/Octave ``plus`` operator (``+``). If 750 both input arguments are ``dates`` objects, then the method 751 combines ``A`` and ``B`` without removing repetitions. If 752 ``B`` is a vector of integers, the ``plus`` operator shifts 753 the ``dates`` object by ``B`` periods forward. 754 755 *Example* 756 757 :: 758 759 >> d1 = dates('1950Q1','1950Q2')+dates('1960Q1'); 760 >> d2 = (dates('1950Q1','1950Q2')+2)+dates('1960Q1'); 761 >> ee = d2-d1; 762 763 ee = 764 765 2 766 2 767 0 768 769 >> d1+ee 770 ans = <dates: 1950Q3, 1950Q4, 1960Q1> 771 772 773 .. datesmethod:: C = pop (A) 774 C = pop (A, B) 775 C = pop_ (A) 776 C = pop_ (A, B) 777 778 |br| Pop method for ``dates`` class. If only one input is 779 provided, the method removes the last element of a ``dates`` 780 object. If a second input argument is provided, a scalar 781 integer between ``1`` and ``A.length()``, the method removes 782 element number ``B`` from ``dates`` object ``A``. 783 784 *Example* 785 786 :: 787 788 >> d = dates('1950Q1','1950Q2'); 789 >> d.pop() 790 791 ans = <dates: 1950Q1> 792 793 >> d.pop_(1) 794 795 ans = <dates: 1950Q2> 796 797 798 .. datesmethod:: C = remove (A, B) 799 C = remove_ (A, B) 800 801 |br| Remove method for ``dates`` class. Both inputs have to be ``dates`` objects, removes dates in ``B`` from ``A``. 802 803 *Example* 804 805 :: 806 807 >> d = dates('1950Q1','1950Q2'); 808 >> d.remove(dates('1950Q2')) 809 810 ans = <dates: 1950Q1> 811 812 813 .. datesmethod:: C = setdiff (A, B) 814 815 |br| Overloads the MATLAB/Octave ``setdiff`` function. All the 816 input arguments must be ``dates`` objects. The returned 817 argument is a ``dates`` object all dates present in ``A`` but 818 not in ``B``. If ``A`` and ``B`` are disjoint ``dates`` 819 objects, the function returns ``A``. Returned dates in 820 ``dates`` object ``C`` are sorted by increasing order. 821 822 *Example* 823 824 :: 825 826 >> A = dates('1950Q1'):dates('1969Q4'); 827 >> B = dates('1960Q1'):dates('1969Q4'); 828 >> C = dates('1970Q1'):dates('1979Q4'); 829 >> setdiff(A, B) 830 831 ans = <dates: 1950Q1, 1950Q2, ..., 1959Q3, 1959Q4> 832 833 >> setdiff(A, C) 834 835 ans = <dates: 1950Q1, 1950Q2, ..., 1969Q3, 1969Q4> 836 837 838 .. datesmethod:: B = sort (A) 839 B = sort_ (A) 840 841 |br| Sort method for ``dates`` objects. Returns a ``dates`` object 842 with elements sorted by increasing order. 843 844 *Example* 845 846 :: 847 848 >> dd = dates('1945Q3','1938Q4','1789Q3'); 849 >> dd.sort() 850 851 ans = <dates: 1789Q3, 1938Q4, 1945Q3> 852 853 854 .. datesmethod:: B = strings (A) 855 856 |br| Converts a ``dates`` object into a cell of char arrays. 857 858 *Example* 859 860 :: 861 862 >> A = dates('1950Q1'); 863 >> A = A:A+1; 864 >> strings(A) 865 866 ans = 867 868 1x2 cell array 869 870 {'1950Q1'} {'1950Q2'} 871 872 873 .. datesmethod:: B = subperiod (A) 874 875 |br| Returns the subperiod of a date (an integer scalar 876 between 1 and ``A.freq``). 877 878 *Example* 879 880 :: 881 882 >> A = dates('1950Q2'); 883 >> A.subperiod() 884 885 ans = 886 887 2 888 889 890 .. datesmethod:: B = uminus (A) 891 892 |br| Overloads the MATLAB/Octave unary minus operator. Returns 893 a ``dates`` object with elements shifted one period backward. 894 895 *Example* 896 897 :: 898 899 >> dd = dates('1945Q3','1938Q4','1973Q1'); 900 >> -dd 901 902 ans = <dates: 1945Q2, 1938Q3, 1972Q4> 903 904 905 .. datesmethod:: D = union (A, B, C, ...) 906 907 |br| Overloads the MATLAB/Octave ``union`` function. Returns a 908 ``dates`` object with elements sorted by increasing order 909 (repetitions are removed, to keep the repetitions use the 910 ``horzcat`` or ``plus`` operators). 911 912 *Example* 913 914 :: 915 916 >> d1 = dates('1945Q3','1973Q1','1938Q4'); 917 >> d2 = dates('1973Q1','1976Q1'); 918 >> union(d1,d2) 919 920 ans = <dates: 1938Q4, 1945Q3, 1973Q1, 1976Q1> 921 922 923 .. datesmethod:: B = unique (A) 924 B = unique_ (A) 925 926 |br| Overloads the MATLAB/Octave ``unique`` function. Returns 927 a ``dates`` object with repetitions removed (only the last 928 occurence of a date is kept). 929 930 *Example* 931 932 :: 933 934 >> d1 = dates('1945Q3','1973Q1','1945Q3'); 935 >> d1.unique() 936 937 ans = <dates: 1973Q1, 1945Q3> 938 939 940 .. datesmethod:: B = uplus (A) 941 942 |br| Overloads the MATLAB/Octave unary plus operator. Returns 943 a ``dates`` object with elements shifted one period ahead. 944 945 *Example* 946 947 :: 948 949 >> dd = dates('1945Q3','1938Q4','1973Q1'); 950 >> +dd 951 952 ans = <dates: 1945Q4, 1939Q1, 1973Q2> 953 954 955 .. datesmethod:: D = vertcat (A, B, C, ...) 956 957 |br| Overloads the MATLAB/Octave ``horzcat`` operator. All the 958 input arguments must be ``dates`` objects. The returned 959 argument is a ``dates`` object gathering all the dates given 960 in the input arguments (repetitions are not removed). 961 962 963 .. datesmethod:: B = year (A) 964 965 |br| Returns the year of a date (an integer scalar 966 between 1 and ``A.freq``). 967 968 *Example* 969 970 :: 971 972 >> A = dates('1950Q2'); 973 >> A.subperiod() 974 975 ans = 976 977 1950 978 979.. _dseries-members: 980 981The dseries class 982================= 983 984.. class:: dseries 985 986 |br| The MATLAB/Octave ``dseries`` class handles time series 987 data. As any MATLAB/Octave statements, this class can be used in a 988 Dynare’s mod file. A ``dseries`` object has six members: 989 990 :arg name: A ``nobs*1`` cell of strings or a ``nobs*p`` character 991 array, the names of the variables. 992 :arg tex: A ``nobs*1`` cell of strings or a ``nobs*p`` character 993 array, the tex names of the variables. 994 :arg dates dates: An object with ``nobs`` elements, the dates of the sample. 995 :arg double data: A ``nobs`` by ``vobs`` array, the data. 996 :arg ops: The history of operations on the variables. 997 :arg tags: The user-defined tags on the variables. 998 999 ``data``, ``name``, ``tex`` are private members. The following 1000 constructors are available: 1001 1002 .. construct:: dseries () 1003 dseries (INITIAL_DATE) 1004 1005 |br| Instantiates an empty ``dseries`` object with, if 1006 defined, an initial date given by the single element ``dates`` 1007 object *INITIAL_DATE.* 1008 1009 .. construct:: dseries (FILENAME[, INITIAL_DATE]) 1010 1011 |br| Instantiates and populates a ``dseries`` object with a 1012 data file specified by *FILENAME*, a string passed as 1013 input. Valid file types are ``.m``, ``.mat``, ``.csv`` and 1014 ``.xls/.xlsx`` (Octave only supports ``.xlsx`` files and the 1015 `io <https://octave.sourceforge.io/io/>`__ package from 1016 Octave-Forge must be installed). The extension of the file 1017 should be explicitly provided. A typical ``.m`` file will have 1018 the following form:: 1019 1020 FREQ__ = 4; 1021 INIT__ = '1994Q3'; 1022 NAMES__ = {'azert';'yuiop'}; 1023 TEX__ = {'azert';'yuiop'}; 1024 TAGS__ = struct() 1025 DATA__ = {} 1026 1027 azert = randn(100,1); 1028 yuiop = randn(100,1); 1029 1030 If a ``.mat`` file is used instead, it should provide the same 1031 informations, except that the data should not be given as a 1032 set of vectors, but as a single matrix of doubles named 1033 ``DATA__``. This array should have as many columns as elements 1034 in ``NAMES__`` (the number of variables). Note that the 1035 ``INIT__`` variable can be either a ``dates`` object or a 1036 string which could be used to instantiate the same ``dates`` 1037 object. If ``INIT__`` is not provided in the ``.mat`` or 1038 ``.m`` file, the initial is by default set equal to 1039 ``dates('1Y')``. If a second input argument is passed to the 1040 constructor, ``dates`` object *INITIAL_DATE*, the initial date 1041 defined in *FILENAME* is reset to *INITIAL_DATE*. This is 1042 typically usefull if ``INIT__`` is not provided in the data 1043 file. 1044 1045 .. construct:: dseries (DATA_MATRIX[,INITIAL_DATE[,LIST_OF_NAMES[,TEX_NAMES]]]) 1046 dseries (DATA_MATRIX[,RANGE_OF_DATES[,LIST_OF_NAMES[,TEX_NAMES]]]) 1047 1048 |br| If the data is not read from a file, it can be provided 1049 via a :math:`T \times N` matrix as the first argument to 1050 ``dseries`` ’ constructor, with :math:`T` representing the 1051 number of observations on :math:`N` variables. The optional 1052 second argument, *INITIAL_DATE*, can be either a ``dates`` 1053 object representing the period of the first observation or a 1054 string which would be used to instantiate a ``dates`` 1055 object. Its default value is ``dates('1Y')``. The optional 1056 third argument, *LIST_OF_NAMES*, is a :math:`N \times 1` cell 1057 of strings with one entry for each variable name. The default 1058 name associated with column ``i`` of *DATA_MATRIX* is 1059 ``Variable_i``. The final argument, *TEX_NAMES*, is a :math:`N 1060 \times 1` cell of strings composed of the LaTeX names 1061 associated with the variables. The default LaTeX name 1062 associated with column ``i`` of *DATA_MATRIX* is 1063 ``Variable\_i``. If the optional second input argument is a 1064 range of dates, ``dates`` object *RANGE_OF_DATES*, the number 1065 of rows in the first argument must match the number of 1066 elements *RANGE_OF_DATES* or be equal to one (in which case 1067 the single observation is replicated). 1068 1069 .. construct:: dseries (TABLE) 1070 1071 Creates a ``dseries`` object given the MATLAB Table provided as the sole 1072 argument. It is assumed that the first column of the table contains the 1073 dates of the ``dseries`` and the first row contains the names. This 1074 feature is not available under Octave or MATLAB R2013a or earlier. 1075 1076 *Example* 1077 1078 Various ways to create a ``dseries`` object:: 1079 1080 do1 = dseries(1999Q3); 1081 do2 = dseries('filename.csv'); 1082 do3 = dseries([1; 2; 3], 1999Q3, {'var123'}, {'var_{123}'}); 1083 1084 >> do1 = dseries(dates('1999Q3')); 1085 >> do2 = dseries('filename.csv'); 1086 >> do3 = dseries([1; 2; 3], dates('1999Q3'), {'var123'}, {'var_{123}'}); 1087 1088 1089 One can easily create subsamples from a ``dseries`` object using 1090 the overloaded parenthesis operator. If ``ds`` is a ``dseries`` 1091 object with :math:`T` observations and ``d`` is a ``dates`` object 1092 with :math:`S<T` elements, such that :math:`\min(d)` is not 1093 smaller than the date associated to the first observation in 1094 ``ds`` and :math:`\max(d)` is not greater than the date associated 1095 to the last observation, then ``ds(d)`` instantiates a new 1096 ``dseries`` object containing the subsample defined by ``d``. 1097 1098 A list of the available methods, by alphabetical order, is given 1099 below. As in the previous section the in place modifications 1100 versions of the methods are postfixed with an underscore. 1101 1102 1103 .. dseriesmethod:: A = abs (B) 1104 abs_ (B) 1105 1106 |br| Overloads the ``abs()`` function for ``dseries`` 1107 objects. Returns the absolute value of the variables in 1108 dseries ``object`` ``B``. 1109 1110 *Example* 1111 1112 :: 1113 1114 >> ts0 = dseries(randn(3,2),'1973Q1',{'A1'; 'A2'},{'A_1'; 'A_2'}); 1115 >> ts1 = ts0.abs(); 1116 >> ts0 1117 1118 ts0 is a dseries object: 1119 1120 | A1 | A2 1121 1973Q1 | -0.67284 | 1.4367 1122 1973Q2 | -0.51222 | -0.4948 1123 1973Q3 | 0.99791 | 0.22677 1124 1125 >> ts1 1126 1127 ts1 is a dseries object: 1128 1129 | abs(A1) | abs(A2) 1130 1973Q1 | 0.67284 | 1.4367 1131 1973Q2 | 0.51222 | 0.4948 1132 1973Q3 | 0.99791 | 0.22677 1133 1134 1135 .. dseriesmethod:: [A, B] = align (A, B) 1136 align_ (A, B) 1137 1138 If ``dseries`` objects ``A`` and ``B`` are defined on 1139 different time ranges, this function extends ``A`` and/or 1140 ``B`` with NaNs so that they are defined on the same time 1141 range. Note that both ``dseries`` objects must have the same 1142 frequency. 1143 1144 *Example* 1145 1146 :: 1147 1148 >> ts0 = dseries(rand(5,1),dates('2000Q1')); % 2000Q1 -> 2001Q1 1149 >> ts1 = dseries(rand(3,1),dates('2000Q4')); % 2000Q4 -> 2001Q2 1150 >> [ts0, ts1] = align(ts0, ts1); % 2000Q1 -> 2001Q2 1151 >> ts0 1152 1153 ts0 is a dseries object: 1154 1155 | Variable_1 1156 2000Q1 | 0.81472 1157 2000Q2 | 0.90579 1158 2000Q3 | 0.12699 1159 2000Q4 | 0.91338 1160 2001Q1 | 0.63236 1161 2001Q2 | NaN 1162 1163 >> ts1 1164 1165 ts1 is a dseries object: 1166 1167 | Variable_1 1168 2000Q1 | NaN 1169 2000Q2 | NaN 1170 2000Q3 | NaN 1171 2000Q4 | 0.66653 1172 2001Q1 | 0.17813 1173 2001Q2 | 0.12801 1174 1175 >> ts0 = dseries(rand(5,1),dates('2000Q1')); % 2000Q1 -> 2001Q1 1176 >> ts1 = dseries(rand(3,1),dates('2000Q4')); % 2000Q4 -> 2001Q2 1177 >> align_(ts0, ts1); % 2000Q1 -> 2001Q2 1178 >> ts1 1179 1180 ts1 is a dseries object: 1181 1182 | Variable_1 1183 2000Q1 | NaN 1184 2000Q2 | NaN 1185 2000Q3 | NaN 1186 2000Q4 | 0.66653 1187 2001Q1 | 0.17813 1188 2001Q2 | 0.12801 1189 1190 1191 .. dseriesmethod:: C = backcast (A, B[, diff]) 1192 backcast_ (A, B[, diff]) 1193 1194 Backcasts ``dseries`` object ``A`` with ``dseries`` object B's 1195 growth rates (except if the last optional argument, ``diff``, 1196 is true in which case first differences are used). Both 1197 ``dseries`` objects must have the same frequency. 1198 1199 1200 .. dseriesmethod:: B = baxter_king_filter (A, hf, lf, K) 1201 baxter_king_filter_ (A, hf, lf, K) 1202 1203 |br| Implementation of the *Baxter and King* (1999) band pass 1204 filter for ``dseries`` objects. This filter isolates business 1205 cycle fluctuations with a period of length ranging between 1206 ``hf`` (high frequency) to ``lf`` (low frequency) using a 1207 symmetric moving average smoother with :math:`2K+1` points, so 1208 that :math:`K` observations at the beginning and at the end of 1209 the sample are lost in the computation of the filter. The 1210 default value for ``hf`` is ``6``, for ``lf`` is ``32``, and 1211 for ``K`` is ``12``. 1212 1213 *Example* 1214 1215 :: 1216 1217 % Simulate a component model (stochastic trend, deterministic 1218 % trend, and a stationary autoregressive process). 1219 e = 0.2*randn(200,1); 1220 u = randn(200,1); 1221 stochastic_trend = cumsum(e); 1222 deterministic_trend = .1*transpose(1:200); 1223 x = zeros(200,1); 1224 for i=2:200 1225 x(i) = .75*x(i-1) + u(i); 1226 end 1227 y = x + stochastic_trend + deterministic_trend; 1228 1229 % Instantiates time series objects. 1230 ts0 = dseries(y,'1950Q1'); 1231 ts1 = dseries(x,'1950Q1'); % stationary component. 1232 1233 % Apply the Baxter-King filter. 1234 ts2 = ts0.baxter_king_filter(); 1235 1236 % Plot the filtered time series. 1237 plot(ts1(ts2.dates).data,'-k'); % Plot of the stationary component. 1238 hold on 1239 plot(ts2.data,'--r'); % Plot of the filtered y. 1240 hold off 1241 axis tight 1242 id = get(gca,'XTick'); 1243 set(gca,'XTickLabel',strings(ts1.dates(id))); 1244 1245 1246 .. dseriesmethod:: B = center (A[, geometric]) 1247 center_ (A[, geometric]) 1248 1249 |br| Centers variables in ``dseries`` object ``A`` around their 1250 arithmetic means, except if the optional argument ``geometric`` 1251 is set equal to ``true`` in which case all the variables are 1252 divided by their geometric means. 1253 1254 1255 .. dseriesmethod:: C = chain (A, B) 1256 chain_ (A, B) 1257 1258 |br| Merge two ``dseries`` objects along the time 1259 dimension. The two objects must have the same number of 1260 observed variables, and the initial date in ``B`` must not be 1261 posterior to the last date in ``A``. The returned ``dseries`` 1262 object, ``C``, is built by extending ``A`` with the cumulated 1263 growth factors of ``B``. 1264 1265 *Example* 1266 1267 :: 1268 1269 >> ts = dseries([1; 2; 3; 4],dates(`1950Q1')) 1270 1271 ts is a dseries object: 1272 1273 | Variable_1 1274 1950Q1 | 1 1275 1950Q2 | 2 1276 1950Q3 | 3 1277 1950Q4 | 4 1278 1279 >> us = dseries([3; 4; 5; 6],dates(`1950Q3')) 1280 1281 us is a dseries object: 1282 1283 | Variable_1 1284 1950Q3 | 3 1285 1950Q4 | 4 1286 1951Q1 | 5 1287 1951Q2 | 6 1288 1289 >> chain(ts, us) 1290 1291 ans is a dseries object: 1292 1293 | Variable_1 1294 1950Q1 | 1 1295 1950Q2 | 2 1296 1950Q3 | 3 1297 1950Q4 | 4 1298 1951Q1 | 5 1299 1951Q2 | 6 1300 1301 1302 .. dseriesmethod:: [error_flag, message ] = check (A) 1303 1304 |br| Sanity check of ``dseries`` object ``A``. Returns ``1`` 1305 if there is an error, ``0`` otherwise. The second output 1306 argument is a string giving brief informations about the 1307 error. 1308 1309 1310 .. dseriesmethod:: B = copy (A) 1311 1312 |br| Returns a copy of ``A``. If an inplace modification method 1313 is applied to ``A``, object ``B`` will not be affected. Note 1314 that if ``A`` is assigned to ``C``, ``C = A``, then any in 1315 place modification method applied to ``A`` will change ``C``. 1316 1317 *Example* 1318 1319 :: 1320 1321 >> a = dseries(randn(5,1)) 1322 1323 a is a dseries object: 1324 1325 | Variable_1 1326 1Y | -0.16936 1327 2Y | -1.1451 1328 3Y | -0.034331 1329 4Y | -0.089042 1330 5Y | -0.66997 1331 1332 >> b = copy(a); 1333 >> c = a; 1334 >> a.abs(); 1335 >> a.abs_(); 1336 >> a 1337 1338 a is a dseries object: 1339 1340 | Variable_1 1341 1Y | 0.16936 1342 2Y | 1.1451 1343 3Y | 0.034331 1344 4Y | 0.089042 1345 5Y | 0.66997 1346 1347 >> b 1348 1349 b is a dseries object: 1350 1351 | Variable_1 1352 1Y | -0.16936 1353 2Y | -1.1451 1354 3Y | -0.034331 1355 4Y | -0.089042 1356 5Y | -0.66997 1357 1358 >> c 1359 1360 c is a dseries object: 1361 1362 | Variable_1 1363 1Y | 0.16936 1364 2Y | 1.1451 1365 3Y | 0.034331 1366 4Y | 0.089042 1367 5Y | 0.66997 1368 1369 1370 .. dseriesmethod:: B = cumprod (A[, d[, v]]) 1371 cumprod_ (A[, d[, v]]) 1372 1373 |br| Overloads the MATLAB/Octave ``cumprod`` function for 1374 ``dseries`` objects. The cumulated product cannot be computed 1375 if the variables in ``dseries`` object ``A`` have NaNs. If a 1376 ``dates`` object ``d`` is provided as a second argument, then 1377 the method computes the cumulated product with the additional 1378 constraint that the variables in the ``dseries`` object ``B`` 1379 are equal to one in period ``d``. If a single-observation 1380 ``dseries`` object ``v`` is provided as a third argument, the 1381 cumulated product in ``B`` is normalized such that ``B(d)`` 1382 matches ``v`` (``dseries`` objects ``A`` and ``v`` must have 1383 the same number of variables). 1384 1385 *Example* 1386 1387 :: 1388 1389 >> ts1 = dseries(2*ones(7,1)); 1390 >> ts2 = ts1.cumprod(); 1391 >> ts2 1392 1393 ts2 is a dseries object: 1394 1395 | cumprod(Variable_1) 1396 1Y | 2 1397 2Y | 4 1398 3Y | 8 1399 4Y | 16 1400 5Y | 32 1401 6Y | 64 1402 7Y | 128 1403 1404 >> ts3 = ts1.cumprod(dates('3Y')); 1405 >> ts3 1406 1407 ts3 is a dseries object: 1408 1409 | cumprod(Variable_1) 1410 1Y | 0.25 1411 2Y | 0.5 1412 3Y | 1 1413 4Y | 2 1414 5Y | 4 1415 6Y | 8 1416 7Y | 16 1417 1418 >> ts4 = ts1.cumprod(dates('3Y'),dseries(pi)); 1419 >> ts4 1420 1421 ts4 is a dseries object: 1422 1423 | cumprod(Variable_1) 1424 1Y | 0.7854 1425 2Y | 1.5708 1426 3Y | 3.1416 1427 4Y | 6.2832 1428 5Y | 12.5664 1429 6Y | 25.1327 1430 7Y | 50.2655 1431 1432 1433 .. dseriesmethod:: B = cumsum (A[, d[, v]]) 1434 cumsum (A[, d[, v]]) 1435 1436 |br| Overloads the MATLAB/Octave ``cumsum`` function for 1437 ``dseries`` objects. The cumulated sum cannot be computed if 1438 the variables in ``dseries`` object ``A`` have NaNs. If a 1439 ``dates`` object ``d`` is provided as a second argument, then 1440 the method computes the cumulated sum with the additional 1441 constraint that the variables in the ``dseries`` object ``B`` 1442 are zero in period ``d``. If a single observation ``dseries`` 1443 object ``v`` is provided as a third argument, the cumulated 1444 sum in ``B`` is such that ``B(d)`` matches ``v`` (``dseries`` 1445 objects ``A`` and ``v`` must have the same number of 1446 variables). 1447 1448 *Example* 1449 1450 :: 1451 1452 >> ts1 = dseries(ones(10,1)); 1453 >> ts2 = ts1.cumsum(); 1454 >> ts2 1455 1456 ts2 is a dseries object: 1457 1458 | cumsum(Variable_1) 1459 1Y | 1 1460 2Y | 2 1461 3Y | 3 1462 4Y | 4 1463 5Y | 5 1464 6Y | 6 1465 7Y | 7 1466 8Y | 8 1467 9Y | 9 1468 10Y | 10 1469 1470 >> ts3 = ts1.cumsum(dates('3Y')); 1471 >> ts3 1472 1473 ts3 is a dseries object: 1474 1475 | cumsum(Variable_1) 1476 1Y | -2 1477 2Y | -1 1478 3Y | 0 1479 4Y | 1 1480 5Y | 2 1481 6Y | 3 1482 7Y | 4 1483 8Y | 5 1484 9Y | 6 1485 10Y | 7 1486 1487 >> ts4 = ts1.cumsum(dates('3Y'),dseries(pi)); 1488 >> ts4 1489 1490 ts4 is a dseries object: 1491 1492 | cumsum(Variable_1) 1493 1Y | 1.1416 1494 2Y | 2.1416 1495 3Y | 3.1416 1496 4Y | 4.1416 1497 5Y | 5.1416 1498 6Y | 6.1416 1499 7Y | 7.1416 1500 8Y | 8.1416 1501 9Y | 9.1416 1502 10Y | 10.1416 1503 1504 1505 .. dseriesmethod:: B = detrend (A, m) 1506 dentrend_ (A, m) 1507 1508 |br| Detrends ``dseries`` object ``A`` with a fitted 1509 polynomial of order ``m``. Note that each variable is 1510 detrended with a different polynomial. 1511 1512 1513 .. dseriesmethod:: B = diff (A) 1514 diff_ (A) 1515 1516 |br| Returns the first difference of ``dseries`` object ``A``. 1517 1518 1519 .. datesmethod:: disp (A) 1520 1521 |br| Overloads the MATLAB/Octave disp function for ``dseries`` object. 1522 1523 1524 .. datesmethod:: display (A) 1525 1526 |br| Overloads the MATLAB/Octave display function for 1527 ``dseries`` object. ``display`` is the function called by 1528 MATLAB to print the content of an object if a semicolon is 1529 missing at the end of a MATLAB statement. If the ``dseries`` 1530 object is defined over a too large time span, only the first 1531 and last periods will be printed. If the ``dseries`` object 1532 contains too many variables, only the first and last variables 1533 will be printed. If all the periods and variables are 1534 required, the ``disp`` method should be used instead. 1535 1536 1537 .. dseriesmethod:: C = eq (A, B) 1538 1539 |br| Overloads the MATLAB/Octave ``eq`` (equal, ``==``) 1540 operator. ``dseries`` objects ``A`` and ``B`` must have the 1541 same number of observations (say, :math:`T`) and variables 1542 (:math:`N`). The returned argument is a :math:`T \times N` 1543 matrix of logicals. Element :math:`(i,j)` of ``C`` is 1544 equal to ``true`` if and only if observation :math:`i` for 1545 variable :math:`j` in ``A`` and ``B`` are the same. 1546 1547 *Example* 1548 1549 :: 1550 1551 >> ts0 = dseries(2*ones(3,1)); 1552 >> ts1 = dseries([2; 0; 2]); 1553 >> ts0==ts1 1554 1555 ans = 1556 1557 3x1 logical array 1558 1559 1 1560 0 1561 1 1562 1563 1564 .. dseriesmethod:: l = exist (A, varname) 1565 1566 |br| Tests if variable ``varname`` exists in ``dseries`` object ``A``. Returns 1567 ``true`` iff variable exists in ``A``. 1568 1569 *Example* 1570 1571 :: 1572 1573 >> ts = dseries(randn(100,1)); 1574 >> ts.exist('Variable_1') 1575 1576 ans = 1577 1578 logical 1579 1580 1 1581 1582 >> ts.exist('Variable_2') 1583 1584 ans = 1585 1586 logical 1587 1588 0 1589 1590 1591 .. dseriesmethod:: B = exp (A) 1592 exp_ (A) 1593 1594 |br| Overloads the MATLAB/Octave ``exp`` function for 1595 ``dseries`` objects. 1596 1597 *Example* 1598 1599 :: 1600 1601 >> ts0 = dseries(rand(10,1)); 1602 >> ts1 = ts0.exp(); 1603 1604 1605 .. dseriesmethod:: C = extract (A, B[, ...]) 1606 1607 |br| Extracts some variables from a ``dseries`` object ``A`` 1608 and returns a ``dseries`` object ``C``. The input arguments 1609 following ``A`` are strings representing the variables to be 1610 selected in the new ``dseries`` object ``C``. To simplify the 1611 creation of sub-objects, the ``dseries`` class overloads the 1612 curly braces (``D = extract (A, B, C)`` is equivalent to ``D = 1613 A{B,C}``) and allows implicit loops (defined between a pair of 1614 ``@`` symbol, see examples below) or MATLAB/Octave’s regular 1615 expressions (introduced by square brackets). 1616 1617 *Example* 1618 1619 The following selections are equivalent:: 1620 1621 >> ts0 = dseries(ones(100,10)); 1622 >> ts1 = ts0{'Variable_1','Variable_2','Variable_3'}; 1623 >> ts2 = ts0{'Variable_@1,2,3@'}; 1624 >> ts3 = ts0{'Variable_[1-3]$'}; 1625 >> isequal(ts1,ts2) && isequal(ts1,ts3) 1626 1627 ans = 1628 1629 logical 1630 1631 1 1632 1633 It is possible to use up to two implicit loops to select variables:: 1634 1635 names = {'GDP_1';'GDP_2';'GDP_3'; 'GDP_4'; 'GDP_5'; 'GDP_6'; 'GDP_7'; 'GDP_8'; ... 1636 'GDP_9'; 'GDP_10'; 'GDP_11'; 'GDP_12'; ... 1637 'HICP_1';'HICP_2';'HICP_3'; 'HICP_4'; 'HICP_5'; 'HICP_6'; 'HICP_7'; 'HICP_8'; ... 1638 'HICP_9'; 'HICP_10'; 'HICP_11'; 'HICP_12'}; 1639 1640 ts0 = dseries(randn(4,24),dates('1973Q1'),names); 1641 ts0{'@GDP,HICP@_@1,3,5@'} 1642 1643 ans is a dseries object: 1644 1645 | GDP_1 | GDP_3 | GDP_5 | HICP_1 | HICP_3 | HICP_5 1646 1973Q1 | 1.7906 | -1.6606 | -0.57716 | 0.60963 | -0.52335 | 0.26172 1647 1973Q2 | 2.1624 | 3.0125 | 0.52563 | 0.70912 | -1.7158 | 1.7792 1648 1973Q3 | -0.81928 | 1.5008 | 1.152 | 0.2798 | 0.88568 | 1.8927 1649 1973Q4 | -0.03705 | -0.35899 | 0.85838 | -1.4675 | -2.1666 | -0.62032 1650 1651 1652 .. dseriesmethod:: f = firstdate (A) 1653 1654 |br| Returns the first period in ``dseries`` object ``A``. 1655 1656 1657 .. dseriesmethod:: f = firstobservedperiod (A) 1658 1659 |br| Returns the first period where all the variables in ``dseries`` object ``A`` are observed (non NaN). 1660 1661 1662 .. dseriesmethod:: f = frequency (B) 1663 1664 |br| Returns the frequency of the variables in ``dseries`` object ``B``. 1665 1666 *Example* 1667 1668 :: 1669 1670 >> ts = dseries(randn(3,2),'1973Q1'); 1671 >> ts.frequency 1672 1673 ans = 1674 1675 4 1676 1677 1678 .. dseriesmethod:: D = horzcat (A, B[, ...]) 1679 1680 |br| Overloads the ``horzcat`` MATLAB/Octave’s method for 1681 ``dseries`` objects. Returns a ``dseries`` object ``D`` 1682 containing the variables in ``dseries`` objects passed as 1683 inputs: ``A, B, ...`` If the inputs are not defined on the 1684 same time ranges, the method adds NaNs to the variables so 1685 that the variables are redefined on the smallest common time 1686 range. Note that the names in the ``dseries`` objects passed 1687 as inputs must be different and these objects must have common 1688 frequency. 1689 1690 *Example* 1691 1692 :: 1693 1694 >> ts0 = dseries(rand(5,2),'1950Q1',{'nifnif';'noufnouf'}); 1695 >> ts1 = dseries(rand(7,1),'1950Q3',{'nafnaf'}); 1696 >> ts2 = [ts0, ts1]; 1697 >> ts2 1698 1699 ts2 is a dseries object: 1700 1701 | nifnif | noufnouf | nafnaf 1702 1950Q1 | 0.17404 | 0.71431 | NaN 1703 1950Q2 | 0.62741 | 0.90704 | NaN 1704 1950Q3 | 0.84189 | 0.21854 | 0.83666 1705 1950Q4 | 0.51008 | 0.87096 | 0.8593 1706 1951Q1 | 0.16576 | 0.21184 | 0.52338 1707 1951Q2 | NaN | NaN | 0.47736 1708 1951Q3 | NaN | NaN | 0.88988 1709 1951Q4 | NaN | NaN | 0.065076 1710 1952Q1 | NaN | NaN | 0.50946 1711 1712 1713 .. dseriesmethod:: B = hpcycle (A[, lambda]) 1714 hpcycle_ (A[, lambda]) 1715 1716 |br| Extracts the cycle component from a ``dseries`` ``A`` 1717 object using the *Hodrick and Prescott (1997)* filter and 1718 returns a ``dseries`` object, ``B``. The default value for 1719 ``lambda``, the smoothing parameter, is ``1600``. 1720 1721 *Example* 1722 1723 :: 1724 1725 % Simulate a component model (stochastic trend, deterministic 1726 % trend, and a stationary autoregressive process). 1727 e = 0.2*randn(200,1); 1728 u = randn(200,1); 1729 stochastic_trend = cumsum(e); 1730 deterministic_trend = .1*transpose(1:200); 1731 x = zeros(200,1); 1732 for i=2:200 1733 x(i) = .75*x(i-1) + u(i); 1734 end 1735 y = x + stochastic_trend + deterministic_trend; 1736 1737 % Instantiates time series objects. 1738 ts0 = dseries(y,'1950Q1'); 1739 ts1 = dseries(x,'1950Q1'); % stationary component. 1740 1741 % Apply the HP filter. 1742 ts2 = ts0.hpcycle(); 1743 1744 % Plot the filtered time series. 1745 plot(ts1(ts2.dates).data,'-k'); % Plot of the stationary component. 1746 hold on 1747 plot(ts2.data,'--r'); % Plot of the filtered y. 1748 hold off 1749 axis tight 1750 id = get(gca,'XTick'); 1751 set(gca,'XTickLabel',strings(ts.dates(id))); 1752 1753 1754 .. dseriesmethod:: B = hptrend (A[, lambda]) 1755 hptrend_ (A[, lambda]) 1756 1757 |br| Extracts the trend component from a ``dseries`` A object 1758 using the *Hodrick and Prescott (1997)* filter and returns a 1759 ``dseries`` object, ``B``. Default value for ``lambda``, the 1760 smoothing parameter, is ``1600``. 1761 1762 *Example* 1763 1764 :: 1765 1766 % Using the same generating data process 1767 % as in the previous example: 1768 1769 ts1 = dseries(stochastic_trend + deterministic_trend,'1950Q1'); 1770 % Apply the HP filter. 1771 ts2 = ts0.hptrend(); 1772 1773 % Plot the filtered time series. 1774 plot(ts1.data,'-k'); % Plot of the nonstationary components. 1775 hold on 1776 plot(ts2.data,'--r'); % Plot of the estimated trend. 1777 hold off 1778 axis tight 1779 id = get(gca,'XTick'); 1780 set(gca,'XTickLabel',strings(ts0.dates(id))); 1781 1782 1783 .. dseriesmethod:: C = insert (A, B, I) 1784 1785 |br| Inserts variables contained in ``dseries`` object ``B`` 1786 in ``dseries`` object ``A`` at positions specified by integer 1787 scalars in vector ``I``, returns augmented ``dseries`` object 1788 ``C``. The integer scalars in ``I`` must take values between 1789 `` and ``A.length()+1`` and refers to ``A`` ’s column 1790 numbers. The ``dseries`` objects ``A`` and ``B`` need not be 1791 defined over the same time ranges, but it is assumed that they 1792 have common frequency. 1793 1794 *Example* 1795 1796 :: 1797 1798 >> ts0 = dseries(ones(2,4),'1950Q1',{'Sly'; 'Gobbo'; 'Sneaky'; 'Stealthy'}); 1799 >> ts1 = dseries(pi*ones(2,1),'1950Q1',{'Noddy'}); 1800 >> ts2 = ts0.insert(ts1,3) 1801 1802 ts2 is a dseries object: 1803 1804 | Sly | Gobbo | Noddy | Sneaky | Stealthy 1805 1950Q1 | 1 | 1 | 3.1416 | 1 | 1 1806 1950Q2 | 1 | 1 | 3.1416 | 1 | 1 1807 1808 >> ts3 = dseries([pi*ones(2,1) sqrt(pi)*ones(2,1)],'1950Q1',{'Noddy';'Tessie Bear'}); 1809 >> ts4 = ts0.insert(ts1,[3, 4]) 1810 1811 ts4 is a dseries object: 1812 1813 | Sly | Gobbo | Noddy | Sneaky | Tessie Bear | Stealthy 1814 1950Q1 | 1 | 1 | 3.1416 | 1 | 1.7725 | 1 1815 1950Q2 | 1 | 1 | 3.1416 | 1 | 1.7725 | 1 1816 1817 1818 .. dseriesmethod:: B = isempty (A) 1819 1820 |br| Overloads the MATLAB/octave’s ``isempty`` function. Returns 1821 ``true`` if ``dseries`` object ``A`` is empty. 1822 1823 1824 .. dseriesmethod:: C = isequal (A, B) 1825 1826 |br| Overloads the MATLAB/octave’s ``isequal`` function. Returns 1827 ``true`` if ``dseries`` objects ``A`` and ``B`` are identical. 1828 1829 1830 .. dseriesmethod:: C = isinf (A) 1831 1832 |br| Overloads the MATLAB/octave’s ``isinf`` function. Returns 1833 a logical array, with element ``(i,j)`` equal to ``true`` if and 1834 only if variable ``j`` is finite in period ``A.dates(i)``. 1835 1836 1837 .. dseriesmethod:: C = isnan (A) 1838 1839 |br| Overloads the MATLAB/octave’s ``isnan`` function. Returns 1840 a logical array, with element ``(i,j)`` equal to ``true`` if and 1841 only if variable ``j`` isn't NaN in period ``A.dates(i)``. 1842 1843 1844 .. dseriesmethod:: C = isreal (A) 1845 1846 |br| Overloads the MATLAB/octave’s ``isreal`` function. Returns 1847 a logical array, with element ``(i,j)`` equal to ``true`` if and 1848 only if variable ``j`` is real in period ``A.dates(i)``. 1849 1850 1851 .. dseriesmethod:: B = lag (A[, p]) 1852 lag_ (A[, p]) 1853 1854 |br| Returns lagged time series. Default value of integer scalar ``p``, the number 1855 of lags, is ``1``. 1856 1857 *Example* 1858 1859 :: 1860 1861 >> ts0 = dseries(transpose(1:4), '1950Q1') 1862 1863 ts0 is a dseries object: 1864 1865 | Variable_1 1866 1950Q1 | 1 1867 1950Q2 | 2 1868 1950Q3 | 3 1869 1950Q4 | 4 1870 1871 >> ts1 = ts0.lag() 1872 1873 ts1 is a dseries object: 1874 1875 | Variable_1 1876 1950Q1 | NaN 1877 1950Q2 | 1 1878 1950Q3 | 2 1879 1950Q4 | 3 1880 1881 >> ts2 = ts0.lag(2) 1882 1883 ts2 is a dseries object: 1884 1885 | Variable_1 1886 1950Q1 | NaN 1887 1950Q2 | NaN 1888 1950Q3 | 1 1889 1950Q4 | 2 1890 1891 % dseries class overloads the parenthesis 1892 % so that ts.lag(p) can be written more 1893 % compactly as ts(-p). For instance: 1894 1895 >> ts0.lag(1) 1896 1897 ans is a dseries object: 1898 1899 | Variable_1 1900 1950Q1 | NaN 1901 1950Q2 | 1 1902 1950Q3 | 2 1903 1950Q4 | 3 1904 1905 or alternatively:: 1906 1907 >> ts0(-1) 1908 1909 ans is a dseries object: 1910 1911 | Variable_1 1912 1950Q1 | NaN 1913 1950Q2 | 1 1914 1950Q3 | 2 1915 1950Q4 | 3 1916 1917 1918 .. dseriesmethod:: l = lastdate (B) 1919 1920 |br| Returns the last period in ``dseries`` object ``B``. 1921 1922 *Example* 1923 1924 :: 1925 1926 >> ts = dseries(randn(3,2),'1973Q1'); 1927 >> ts.lastdate() 1928 1929 ans = <dates: 1973Q3> 1930 1931 1932 .. dseriesmethod:: f = lastobservedperiod (A) 1933 1934 |br| Returns the last period where all the variables in ``dseries`` object ``A`` are observed (non NaN). 1935 1936 1937 .. dseriesmethod:: B = lead (A[, p]) 1938 lead_ (A[, p]) 1939 1940 |br| Returns lead time series. Default value of integer scalar 1941 ``p``, the number of leads, is ``1``. As in the ``lag`` 1942 method, the ``dseries`` class overloads the parenthesis so 1943 that ``ts.lead(p)`` is equivalent to ``ts(p)``. 1944 1945 *Example* 1946 1947 :: 1948 1949 >> ts0 = dseries(transpose(1:4),'1950Q1'); 1950 >> ts1 = ts0.lead() 1951 1952 ts1 is a dseries object: 1953 1954 | Variable_1 1955 1950Q1 | 2 1956 1950Q2 | 3 1957 1950Q3 | 4 1958 1950Q4 | NaN 1959 1960 >> ts2 = ts0(2) 1961 1962 ts2 is a dseries object: 1963 1964 | Variable_1 1965 1950Q1 | 3 1966 1950Q2 | 4 1967 1950Q3 | NaN 1968 1950Q4 | NaN 1969 1970 *Remark* 1971 1972 The overloading of the parenthesis for ``dseries`` objects, 1973 allows to easily create new ``dseries`` objects by 1974 copying/pasting equations declared in the ``model`` block. For 1975 instance, if an Euler equation is defined in the ``model`` 1976 block:: 1977 1978 model; 1979 ... 1980 1/C - beta/C(1)*(exp(A(1))*K^(alpha-1)+1-delta) ; 1981 ... 1982 end; 1983 1984 and if variables ``, ``A`` and ``K`` are defined as 1985 ``dseries`` objects, then by writing:: 1986 1987 Residuals = 1/C - beta/C(1)*(exp(A(1))*K^(alpha-1)+1-delta) ; 1988 1989 outside of the ``model`` block, we create a new ``dseries`` 1990 object, called ``Residuals``, for the residuals of the Euler 1991 equation (the conditional expectation of the equation defined 1992 in the ``model`` block is zero, but the residuals are non 1993 zero). 1994 1995 1996 .. dseriesmethod:: B = lineartrend (A) 1997 1998 |br| Returns a linear trend centered on 0, the length of the 1999 trend is given by the size of ``dseries`` object ``A`` (the 2000 number of periods). 2001 2002 *Example* 2003 2004 :: 2005 2006 >> ts = dseries(ones(3,1)); 2007 >> ts.lineartrend() 2008 2009 ans = 2010 2011 -1 2012 0 2013 1 2014 2015 2016 .. dseriesmethod:: B = log (A) 2017 log_ (A) 2018 2019 |br| Overloads the MATLAB/Octave ``log`` function for 2020 ``dseries`` objects. 2021 2022 *Example* 2023 2024 :: 2025 2026 >> ts0 = dseries(rand(10,1)); 2027 >> ts1 = ts0.log(); 2028 2029 .. dseriesmethod:: B = mdiff (A) 2030 mdiff_ (A) 2031 2032 |br| Computes monthly growth rates of variables in 2033 ``dseries`` object ``A``. 2034 2035 2036 .. dseriesmethod:: B = mean (A[, geometric]) 2037 2038 |br| Overloads the MATLAB/Octave ``mean`` function for 2039 ``dseries`` objects. Returns the mean of each variable in 2040 ``dseries`` object ``A``. If the second argument is ``true`` 2041 the geometric mean is computed, otherwise (default) the 2042 arithmetic mean is reported. 2043 2044 2045 .. dseriesmethod:: C = merge (A, B[, legacy]) 2046 2047 |br| Merges two ``dseries`` objects ``A`` and ``B`` in 2048 ``dseries`` object ``C``. Objects ``A`` and ``B`` need to have 2049 common frequency but can be defined on different time 2050 ranges. If a variable, say ``x``, is defined both in 2051 ``dseries`` objects ``A`` and ``B``, then the ``merge`` will 2052 select the variable ``x`` as defined in the second input 2053 argument, ``B``, except for the NaN elements in ``B`` if 2054 corresponding elements in ``A`` (ie same periods) are well 2055 defined numbers. This behaviour can be changed by setting the 2056 optional argument ``legacy`` equal to true, in which case the 2057 second variable overwrites the first one even if the second 2058 variable has NaNs. 2059 2060 *Example* 2061 2062 :: 2063 2064 >> ts0 = dseries(rand(3,2),'1950Q1',{'A1';'A2'}) 2065 2066 ts0 is a dseries object: 2067 2068 | A1 | A2 2069 1950Q1 | 0.96284 | 0.5363 2070 1950Q2 | 0.25145 | 0.31866 2071 1950Q3 | 0.34447 | 0.4355 2072 2073 >> ts1 = dseries(rand(3,1),'1950Q2',{'A1'}) 2074 2075 ts1 is a dseries object: 2076 2077 | A1 2078 1950Q2 | 0.40161 2079 1950Q3 | 0.81763 2080 1950Q4 | 0.97769 2081 2082 >> merge(ts0,ts1) 2083 2084 ans is a dseries object: 2085 2086 | A1 | A2 2087 1950Q1 | 0.96284 | 0.5363 2088 1950Q2 | 0.40161 | 0.31866 2089 1950Q3 | 0.81763 | 0.4355 2090 1950Q4 | 0.97769 | NaN 2091 2092 >> merge(ts1,ts0) 2093 2094 ans is a dseries object: 2095 2096 | A1 | A2 2097 1950Q1 | 0.96284 | 0.5363 2098 1950Q2 | 0.25145 | 0.31866 2099 1950Q3 | 0.34447 | 0.4355 2100 1950Q4 | 0.97769 | NaN 2101 2102 2103 .. dseriesmethod:: C = minus (A, B) 2104 2105 |br| Overloads the MATLAB/Octave ``minus`` (``-``) operator 2106 for ``dseries`` objects, element by element subtraction. If 2107 both ``A`` and ``B`` are ``dseries`` objects, they do not need 2108 to be defined over the same time ranges. If ``A`` and ``B`` 2109 are ``dseries`` objects with :math:`T_A` and :math:`T_B` 2110 observations and :math:`N_A` and :math:`N_B` variables, then 2111 :math:`N_A` must be equal to :math:`N_B` or :math:`1` and 2112 :math:`N_B` must be equal to :math:`N_A` or :math:`1`. If 2113 :math:`T_A=T_B`, ``isequal(A.init,B.init)`` returns ``1`` and 2114 :math:`N_A=N_B`, then the ``minus`` operator will compute for 2115 each couple :math:`(t,n)`, with :math:`1\le t\le T_A` and 2116 :math:`1\le n\le N_A`, 2117 ``C.data(t,n)=A.data(t,n)-B.data(t,n)``. If :math:`N_B` is 2118 equal to :math:`1` and :math:`N_A>1`, the smaller ``dseries`` 2119 object (``B``) is “broadcast” across the larger ``dseries`` 2120 (``A``) so that they have compatible shapes, the ``minus`` 2121 operator will subtract the variable defined in ``B`` from each 2122 variable in ``A``. If ``B`` is a double scalar, then the 2123 method ``minus`` will subtract ``B`` from all the 2124 observations/variables in ``A``. If ``B`` is a row vector of 2125 length :math:`N_A`, then the ``minus`` method will subtract 2126 ``B(i)`` from all the observations of variable ``i``, for 2127 :math:`i=1,...,N_A`. If ``B`` is a column vector of length 2128 :math:`T_A`, then the ``minus`` method will subtract ``B`` 2129 from all the variables. 2130 2131 *Example* 2132 2133 :: 2134 2135 >> ts0 = dseries(rand(3,2)); 2136 >> ts1 = ts0{'Variable_2'}; 2137 >> ts0-ts1 2138 2139 ans is a dseries object: 2140 2141 | Variable_1 | Variable_2 2142 1Y | -0.48853 | 0 2143 2Y | -0.50535 | 0 2144 3Y | -0.32063 | 0 2145 2146 >> ts1 2147 2148 ts1 is a dseries object: 2149 2150 | Variable_2 2151 1Y | 0.703 2152 2Y | 0.75415 2153 3Y | 0.54729 2154 2155 >> ts1-ts1.data(1) 2156 2157 ans is a dseries object: 2158 2159 | Variable_2 2160 1Y | 0 2161 2Y | 0.051148 2162 3Y | -0.15572 2163 2164 >> ts1.data(1)-ts1 2165 2166 ans is a dseries object: 2167 2168 | Variable_2 2169 1Y | 0 2170 2Y | -0.051148 2171 3Y | 0.15572 2172 2173 2174 .. dseriesmethod:: C = mpower (A, B) 2175 2176 |br| Overloads the MATLAB/Octave ``mpower`` (``^``) operator for ``dseries`` 2177 objects and computes element-by-element power. ``A`` is a 2178 ``dseries`` object with ``N`` variables and ``T`` 2179 observations. If ``B`` is a real scalar, then ``mpower(A,B)`` 2180 returns a ``dseries`` object ``C`` with 2181 ``C.data(t,n)=A.data(t,n)^C``. If ``B`` is a ``dseries`` 2182 object with ``N`` variables and ``T`` observations then 2183 ``mpower(A,B)`` returns a ``dseries`` object ``C`` with 2184 ``C.data(t,n)=A.data(t,n)^C.data(t,n)``. 2185 2186 *Example* 2187 2188 :: 2189 2190 >> ts0 = dseries(transpose(1:3)); 2191 >> ts1 = ts0^2 2192 2193 ts1 is a dseries object: 2194 2195 | Variable_1 2196 1Y | 1 2197 2Y | 4 2198 3Y | 9 2199 2200 >> ts2 = ts0^ts0 2201 2202 ts2 is a dseries object: 2203 2204 | Variable_1 2205 1Y | 1 2206 2Y | 4 2207 3Y | 27 2208 2209 2210 .. dseriesmethod:: C = mrdivide (A, B) 2211 2212 |br| Overloads the MATLAB/Octave ``mrdivide`` (``/``) operator for 2213 ``dseries`` objects, element by element division (like the 2214 ``./`` MATLAB/Octave operator). If both ``A`` and ``B`` are 2215 ``dseries`` objects, they do not need to be defined over the 2216 same time ranges. If ``A`` and ``B`` are ``dseries`` objects 2217 with :math:`T_A` and :math:`T_B` observations and :math:`N_A` 2218 and :math:`N_B` variables, then :math:`N_A` must be equal to 2219 :math:`N_B` or :math:`1` and :math:`N_B` must be equal to 2220 :math:`N_A` or :math:`1`. If :math:`T_A=T_B`, 2221 ``isequal(A.init,B.init)`` returns ``1`` and :math:`N_A=N_B`, 2222 then the ``mrdivide`` operator will compute for each couple 2223 :math:`(t,n)`, with :math:`1\le t\le T_A` and :math:`1\le n\le 2224 N_A`, ``C.data(t,n)=A.data(t,n)/B.data(t,n)``. If :math:`N_B` 2225 is equal to :math:`1` and :math:`N_A>1`, the smaller 2226 ``dseries`` object (``B``) is “broadcast” across the larger 2227 ``dseries`` (``A``) so that they have compatible shapes. In 2228 this case the ``mrdivide`` operator will divide each variable 2229 defined in A by the variable in B, observation per 2230 observation. If B is a double scalar, then ``mrdivide`` will 2231 divide all the observations/variables in ``A`` by ``B``. If 2232 ``B`` is a row vector of length :math:`N_A`, then ``mrdivide`` 2233 will divide all the observations of variable ``i`` by 2234 ``B(i)``, for :math:`i=1,...,N_A`. If ``B`` is a column vector 2235 of length :math:`T_A`, then ``mrdivide`` will perform a 2236 division of all the variables by ``B``, element by element. 2237 2238 *Example* 2239 2240 :: 2241 2242 >> ts0 = dseries(rand(3,2)) 2243 2244 ts0 is a dseries object: 2245 2246 | Variable_1 | Variable_2 2247 1Y | 0.72918 | 0.90307 2248 2Y | 0.93756 | 0.21819 2249 3Y | 0.51725 | 0.87322 2250 2251 >> ts1 = ts0{'Variable_2'}; 2252 >> ts0/ts1 2253 2254 ans is a dseries object: 2255 2256 | Variable_1 | Variable_2 2257 1Y | 0.80745 | 1 2258 2Y | 4.2969 | 1 2259 3Y | 0.59235 | 1 2260 2261 2262 .. dseriesmethod:: C = mtimes (A, B) 2263 2264 |br| Overloads the MATLAB/Octave ``mtimes`` (``*``) operator 2265 for ``dseries`` objects and the Hadammard product (the .* 2266 MATLAB/Octave operator). If both ``A`` and ``B`` are 2267 ``dseries`` objects, they do not need to be defined over the 2268 same time ranges. If ``A`` and ``B`` are ``dseries`` objects 2269 with :math:`T_A` and :math:`_B` observations and :math:`N_A` 2270 and :math:`N_B` variables, then :math:`N_A` must be equal to 2271 :math:`N_B` or :math:`1` and :math:`N_B` must be equal to 2272 :math:`N_A` or :math:`1`. If :math:`T_A=T_B`, 2273 ``isequal(A.init,B.init)`` returns ``1`` and :math:`N_A=N_B`, 2274 then the ``mtimes`` operator will compute for each couple 2275 :math:`(t,n)`, with :math:`1\le t\le T_A` and :math:`1\le n\le 2276 N_A`, ``C.data(t,n)=A.data(t,n)*B.data(t,n)``. If :math:`N_B` 2277 is equal to :math:`1` and :math:`N_A>1`, the smaller 2278 ``dseries`` object (``B``) is “broadcast” across the larger 2279 ``dseries`` (``A``) so that they have compatible shapes, 2280 ``mtimes`` operator will multiply each variable defined in 2281 ``A`` by the variable in ``B``, observation per 2282 observation. If ``B`` is a double scalar, then the method 2283 ``mtimes`` will multiply all the observations/variables in 2284 ``A`` by ``B``. If ``B`` is a row vector of length 2285 :math:`N_A`, then the ``mtimes`` method will multiply all the 2286 observations of variable ``i`` by ``B(i)``, for 2287 :math:`i=1,...,N_A`. If ``B`` is a column vector of length 2288 :math:`T_A`, then the ``mtimes`` method will perform a 2289 multiplication of all the variables by ``B``, element by 2290 element. 2291 2292 2293 .. dseriesmethod:: B = nanmean (A[, geometric]) 2294 2295 |br| Overloads the MATLAB/Octave ``nanmean`` function for 2296 ``dseries`` objects. Returns the mean of each variable in 2297 ``dseries`` object ``A`` ignoring the NaN values. If the 2298 second argument is ``true`` the geometric mean is computed, 2299 otherwise (default) the arithmetic mean is reported. 2300 2301 2302 .. dseriesmethod:: C = ne (A, B) 2303 2304 |br| Overloads the MATLAB/Octave ``ne`` (not equal, ``~=``) 2305 operator. ``dseries`` objects ``A`` and ``B`` must have the 2306 same number of observations (say, :math:`T`) and variables 2307 (:math:`N`). The returned argument is a :math:`T` by :math:`N` 2308 matrix of zeros and ones. Element :math:`(i,j)` of ``C`` is 2309 equal to ``1`` if and only if observation :math:`i` for 2310 variable :math:`j` in ``A`` and ``B`` are not equal. 2311 2312 *Example* 2313 2314 :: 2315 2316 >> ts0 = dseries(2*ones(3,1)); 2317 >> ts1 = dseries([2; 0; 2]); 2318 >> ts0~=ts1 2319 2320 ans = 2321 2322 3x1 logical array 2323 2324 0 2325 1 2326 0 2327 2328 2329 .. dseriesmethod:: B = nobs (A) 2330 2331 |br| Returns the number of observations in ``dseries`` object 2332 ``A``. 2333 2334 *Example* 2335 2336 :: 2337 2338 >> ts0 = dseries(randn(10)); 2339 >> ts0.nobs 2340 2341 ans = 2342 2343 10 2344 2345 2346 .. dseriesmethod:: B = onesidedhpcycle (A[, lambda[, init]]) 2347 onesidedhpcycle_ (A[, lambda[, init]]) 2348 2349 |br| Extracts the cycle component from a ``dseries`` ``A`` 2350 object using a one sided HP filter (with a Kalman filter) and 2351 returns a ``dseries`` object, ``B``. The default value for 2352 ``lambda``, the smoothing parameter, is ``1600``. By default, 2353 if ``ìnit`` is not provided, the initial value is based on the 2354 first two observations. 2355 2356 2357 .. dseriesmethod:: B = onesidedhptrend (A[, lambda[, init]]) 2358 onesidedhptrend_ (A[, lambda[, init]]) 2359 2360 |br| Extracts the trend component from a ``dseries`` ``A`` 2361 object using a one sided HP filter (with a Kalman filter) and 2362 returns a ``dseries`` object, ``B``. The default value for 2363 ``lambda``, the smoothing parameter, is ``1600``. By default, 2364 if ``ìnit`` is not provided, the initial value is based on the 2365 first two observations. 2366 2367 2368 .. dseriesmethod:: h = plot (A) 2369 h = plot (A, B) 2370 h = plot (A[, ...]) 2371 h = plot (A, B[, ...]) 2372 2373 |br| Overloads MATLAB/Octave’s ``plot`` function for 2374 ``dseries`` objects. Returns a MATLAB/Octave plot handle, that 2375 can be used to modify the properties of the plotted time 2376 series. If only one ``dseries`` object, ``A``, is passed as 2377 argument, then the plot function will put the associated dates 2378 on the x-abscissa. If this ``dseries`` object contains only 2379 one variable, additional arguments can be passed to modify the 2380 properties of the plot (as one would do with the 2381 MATLAB/Octave’s version of the plot function). If ``dseries`` 2382 object ``A`` contains more than one variable, it is not 2383 possible to pass these additional arguments and the properties 2384 of the plotted time series must be modified using the returned 2385 plot handle and the MATLAB/Octave ``set`` function (see 2386 example below). If two ``dseries`` objects, ``A`` and ``B``, 2387 are passed as input arguments, the plot function will plot the 2388 variables in ``A`` against the variables in ``B`` (the number 2389 of variables in each object must be the same otherwise an 2390 error is issued). Again, if each object contains only one 2391 variable, additional arguments can be passed to modify the 2392 properties of the plotted time series, otherwise the 2393 MATLAB/Octave ``set`` command has to be used. 2394 2395 *Example* 2396 2397 Define a ``dseries`` object with two variables (named by 2398 default ``Variable_1`` and ``Variable_2``):: 2399 2400 >> ts = dseries(randn(100,2),'1950Q1'); 2401 2402 The following command will plot the first variable in ``ts``:: 2403 2404 >> plot(ts{'Variable_1'},'-k','linewidth',2); 2405 2406 The next command will draw all the variables in ``ts`` on 2407 the same figure:: 2408 2409 >> h = plot(ts); 2410 2411 If one wants to modify the properties of the plotted time 2412 series (line style, colours, ...), the set function can be 2413 used (see MATLAB’s documentation):: 2414 2415 >> set(h(1),'-k','linewidth',2); 2416 >> set(h(2),'--r'); 2417 2418 The following command will plot ``Variable_1`` against 2419 ``exp(Variable_1)``:: 2420 2421 >> plot(ts{'Variable_1'},ts{'Variable_1'}.exp(),'ok'); 2422 2423 Again, the properties can also be modified using the 2424 returned plot handle and the ``set`` function:: 2425 2426 >> h = plot(ts, ts.exp()); 2427 >> set(h(1),'ok'); 2428 >> set(h(2),'+r'); 2429 2430 2431 .. dseriesmethod:: C = plus (A, B) 2432 2433 |br| Overloads the MATLAB/Octave ``plus`` (``+``) operator for 2434 ``dseries`` objects, element by element addition. If both 2435 ``A`` and ``B`` are ``dseries`` objects, they do not need to 2436 be defined over the same time ranges. If ``A`` and ``B`` are 2437 ``dseries`` objects with :math:`T_A` and :math:`T_B` 2438 observations and :math:`N_A` and :math:`N_B` variables, then 2439 :math:`N_A` must be equal to :math:`N_B` or :math:`1` and 2440 :math:`N_B` must be equal to :math:`N_A` or :math:`1`. If 2441 :math:`T_A=T_B`, ``isequal(A.init,B.init)`` returns ``1`` and 2442 :math:`N_A=N_B`, then the ``plus`` operator will compute for 2443 each couple :math:`(t,n)`, with :math:`1\le t\le T_A` and 2444 :math:`1\le n\le N_A`, 2445 ``C.data(t,n)=A.data(t,n)+B.data(t,n)``. If :math:`N_B` is 2446 equal to :math:`1` and :math:`N_A>1`, the smaller ``dseries`` 2447 object (``B``) is “broadcast” across the larger ``dseries`` 2448 (``A``) so that they have compatible shapes, the plus operator 2449 will add the variable defined in ``B`` to each variable in 2450 ``A``. If ``B`` is a double scalar, then the method ``plus`` 2451 will add ``B`` to all the observations/variables in ``A``. If 2452 ``B`` is a row vector of length :math:`N_A`, then the ``plus`` 2453 method will add ``B(i)`` to all the observations of variable 2454 ``i``, for :math:`i=1,...,N_A`. If ``B`` is a column vector of 2455 length :math:`T_A`, then the ``plus`` method will add ``B`` to 2456 all the variables. 2457 2458 2459 .. dseriesmethod:: C = pop (A[, B]) 2460 pop_ (A[, B]) 2461 2462 |br| Removes variable ``B`` from ``dseries`` object ``A``. By 2463 default, if the second argument is not provided, the last 2464 variable is removed. 2465 2466 *Example* 2467 2468 :: 2469 2470 >> ts0 = dseries(ones(3,3)); 2471 >> ts1 = ts0.pop('Variable_2'); 2472 2473 ts1 is a dseries object: 2474 2475 | Variable_1 | Variable_3 2476 1Y | 1 | 1 2477 2Y | 1 | 1 2478 3Y | 1 | 1 2479 2480 2481 .. dseriesmethod:: B = qdiff (A) 2482 B = qgrowth (A) 2483 qdiff_ (A) 2484 qgrowth_ (A) 2485 2486 |br| Computes quarterly differences or growth rates. 2487 2488 *Example* 2489 2490 :: 2491 2492 >> ts0 = dseries(transpose(1:4),'1950Q1'); 2493 >> ts1 = ts0.qdiff() 2494 2495 ts1 is a dseries object: 2496 2497 | Variable_1 2498 1950Q1 | NaN 2499 1950Q2 | 1 2500 1950Q3 | 1 2501 1950Q4 | 1 2502 2503 >> ts0 = dseries(transpose(1:6),'1950M1'); 2504 >> ts1 = ts0.qdiff() 2505 2506 ts1 is a dseries object: 2507 2508 | Variable_1 2509 1950M1 | NaN 2510 1950M2 | NaN 2511 1950M3 | NaN 2512 1950M4 | 3 2513 1950M5 | 3 2514 1950M6 | 3 2515 2516 2517 .. dseriesmethod:: C = remove (A, B) 2518 remove_ (A, B) 2519 2520 |br| Alias for the ``pop`` method with two arguments. Removes 2521 variable ``B`` from ``dseries`` object ``A``. 2522 2523 *Example* 2524 2525 :: 2526 2527 >> ts0 = dseries(ones(3,3)); 2528 >> ts1 = ts0.remove('Variable_2'); 2529 2530 ts1 is a dseries object: 2531 2532 | Variable_1 | Variable_3 2533 1Y | 1 | 1 2534 2Y | 1 | 1 2535 3Y | 1 | 1 2536 2537 A shorter syntax is available: ``remove(ts,'Variable_2')`` 2538 is equivalent to ``ts{'Variable_2'} = []`` (``[]`` can be 2539 replaced by any empty object). This alternative syntax is 2540 useful if more than one variable has to be removed. For 2541 instance:: 2542 2543 ts{'Variable_@2,3,4@'} = []; 2544 2545 will remove ``Variable_2``, ``Variable_3`` and 2546 ``Variable_4`` from ``dseries`` object ``ts`` (if these 2547 variables exist). Regular expressions cannot be used but 2548 implicit loops can. 2549 2550 2551 .. dseriesmethod:: B = rename (A, oldname, newname) 2552 rename_ (A, oldname, newname) 2553 2554 |br| Rename variable ``oldname`` to ``newname`` in ``dseries`` 2555 object ``A``. Returns a ``dseries`` object. If more than one 2556 variable needs to be renamed, it is possible to pass cells of 2557 char arrays as second and third arguments. 2558 2559 *Example* 2560 2561 :: 2562 2563 >> ts0 = dseries(ones(2,2)); 2564 >> ts1 = ts0.rename('Variable_1','Stinkly') 2565 2566 ts1 is a dseries object: 2567 2568 | Stinkly | Variable_2 2569 1Y | 1 | 1 2570 2Y | 1 | 1 2571 2572 2573 .. dseriesmethod:: C = rename (A, newname) 2574 rename_ (A, newname) 2575 2576 |br| Replace the names in ``A`` with those passed in the cell 2577 string array ``newname``. ``newname`` must have the same 2578 number of elements as ``dseries`` object ``A`` has 2579 variables. Returns a ``dseries`` object. 2580 2581 *Example* 2582 2583 :: 2584 2585 >> ts0 = dseries(ones(2,3)); 2586 >> ts1 = ts0.rename({'TinkyWinky','Dipsy','LaaLaa'}) 2587 2588 ts1 is a dseries object: 2589 2590 | TinkyWinky | Dipsy | LaaLaa 2591 1Y | 1 | 1 | 1 2592 2Y | 1 | 1 | 1 2593 2594 2595 .. dseriesmethod:: save (A, basename[, format]) 2596 2597 |br| Overloads the MATLAB/Octave ``save`` function and saves 2598 ``dseries`` object ``A`` to disk. Possible formats are ``mat`` 2599 (this is the default), ``m`` (MATLAB/Octave script), and 2600 ``csv`` (MATLAB binary data file). The name of the file 2601 without extension is specified by ``basename``. 2602 2603 *Example* 2604 2605 :: 2606 2607 >> ts0 = dseries(ones(2,2)); 2608 >> ts0.save('ts0', 'csv'); 2609 2610 The last command will create a file ts0.csv with the 2611 following content:: 2612 2613 ,Variable_1,Variable_2 2614 1Y, 1, 1 2615 2Y, 1, 1 2616 2617 To create a MATLAB/Octave script, the following command:: 2618 2619 >> ts0.save('ts0','m'); 2620 2621 will produce a file ts0.m with the following content:: 2622 2623 % File created on 14-Nov-2013 12:08:52. 2624 2625 FREQ__ = 1; 2626 INIT__ = ' 1Y'; 2627 2628 NAMES__ = {'Variable_1'; 'Variable_2'}; 2629 TEX__ = {'Variable_{1}'; 'Variable_{2}'}; 2630 OPS__ = {}; 2631 TAGS__ = struct(); 2632 2633 Variable_1 = [ 2634 1 2635 1]; 2636 2637 Variable_2 = [ 2638 1 2639 1]; 2640 2641 The generated (``csv``, ``m``, or ``mat``) files can be 2642 loaded when instantiating a ``dseries`` object as 2643 explained above. 2644 2645 2646 .. dseriesmethod:: B = set_names(A, s1, s2, ...) 2647 2648 |br| Renames variables in ``dseries`` object ``A`` and returns 2649 a ``dseries`` object ``B`` with new names ``s1``, ``s2``, 2650 ... The number of input arguments after the first one 2651 (``dseries`` object ``A``) must be equal to ``A.vobs`` (the 2652 number of variables in ``A``). ``s1`` will be the name of the 2653 first variable in ``B``, ``s2`` the name of the second 2654 variable in ``B``, and so on. 2655 2656 *Example* 2657 2658 :: 2659 2660 >> ts0 = dseries(ones(1,3)); 2661 >> ts1 = ts0.set_names('Barbibul',[],'Barbouille') 2662 2663 ts1 is a dseries object: 2664 2665 | Barbibul | Variable_2 | Barbouille 2666 1Y | 1 | 1 | 1 2667 2668 2669 .. dseriesmethod:: [T, N ] = size(A[, dim]) 2670 2671 Overloads the MATLAB/Octave’s ``size`` function. Returns the 2672 number of observations in ``dseries`` object ``A`` 2673 (i.e. ``A.nobs``) and the number of variables 2674 (i.e. ``A.vobs``). If a second input argument is passed, the 2675 ``size`` function returns the number of observations if 2676 ``dim=1`` or the number of variables if ``dim=2`` (for all 2677 other values of ``dim`` an error is issued). 2678 2679 *Example* 2680 2681 :: 2682 2683 >> ts0 = dseries(ones(1,3)); 2684 >> ts0.size() 2685 2686 ans = 2687 2688 1 3 2689 2690 2691 .. dseriesmethod:: B = std (A[, geometric]) 2692 2693 |br| Overloads the MATLAB/Octave ``std`` function for 2694 ``dseries`` objects. Returns the standard deviation of each 2695 variable in ``dseries`` object ``A``. If the second argument 2696 is ``true`` the geometric standard deviation is computed 2697 (default value of the second argument is ``false``). 2698 2699 2700 .. dseriesmethod:: A = tag (A, a[, b, c]) 2701 2702 |br| Add a tag to a variable in ``dseries`` object ``A``. 2703 2704 *Example* 2705 2706 :: 2707 2708 >> ts = dseries(randn(10, 3)); 2709 >> tag(ts, 'type'); % Define a tag name. 2710 >> tag(ts, 'type', 'Variable_1', 'Stock'); 2711 >> tag(ts, 'type', 'Variable_2', 'Flow'); 2712 >> tag(ts, 'type', 'Variable_3', 'Stock'); 2713 2714 2715 .. dseriesmethod:: B = tex_rename (A, name, newtexname) 2716 B = tex_rename (A, newtexname) 2717 tex_rename_ (A, name, newtexname) 2718 tex_rename_ (A, newtexname) 2719 2720 |br| Redefines the tex name of variable ``name`` to 2721 ``newtexname`` in ``dseries`` object ``A``. Returns a 2722 ``dseries`` object. 2723 2724 With only two arguments ``A`` and ``newtexname``, it redefines 2725 the tex names of the ``A`` to those contained in 2726 ``newtexname``. Here, ``newtexname`` is a cell string array 2727 with the same number of entries as variables in ``A``. 2728 2729 2730 .. dseriesmethod:: B = uminus(A) 2731 2732 |br| Overloads ``uminus`` (``-``, unary minus) for ``dseries`` 2733 object. 2734 2735 *Example* 2736 2737 :: 2738 2739 >> ts0 = dseries(1) 2740 2741 ts0 is a dseries object: 2742 2743 | Variable_1 2744 1Y | 1 2745 2746 >> ts1 = -ts0 2747 2748 ts1 is a dseries object: 2749 2750 | Variable_1 2751 1Y | -1 2752 2753 2754 .. dseriesmethod:: D = vertcat (A, B[, ...]) 2755 2756 |br| Overloads the ``vertcat`` MATLAB/Octave method for 2757 ``dseries`` objects. This method is used to append more 2758 observations to a ``dseries`` object. Returns a ``dseries`` 2759 object ``D`` containing the variables in ``dseries`` objects 2760 passed as inputs. All the input arguments must be ``dseries`` 2761 objects with the same variables defined on different time 2762 ranges. 2763 2764 *Example* 2765 2766 :: 2767 2768 >> ts0 = dseries(rand(2,2),'1950Q1',{'nifnif';'noufnouf'}); 2769 >> ts1 = dseries(rand(2,2),'1950Q3',{'nifnif';'noufnouf'}); 2770 >> ts2 = [ts0; ts1] 2771 2772 ts2 is a dseries object: 2773 2774 | nifnif | noufnouf 2775 1950Q1 | 0.82558 | 0.31852 2776 1950Q2 | 0.78996 | 0.53406 2777 1950Q3 | 0.089951 | 0.13629 2778 1950Q4 | 0.11171 | 0.67865 2779 2780 2781 .. dseriesmethod:: B = vobs (A) 2782 2783 |br| Returns the number of variables in ``dseries`` object 2784 ``A``. 2785 2786 *Example* 2787 2788 :: 2789 2790 >> ts0 = dseries(randn(10,2)); 2791 >> ts0.vobs 2792 2793 ans = 2794 2795 2 2796 2797 2798.. dseriesmethod:: B = ydiff (A) 2799 B = ygrowth (A) 2800 ydiff_ (A) 2801 ygrowth_ (A) 2802 2803 |br| Computes yearly differences or growth rates. 2804