3. Plotting tools

RISE ships a number of plotting helpers that fall into three groups:

  • Time-series plotters – methods on the ts class (plot, fanchart, plot_decomp) and the corresponding standalone routines that consume their output.

  • Model plotters – one-call convenience methods on dsge / VAR objects (quick_irfs, quick_plots, plot_probabilities, plot_data_against_probabilities).

  • Decorations and layout – shaded recession bands, super-labels across subplot grids, x-tick rotation, multi-panel layout helpers, date-tick handling.

Plus a save-figure utility and the default figure / print settings applied automatically by rise_startup.

3.1. The myplot wrapper

utils.plot.myplot is the central plotting routine that every ts-aware method calls into (ts.plot, ts.bar, ts.area, ts.errorbar, …). It wraps an arbitrary plot function and adds:

  • automatic handling of ts inputs (multi-column, multi-page);

  • date-aware x-axis (frequency-specific tick labels via plot_specs);

  • optional date-range filtering (pass a dates range as the first positional argument);

  • log-scale toggles and other RISE-specific options.

The user rarely calls myplot directly; it surfaces through ts methods. Knowing it exists explains why ts.plot(...) accepts extras that bare plot does not.

3.2. Time-series plotters

3.2.1. Fan charts

Two-step process:

  1. Build the fan data from a ts object that holds either pages or columns (not both):

    data = fanchart(myts, ci);

    ci is a vector of confidence levels in [0, 1] or [0, 100]. The returned struct has fields ci, median, variance, quantiles, prob_index, probs.

  2. Plot it:

    plot_fanchart(data)
plot_fanchart(data, MainColor)
plot_fanchart(data, MainColor, nticks)
hh = plot_fanchart(...)

    MainColor accepts a single-character colour code ('c','b','g','r','m','k','w'), an RGB triplet, or 'nb' (the default; assumes exactly 4 quantile bands). nticks is the number of x-axis ticks (default 8).

3.2.2. Decomposition bar plots

plot_decomp stacks positive and negative contributions as bars and overlays the total as a line. The ts-method form and the standalone form coexist:

plot_decomp(ts1, ..., 'Name', Value, ...)
plot_decomp(xrange, ts1, ..., 'Name', Value, ...)

The optional xrange (e.g. rq(2020,1):rq(2022,4)) restricts the plot to a date window. Each ts argument has one column per component; the total line is the sum of the columns. Name-value pairs are forwarded to plot.

3.3. Model plotters

These take a solved model object as input and produce publication-shaped multi-panel figures with sensible defaults.

3.3.1. quick_irfs

hdl = quick_irfs(m, myirfs, var_list, shock_list, r0c0, xrange, suplab, leGend)

Lays out impulse-response panels: one figure per shock, one subplot per variable. myirfs is the structure returned by irf; var_list and shock_list filter the rows and figures; r0c0 = [rows, cols] controls the grid (default [4, 4]); xrange restricts horizons; suplab adds a super-label across the grid; leGend adds a legend.

3.3.2. quick_plots

Generic counterpart for arbitrary post-solve series (forecasts, simulations, historical decompositions). Same layout idea, same set of optional arguments (var_list, fig_title, r0c0, …). Two forms:

  • quick_plots(m, batch, ...) – as a @generic method.

  • utils.plot.quick_plots(description, batch, ...) – standalone with an explicit description struct rather than a model.

3.3.3. Smoothed probabilities

plot_probabilities(model)
plot_probabilities(model, specs, stateList, regimeList, shadeInfo, description)

For Markov-switching dsge / VAR models. Plots the smoothed probabilities of states (stateList) and / or regimes (regimeList). specs = [rows, cols] sets the grid; shadeInfo is an optional function handle (typically wrapping shade) that adds shaded bands; description is an optional struct overriding labels.

plot_data_against_probabilities(model, type, specs, shadeInfo, description)

Overlays the observed data against the smoothed state or regime probabilities. type is 'state' or 'regime', optionally with a variable list.

3.4. Decorations and layout

3.4.1. shade

shade(start_finish)
shade(start_finish, color)
shade(start_finish, color, fig)

Adds shaded vertical bands to an existing plot. start_finish is either an n x 2 matrix of date pairs or a logical ts whose true intervals define the shaded periods. Default colour is light grey [211, 211, 211] / 255. The shading respects current y-limits and sits behind plotted data; works on tiled and multi-axes figures.

3.4.2. recession_dates

r = recession_dates(F)

NBER recession periods at frequency F ('D', 'W', 'M', 'Q', 'H', 'Y'; default 'Q'). Returns a cell array of [start, end] date pairs ready to feed into shade.

3.4.3. sup_label

[ax, h] = sup_label(text, whichLabel, supAxes)
ax     = sup_label(text, whichLabel, supAxes)

Places a single title / xlabel / ylabel spanning a group of subplots (whichLabel selects which). Returns handles to the super-axis (and optionally to the text). Lifted from Ben Barrowes’ suplabel on File Exchange, with minor RISE-specific tweaks.

3.4.4. xrotate

xrotate()        % default 90 degrees
xrotate(angle)   % numeric or string

Rotates x-axis tick labels for every Cartesian axis in the current figure. Skips polar / geographic axes.

3.4.5. number_of_rows_and_columns_in_figure

[Remains, r, c] = number_of_rows_and_columns_in_figure(fig, nvar, r0, c0)

Tiles nvar variables across the current figure with up to r0 rows and c0 columns per page. Remains is what didn’t fit on this page, intended to be passed back in a loop until empty.

3.4.6. plot_specs

pp = plot_specs(serial_dates, nticks)

Computes x-axis values, tick locations and labels, and x-limits from a serial-date vector. Used internally by myplot to honour frequency-specific date formatting; useful directly only when bypassing myplot to drive a non-RISE plot routine off RISE dates.

3.5. Saving figures

3.5.1. save_figure

save_figure(figHandle, baseName, resDir)
save_figure(figHandle, baseName, resDir, nvp)

Writes a figure to disk in any combination of .fig, .png, .pdf, .svg, .jpeg, working on a temporary copy so the original figure is left untouched. By default applies a “tight” layout pass that minimises whitespace around plotted content – the result is suited to direct inclusion in LaTeX / Beamer documents without manual trimming. baseName may include a path (in which case resDir is ignored). The nvp struct controls formats, tightness, and a few other options.

3.6. Default figure and print settings

rise_startup configures MATLAB’s root-level figure paper properties so that any figure later printed picks up landscape A4 with a sensible content box. The relevant assignments:

set(0, 'DefaultFigurePaperOrientation', 'landscape');
set(0, 'DefaultFigurePaperType',        'A4');
set(0, 'DefaultFigurePaperUnits',       'centimeters');
set(0, 'DefaultFigurePaperPositionMode','manual');
set(0, 'DefaultFigurePaperPosition',    [3.56  2.03  22.56  16.92]);

These are root defaults; they propagate to every figure created after rise_startup unless explicitly overridden on the figure itself. rise_exit restores them to MATLAB factory values.

Two practical consequences:

  • print(fig, '-dpdf', ...) and save_figure(fig, ..., 'pdf') produce landscape PDFs at the configured size by default. No per-figure paper setup is needed before printing.

  • If you want a different paper geometry, override on the figure (set(fig, 'PaperPosition', ...)) rather than on the root – per-figure settings take precedence.