1.2. Prior distributions and implementation

1.2.1. Bayesian priors

N.B: In the description below :

start denotes the initial value for estimation
mean denotes the mean of the prior distribution
sd denotes the standard deviation
hpp1 denotes the first hyperparameter
hpp2 denotes the second hyperparameter
hpp3 denotes the third hyperparameter
hpp4 denotes the fourth hyperparameter
lb denotes the lower bound
ub denotes the upper bound
lq denotes the lower quantile
uq denotes the upper quantile
p is the structure containing the parameters to estimate
alpha is the name of some parameter to be estimated

Setting Uniform Priors

p.alpha = {start,lb,ub};

N.B: This prior will be rewritten internally as
p.alpha = {start,lb,ub,'uniform(1)'};

If you set all your parameters to be estimated in this way, this is how you perform Maximum Likelihood (See e.g. [Ireland, 2004]) in RISE.

Setting priors using Means and Standard deviations

p.alpha = {start,mean,sd,'distribution'};

*adding truncation*
p.alpha = {start,mean,sd,'distribution',lb,ub};

*more hyperparameters e.g. generalized beta, t-student or truncated normal*
p.alpha = {start,mean,sd,hpp3,hpp4,'distribution'};

*adding truncation*
p.alpha = {start,mean,sd,hpp3,hpp4,'distribution',lb,ub};

Setting priors using quantiles

One cannot always characterize the distribution of parameters in terms of means and standard deviations :

Not all distributions have means and standard deviations

Some distributions are such that for some specific values of the hyperparameters, the first and second moments do not exist

Oftentimes when we take our priors from the literature, the number of studies we take inspiration from are too few to rely on for the calculation of means and standard deviations.

Under such circumstances, one can instead use quantiles.

p.alpha = {start,lq,uq,'distribution(probability)'};

*adding truncation*
p.alpha = {start,lq,uq,'distribution(probability)',lb,ub};

*more hyperparameters e.g. generalized beta, t-student or truncated normal*
p.alpha = {start,lq,uq,hpp3,hpp4,'distribution(probability)'};

*adding truncation*
p.alpha = {start,lq,uq,hpp3,hpp4,'distribution(probability)',lb,ub};

Setting priors using hyperparameters

In some cases, people prefer to characterize their distributions directly in terms of hyperparameters.

In fact all the previous approaches to setting priors will first determine the hyperparameters of the distributions.

RISE also allows you to set your priors directly in terms of hyperparameters if you choose to do so. Should you rely on this strategy, the recommendation is to plot the distributions and inspect them carefully before starting any estimation.

p.alpha = {start,hpp1,hpp2,'distribution(hpp)'};

*adding truncation*
p.alpha = {start,hpp1,hpp2,'distribution(hpp)',lb,ub};

*more hyperparameters e.g. generalized beta, t-student or truncated normal*
p.alpha = {start,hpp1,hpp2,hpp3,hpp4,'distribution(hpp)'};

*adding truncation*
p.alpha = {start,hpp1,hpp2,hpp3,hpp4,'distribution(hpp)',lb,ub};

About the t-student prior

The third hyperparameter of the t-student distribution is the DOF (degree of freedom). There is not 4th hyperparameter and so the field can be nan or empty e.g. p.alpha = {start,3,7,10,nan,’t(.9)’};

The dirichlet prior

consider a transition matrix of the form

\[\begin{split}M = \begin{bmatrix} pname(1,1) & pname(1,2) & ... & pname(1,n) \\ pname(2,1) & pname(2,2) & ... & pname(2,n) \\ ... & ... & ... & ... \\ pname(n,1) & pname(n,2) & ... & pname(n,n) \end{bmatrix}\end{split}\]

Dirichlet priors can bet set as follows

p.dirichlet_1 = {stdev(1,1),pname(1,2),mean(1,2),pname(1,3),mean(1,3),...,pname(1,n),mean(1,n)};

with mean(1,1)+mean(1,2)+mean(1,3)+...+mean(1,n)=1
and mean(1,1) the mean of the first diagonal element
and stdev(1,1) its standard deviation

p.dirichlet_2 = {stdev(2,2),pname(2,1),mean(2,1),pname(2,3),mean(2,3),...,pname(2,n),mean(2,n)};
...
p.dirichlet_n = {stdev(n,n),pname(n,1),mean(n,1),pname(n,2),mean(n,2),...,pname(n,n-1),mean(n,n-1)};

with mean(n,1)+mean(n,2)+mean(n,3)+...+mean(n,n)=1
and mean(n,n) the mean of the n-th diagonal element
and stdev(n,n) its standard deviation

