1. Time Series and Data Management
1.1. Dates
In the RISE toolbox, dates play a crucial role in representing time series data. Dates can be either explicit, where each observation is associated with a specific date, or undated, where dates are simply represented as a sequence of integers.
To handle dates efficiently, RISE provides an abstract class
called rise_dates.dates, from which various derived classes
inherit. These derived classes include:
rise_dates.DailyDate(shortcut:rd)rise_dates.WeeklyDate(shortcut:rw)rise_dates.MonthlyDate(shortcut:rm)rise_dates.QuarterlyDate(shortcut:rq)rise_dates.HalfYearlyDate(shortcut:rh)rise_dates.YearlyDate(shortcuts:ryorra)
Each derived class represents a specific frequency.
1.1.1. Base Class Methods
The base class rise_dates.dates provides several methods that
can be used with any derived class:
char()– converts dates to character representations.convert()– converts dates to another frequency.datestr()– returns a string representation of dates.eq()– equality check.gt(),ge(),lt(),le()– comparisons.ismember()– membership test.min(),max()– minimum / maximum date.ne()– inequality check.unique()– unique dates in a sequence.colon()– creates a sequence of dates.double()– converts dates to double format.intersect()– intersection of two sets of dates.minus(),plus()– date arithmetic.ymd()– extracts year, month, day components.
When passing a date to an estimation option (estim_start_date,
estim_end_date, …), use date2serial to convert the char
form to the numeric / rise_dates.dates form the modern
validators accept:
estim_start_date = date2serial('1990Q1')
1.1.2. Help Text for Derived Classes
Daily dates: rd
RD DailyDate constructor.
Usage:
- obj = rd(year, month, dayOfTheMonth) creates a
rd object for the specified year, month, and day.
- obj = rd(year, dayOfTheYear) creates a rd
object for the specified year and day of the year.
- obj = rd(dateString) creates a rd object from
a string in the format ‘mm/dd/yyyy’ or ‘yyyyDddd’ or ‘yyyy-mm-dd’.
- obj = rd(dateNumber) creates a rd object from
a serial date number.
Inputs:
year: Year of the date.
month: Month of the date.
dayOfTheMonth: Day of the month.
dayOfTheYear: Day of the year.
dateString: A string in the format ‘mm/dd/yyyy’ or ‘yyyyDddd’.
dateNumber: A serial date number representing the date.
Example:
dateObj = rd(2023, 7, 15);
dateObj = rd(2023, 165);
dateObj = rd(‘07/15/2023’);
dateObj = rd(‘2023D165’);
dateObj = rd(737999);
See also rd, rw, rm, rq, rh, ra, ry
Weekly dates: rw
RW constructor.
Usage:
obj = rw(year, fullWeeks)
obj = rw(dateString)
obj = rw(datenumber)
Inputs:
year: Year of the date.
fullWeeks: Number of full weeks.
dateString: A string in the format ‘mm/dd/yyyy’ or ‘yyyyWp’ or ‘yyyy-mm-dd’.
Example:
dateObj = rw(2023, 10);
dateObj = rw(‘07/01/2023’);
dateObj = rw(‘1990W1’);
dateObj = rw(737999);
See also rd, rm, rq, rh, ra, ry
Monthly dates: rm
RM constructor.
Usage:
obj = rm(year, month)
obj = rm(dateString)
obj = rm(datenumber)
Inputs:
year: Year of the date.
month: Month of the date (1 to 12).
dateString: A string in the format ‘mm/dd/yyyy’ or ‘yyyy-mm-dd’.
datenumber: regular date number
Example:
dateObj = rm(2023, 7);
dateObj = rm(‘07/01/2023’);
dateObj = rm(737999);
See also rd, rw, rq, rh, ra, ry
Quarterly dates: rq
RQ constructor.
Usage:
obj = rq(year, quarter)
obj = rq(dateString)
obj = rq(datenumber)
Inputs:
year: Year of the date.
quarter: Quarter of the date (1, 2, 3, or 4).
dateString: A string in the format ‘mm/dd/yyyy’ or ‘yyyyQp’ where p=1,2,3,4 or ‘yyyy-mm-dd’
Example:
dateObj = rq(2023, 2);
dateObj = rq(‘2023Q2’);
dateObj = rq(‘04/01/2023’);
dateObj = rq(737999);
See also rd, rw, rm, rh, ra, ry
Half-yearly dates: rh
RH constructor.
Usage:
obj = rh(year, semi)
obj = rh(dateString)
obj = rh(datenumber)
Inputs:
year: The year of the date.
semi: The semi-annual period (1 or 2).
dateString: A string in the format ‘mm/dd/yyyy’ or ‘yyyyHp’ where p=1,2 or ‘yyyy-mm-dd’.
datenumber: regular date number
Example:
dateObj = rh(2023, 1);
dateObj = rh(‘2023H1’);
dateObj = rh(‘01/01/2023’);
dateObj = rh(737999);
See also rd, rw, rm, rq, ra, ry
Yearly dates: ry
RY constructor for YearlyDate.
Usage:
obj = ry(year)
obj = ry(dateString)
dateObj = ry(datenumber);
Inputs:
year: Year of the date in double (e.g., 2023)
dateString: A string in the format ‘mm/dd/yyyy’ or ‘yyyy’ or ‘yyyy-mm-dd’
datenumber: A regular matlab datenumber. Note that the function will treat the input as a date number if it has more than 4 digits. A warning will be issued as well
Example:
dateObj = ry(2023);
dateObj = ry(‘2023’);
dateObj = ry(‘01/01/2023’);
dateObj = ry(737999);
See also rd, rw, rm, rq, rh, ra.
Annual dates: ra
RA constructor for YearlyDate.
Usage:
obj = ra(year)
obj = ra(dateString)
dateObj = ra(datenumber);
Inputs:
year: Year of the date in double (e.g., 2023)
dateString: A string in the format ‘mm/dd/yyyy’ or ‘yyyy’ or ‘yyyy-mm-dd’
datenumber: A regular matlab datenumber. Note that the function will treat the input as a date number if it has more than 4 digits. A warning will be issued as well
Example:
dateObj = ra(2023);
dateObj = ra(‘2023’);
dateObj = ra(‘01/01/2023’);
dateObj = ra(737999);
See also rd, rw, rm, rq, rh, ry
1.2. Time Series
This section provides information about time series and their usage in the context of the RISE toolbox.
Time series data in essence is just a matrix, so in theory one
can just use matrices to represent the data. However, all
practitioners will share their frustration in trying to remember
the index location of the GDP and the annoyance in trying to
find out what data(:, 5) written by a co-worker represents.
The RISE toolbox addresses this problem by providing a time
series object that uses natural indices, improving readability
and reducing errors.
To use the time series object, initialize it with:
db = ts('1990q1', randn(10, 4), {'gdp','r','wage','capital'})
The first argument specifies the starting date of the time series and its frequency (here, 1990Q1). The second argument is the data matrix, where each row represents a time period and each column represents a variable. The third argument provides the natural names of the variables for intuitive indexing.
If you want to provide descriptions or comments for each variable:
db = ts('1990q1', randn(10, 2), {'gdp','pi'}, {'real gdp','inflation rate'})
You can display the time series with:
disp(db)
Alternatively, set variable names and descriptions with set:
set(db, 'varnames', {'gdp','pi'}, 'description', {'real gdp','inflation rate'})
1.2.1. Indexing and assignment
The indexing surface of the time series object mirrors the
built-in table / timetable conventions, so that users
familiar with those classes feel at home, and the distinction
between “sub-time-series” and “raw values” is explicit.
Expression |
Result |
|---|---|
|
a property of the ts ( |
|
if |
|
a sub-time-series (returns a ts). |
|
the raw numeric block at that selection (a double array of size |
|
(dated ts only, |
|
replace one variable’s column from a ts or a numeric column. |
|
replace a sub-time-series (rhs ts or numeric). |
|
raw numeric block write. |
Scalar-numeric assignment (db{-1} = X, db(-1) = X) is
not supported. The time-shift shortcut is read-only; build the
shifted ts first and assign with a date or logical selector if
you need to write into it.
Examples:
db = ts('1990q1', randn(10, 4), {'gdp','r','wage','capital'});
% Access values
db.wage % single-variable ts
db('wage') % same, sub-ts form
db{'wage'} % raw 10x1 double array
% Slice rows and columns
db('1991q2', 'wage') % single observation, as a ts
db{'1991q2', 'wage'} % the same value as a 1x1 double
db('1990q2:1991q2', {'gdp','wage'}) % sub-ts (5 rows, 2 vars)
db{:, {'gdp','wage'}} % full sample, two vars, as a 10x2 double
% Whole-year selection works across frequencies
db(ry(1991)) % the 4 quarters of 1991, as a ts
% Underlying data, when you need plain MATLAB
values(db) % equivalent to db.data
Time shifts (lags and leads) are expressed either with the
explicit methods lag(db, k), lead(db, k), shift(db, k)
or, on a dated ts, with the brace/paren shortcut. Both preserve
the date axis – the leading or trailing k observations are
NaN-padded so that the length of the output equals the length of
the input. The two forms are equivalent on a dated ts:
growth = 100*(db.gdp / lag(db.gdp, 1) - 1); % q/q growth, % terms
growth = 100*(db.gdp / db.gdp{-1} - 1); % same thing, shorter
On an undated ts the shortcut is unavailable (a scalar numeric in
the braces is treated as the date value itself); use lag,
lead, shift explicitly there.
The time series object seamlessly integrates with other parts of the RISE toolbox, enabling you to perform VAR and DSGE analyses effortlessly.
1.2.2. Data Cleaning
reset_data– resets the data in the time series object.reset_start_date– resets the start date.interpolate– fills in missing data.aggregate– aggregates data to a coarser frequency.dummy– creates a dummy variable.step_dummy– creates a step-dummy variable.cat– joins multiple time series objects.
1.2.3. Time Series Transformations
hpfilter– the Hodrick-Prescott filter.ma_filter– a moving-average filter.pdecomp– parametric trend-seasonal-residual decomposition.npdecomp– non-parametric trend-seasonal-residual decomposition.transform– standard time-series transformations (level, growth, difference, log change, year-over-year variants), following the Haver mnemonics.
1.2.4. Time shifts
These methods preserve the date axis – the leading or trailing
k rows are NaN-padded so that length(out) == length(db):
lag(db, k)– lag byk.out.data(t,:,:) = db.data(t-k,:,:).lead(db, k)– lead byk.out.data(t,:,:) = db.data(t+k,:,:).shift(db, k)– generic shift. Positivekis a lead, negative is a lag.
On a dated ts these are also available as the shortcut
db{-k} / db(-k) (lag) and db{+k} / db(+k) (lead) –
see Indexing and assignment above.
1.2.5. Statistical Analysis
regress– OLS regression on the time series data.chowlin– temporal disaggregation via Chow-Lin (interpolates a low-frequency series to high frequency using one or more related indicators).jbtest– Jarque-Bera test.
1.2.6. Plotting tools for time series
bar– bar plot.fanchart– fan chart.plot– plot the time series data.plot_real_time– plot in real-time-conditioning format.plotyy– plot with two separate axes.
See Plotting tools for the broader plotting surface.