N.B: The order of the names dirichlet_1, dirichlet_2, …, dirichlet_n is irrelevant and there need not be n such names. The key here is the syntax dirichlet_number

1.2.2. Endogenous Priors

Rather than setting priors on parameters, one can also set priors on the behavior or properties of the model. This is known in the literature under various appellations:

Endogenous priors: See e.g., [Del Negro and Schorfheide, 2008] or [Christiano et al., 2011]

System priors: See e.g., [Andrle and Benes, 2013], [Andrle and Plasil, 2017] or [Andrle and Plašil, 2018]

Property priors: as suggested by Bob Tetlow

Behavioral priors

Setting endogenous priors involves placing constraints on model-implied behaviors, such as impulse responses, variance decompositions, or probabilities of certain states or regimes. Below, we describe the syntax for setting these priors, organized by their types and possible variations.

General Syntax for Endogenous Priors

The basic syntax for an endogenous prior is:

{'expression', mean, std, 'distribution'}
{'expression', lb, ub}
    {'expression',lq,uq,'distribution(probability)'}
    {'expression',hpp1,hpp2,'distribution(hpp)'}

where:

`expression`: Defines the model behavior or property being constrained. This could be a covariance, correlation, impulse response, variance decomposition, historical decomposition, probability of being in a particular state, or a custom-defined function.
`mean`, `std`, `distribution`, `lb`, `ub`, `hpp1`, `hpp2`: are the same as defined for priors on parameters above.

Types of Endogenous Priors

This section covers the various types of endogenous priors and their specific syntax.

1. Covariance and Correlation Priors

Covariance and correlation priors constrain the covariance or correlation between two variables in the model. Under regime switching, the default regime is 1. The syntax for each is as follows:

Covariance:
```
'cov{var1, var2, lag}'
'cov{var1, var2, lag, regime}'
```
Example: ‘cov{C, Y, 1, 2}’ sets a prior on the covariance between C and Y with a lag of 1 in regime 2.
Correlation:
```
'corr{var1, var2, lag}'
'corr{var1, var2, lag, regime}'
```
Example: ‘corr{C, Y, 1, 3}’ sets a prior on the correlation between C and Y with a lag of 1 in regime 3.

2. Impulse Response Function (IRF) Priors

Impulse response priors specify the expected behavior of a variable in response to a shock. The syntax is:

'irf{variable, shock, horizon}'
'irf{variable, shock, horizon, regime}'

Example: ‘irf{C, EA, 3, 2}’ constrains the impulse response of C to shock EA at horizon 3 in regime 2.

3. Variance Decomposition (VD) Priors

Variance decomposition priors specify the contribution of a shock to the variance of a variable over a specified horizon. The syntax varies depending on whether it is a finite or infinite horizon.

Finite-Horizon Variance Decomposition:
```
'vd{variable, shock, horizon}'
'vd{variable, shock, horizon, regime}'
```
Example: ‘vd{C, EA, 30, 2}’ constrains the finite-horizon variance decomposition of C explained by shock EA at horizon 30 in regime 2.
Infinite-Horizon (Long-Run) Variance Decomposition:
```
'vd{variable, shock, inf}'
'vd{variable, shock, inf, regime}'
```
Example: ‘vd{C, EA, inf, 3}’ constrains the long-run variance decomposition of C by shock EA in regime 3.

4. Historical Decomposition (HD) Priors

Historical decomposition priors measure the contribution of a shock to a variable over time. The syntax is:

'hd{variable, shock, horizon}'

Example: ‘hd{C, EA, 30}’ constrains the historical decomposition of C from shock EA at horizon 30.

5. First-order solution Priors

What is the impact of a particular state variable on some endogenous variable? The syntax is:

'Tz{variable, stateVariable}'
'Tz{variable, stateVariable, regime}'

Endogenous state variables impacts:

Example: ‘Tz{C, C{-1}}’ constrains the impact of state variable C{-1} on endogenous C in the (default) first regime.

Example: ‘Tz{C, C{-1},2}’ same as above but in the second regime.
Perturbation parameter impacts:

Example: ‘Tz{C, @sig}’ constrains the impact on C of perturbation parameter in the (default) first regime.

Example: ‘Tz{C, @sig, k}’ same as above but in the k-th regime.
Shock impacts:

Example: ‘Tz{C, EA}’ constrains the impact on C of shock EA in the (default) first regime.

Example: ‘Tz{C, EA{+3}, 2}’ constrains the expected impact of shock EA 3 periods ahead on C in the second regime.

6. Probability Priors (Filtered, Updated, Smoothed)

Probability priors set expectations for the likelihood of being in a particular regime or state at a specific date or over a range of dates. These can be filtered (f), updated (u), or smoothed (s).

Regime Probabilities:
```
'mvar{f, regime, date_range}'
'mvar{u, regime, date_range}'
'mvar{s, regime, date_range}'
```
Example: ‘mvar{f, regime_2, rq(2020,3)}’ specifies a prior on the filtered probability of regime 2 in 2020 Q3.
State Combination Probabilities:
```
'mvar{f, state1&state2&...&stateN, date_range}'
'mvar{u, state1&state2&...&stateN, date_range}'
'mvar{s, state1&state2&...&stateN, date_range}'
```
Example: ‘mvar{f, vol_2&pol_1, rq(2020,3)}’ sets a prior on the filtered probability of being in vol_2 and pol_1 in 2020 Q3.

Advanced Variants and Complex Functions

The following advanced options allow the application of mathematical functions to base expressions or combinations of base expressions, as well as the use of discontinuous date ranges.

6. E.g.: Aggregated IRF or Probability Expressions

Aggregate impulse responses or probabilities over a specified period using functions like sum, max, and min.

Sum of IRFs:
```
'sum(irf{variable, shock, start:end, regime})'
```
Example: ‘sum(irf{C, EA, 1:40, 3})’ sums the IRFs of C to EA over the range from 1 to 40 in regime 3.
Max/Min of IRFs or Probabilities:
```
'max(expression)' or 'min(expression)'
```
Example: ‘max(mvar{f, regime_2, rq(1970,3):rq(2024,3)})’ finds the maximum filtered probability of regime 2 over the specified period.

7. E.g.: Multi-Period Expressions with Discontinuous Ranges

Specify non-continuous date ranges to analyze behavior over irregular intervals.

Discontinuous Date Ranges:
```
'[start1:end1, single_date, start2:end2]'
```
Example: ‘mvar{f, regime_2, [rq(1970,3):rq(1975,3), rq(1978,3), rq(1980,3):rq(1985,4)]}’

8. User-Defined Functions

Custom functions allow flexibility to capture specific model behaviors based on parameters or combinations of variables.

Custom Function:

{@(model) function_name(model), mean, std, 'distribution'}
{@(model) function_name(model), lb, ub}
    {@(model) function_name(model), lq,uq,'distribution(probability)'}
    {@(model) function_name(model), hpp1,hpp2,'distribution(hpp)'}

Example: {@(model) custom_autocorrelation(model), 0.5, 0.1, ‘normal’} defines a user-defined function to impose a prior on custom behavior.

9. Advanced User-Defined Endogenous priors

If is also possible for the user to create a function handle to endogenous priors. When called with only one input (the model object), the function should return a structure with fields priors and kf_filtering_level.

v = struct('priors',{v},...
    'kf_filtering_level',0);

The priors field is a n x 1 cell array in which each entry is a cell with information on a particular endogenous prior. For example

v = cell(n,1);

    for ii=1:n

        v{ii}={0.005,2*0.005,'gamma'};

    end

The kf_filtering_level will be:

0 : no filtering information required

1 : 1-step ahead (filtered series) requested

2 : updated series requested

3 : smoothed series requested

When the function is called with two inputs (the model object + filtering information), the function shall return a vector of numbers evaluating the n priors.

Summary of Endogenous Prior Cases

Here is a summary of the main types and formats for endogenous priors:

Covariance: 'cov{var1, var2, lag, regime}'
Correlation: 'corr{var1, var2, lag, regime}'
Impulse Response (IRF): 'irf{variable, shock, horizon, regime}'
Variance Decomposition (Finite): 'vd{variable, shock, horizon, regime}'
Variance Decomposition (Infinite): 'vd{variable, shock, inf, regime}'
Historical Decomposition: 'hd{variable, shock, horizon}'
Regime Probability (Filtered/Updated/Smoothed): 'mvar{f|u|s, regime, date_range}'
State Combination Probability: 'mvar{f|u|s, state_combination, date_range}'
Sum of IRFs or Probabilities: 'sum(irf{variable, shock, start:end, regime})'
Max/Min of IRFs or Probabilities: 'max(expression)' or 'min(expression)'
Multi-Period Expressions with Discontinuous Ranges: '[start:end, single_date, ...]'
User-Defined Function: {@(model) function_name(model), mean, std, 'distribution'}

This comprehensive list provides all available cases and variations for setting endogenous priors, ensuring flexible specification of model behaviors. Use these forms to capture and constrain the model properties essential to your analysis.

1.2.3. User-defined Priors

It could be the case that you want to implement a prior that is not supported by RISE. In that case you should provide the PDF (not the log PDF!) of the prior as a function handle, the lower and upper bounds of the distribution. Internally, RISE will (empirically) construct routines for the CDF, the inverse CDF and everything needed. The syntax is as follows:

p.alpha = {start,LB,UB,function_handle};

1.2.4. Visualizing priors and posteriors

With the structure of priors in place, one can use rise.plot.distribution to visualize the priors and/or, if a posterior simulation has been conducted, the posteriors. The function is model-free: it operates on the priors-shaped struct of named distributions and, optionally, an mcmc object of posterior draws – not on a model.

The syntax is

rise.plot.distribution(distributions)

rise.plot.distribution(distributions, mc)

rise.plot.distribution(distributions, mc, 'what', 'posteriors')

rise.plot.distribution(distributions, [], 'parameters', {'alpha','beta'})

h = rise.plot.distribution(distributions, mc, 'rows_cols', [2,3], ...
        'line_props', {'linewidth',2})

Args:

distributions (struct): the named distributions to plot (the priors-shaped structure, e.g. a model’s estimation.priors).

draws (empty|mcmc object): posterior draws as an mcmc object; [] plots the priors only.

what ({‘both’}|’priors’|’posteriors’): which densities to draw. With ‘both’ (the default) and no draws, only the priors are drawn.

parameters (empty|char|cellstr): subset of names to plot; empty plots all.

rows_cols ({[3,3]}): number of rows and columns of panels per figure.

npoints ({1000}): number of points used to evaluate each density.

prior_trunc ({1e-3}): tail truncation for the prior plots.

line_props ({{}}): extra pairwise line properties, e.g. {‘linewidth’,2}.

Returns the figure handle(s) when an output is requested.

Example

priors=struct();
priors.beta={.5,95,5,'beta(hpp)'};
priors.delta={.5, 40,860,'beta(hpp)'};
priors.alpha={.5,360,590,'gamma(hpp)'};
priors.rhoz={.5,80,20,'beta(hpp)'};
priors.sdez={0.1, 0.01,0.01,'igamma(hpp)'};

rise.plot.distribution(priors, [], 'prior_trunc', 2.6e-3, ...
    'line_props', {'linewidth',2})

1.2.5. List of prior distributions

arcsine: \(\theta\) in \([0,1]\)
beta: \(\theta\) in \([0,1]\)
dirichlet : \(\theta _{i}\) in \([0,1]\), with \(\sum_{i}\theta _{i}=1\)
betaprime : \(\theta\) in \([0,\infty)\)
cauchy : \(\theta\) in \((-\infty ,\infty )\)
exponential: \(\theta\) in \([0,\infty )\)
folded_normal : \(\theta\) in \([0,\infty )\)
gamma : \(\theta\) in \([0,\infty )\)
gammatau (generalized gamma-tau): \(\theta ` in :math:`[0,\infty )\)
gumbel : \(\theta\) in \((-\infty ,\infty )\)
half_normal : \(\theta\) in \([0,\infty )\)
igamma (igamma2) : \(\theta\) in \([0,\infty )\)
igamma1 : \(\theta\) in \([0,\infty )\) – inverse-gamma with the shape/scale parametrisation
igamma2 : \(\theta\) in \([0,\infty )\)
inverse_gaussian : \(\theta\) in \((0,\infty )\)
kumaraswamy : \(\theta\) in \((0,1)\)
laplace : \(\theta\) in \((-\infty ,\infty )\)
left_triang (skewed to the left) : \(\theta\) in \([a,b]\)
levy : \(\theta\) in \([\mu ,\infty )\)
logistic : \(\theta\) in \((-\infty ,\infty )\)
lognormal : \(\theta\) in \((0,\infty )\)
normal : \(\theta\) in \((-\infty ,\infty )\)
pareto : \(\theta\) in \([x_{m},\infty )\), \(x_{m}>0\)
raised_cosine : \(\theta\) in \([\mu -s,\mu +s]\), \(s>0\)
sichisq (scaled inverse \(\chi^2\)) : \(\theta\) in \((0,\infty )\)
t (t-student) : \(\theta\) in \((-\infty ,\infty )\)
truncated_normal: \(\theta\) in \([\underline{\theta },\overline{\theta}]\)
uniform : \(\theta\) in \([\underline{\theta },\overline{\theta }]\)
weibull : \(\theta\) in \([0,\infty )\)

Note

The following distributions can be used for standard deviations: igamma, igamma1, inverse_gaussian sichisq

For parameters in the \([0,1]\) interval, one case use beta, kumaraswamy