Manual

For a concise overview of the package, please read the package paper. It provides a high-level presentation of the theory behind score-driven models and showcases the features of the package as well as examples.

Model Specification

ScoreDrivenModels.Model — Type

Model

The constructor of a score-driven model. The model receives the lag structure, the distribution and the scaling. You can define the lag structure in two different ways, either by passing integers p and q to add all lags from 1 to p and 1 to q or by passing vectors of integers ps and qs containing the desired lags. Once you build the model all of the unknown parameters that must be estimated are represented as NaN.

# Passing p and q
julia> Model(2, 2, LogNormal, 0.5)
Model{LogNormal,Float64}([NaN, NaN], Dict(2=>[NaN 0.0; 0.0 NaN],1=>[NaN 0.0; 0.0 NaN]), Dict(2=>[NaN 0.0; 0.0 NaN],1=>[NaN 0.0; 0.0 NaN]), 0.5)

# Passing ps and qs
julia> Model([1, 12], [1, 12], Gamma, 0.0)
Model{Gamma,Float64}([NaN, NaN], Dict(12=>[NaN 0.0; 0.0 NaN],1=>[NaN 0.0; 0.0 NaN]), Dict(12=>[NaN 0.0; 0.0 NaN],1=>[NaN 0.0; 0.0 NaN]), 0.0)

If you don't want all the parameters to be considered time-varying you can express it through the keyword argument time_varying_params, there you should pass a vector containing a number that represents which parameter should be time-varying. As an example in the Normal distribution time_varying_params = [1] indicates that only $\mu$ is time-varying. You can find the table with the dictionary (number => parameter) in the section ScoreDrivenModels distributions.

julia> Model([1, 12], [1, 12], Normal, 1.0; time_varying_params = [1])
Model{Normal,Float64}([NaN, NaN], Dict(12=>[NaN 0.0; 0.0 0.0],1=>[NaN 0.0; 0.0 0.0]), Dict(12=>[NaN 0.0; 0.0 0.0],1=>[NaN 0.0; 0.0 0.0]), 1.0)

Optimization Algorithms

ScoreDrivenModels.jl allows users to use different optimization methods, in particular it has a common interface to easily incorporate algorithms available on Optim.jl

All optimization methods can receive the following keyword arguments

f_tol - Relative tolerance in changes of the objective value. Default is 1e-6.
g_tol - Absolute tolerance in the gradient, in infinity norm. Default is 1e-6.
iterations - Maximum number of iterations. Default is 10^5.
LB - Lower bound of the initial points. Default is 0.0.
UB - Upper bound of the initial points. Default is 0.6.

ScoreDrivenModels.IPNewton allows users to perform box-constrained optimization.

ScoreDrivenModels.NelderMead — Type

NelderMead(model::Model, args...; kwargs...)

If an Int is provided the method will sample that many random initial_points and use them as initial points for Optim NelderMead method. If a Vector{Vector{T}} is provided it will use them as initial points for Optim NelderMead method.

ScoreDrivenModels.LBFGS — Type

LBFGS(model::Model, args...; kwargs...)

If an Int is provided the method will sample that many random initial_points and use them as initial points for Optim LBFGS method. If a Vector{Vector{T}} is provided it will use them as initial points for Optim LBFGS method.

ScoreDrivenModels.IPNewton — Type

IPNewton(model::Model, args...; kwargs...)

If an Int is provided the method will sample that many random initial_points and use them as initial points for Optim IPNewton method. If a Vector{Vector{T}} is provided it will use them as initial points for Optim IPNewton method.

This method provides an alternative to create box constraints. constraints can be passed as a Vector the default constraints are ub = Inf * ones(T, dim_unknowns(model)) and lb = -Inf * ones(T, dim_unknowns(model))

Recursion

Links

Links are reparametrizations utilized to ensure certain parameter is within its original domain. For instance, for a particular distribution, one might want to ensure that the time varying parameter is positive: $f \in \mathbb{R}^+$. The way to do this is to model $\tilde{f} = \ln{f}$. More generally, one can establish that $\tilde{f} = h(f)$. We refer to this procedure as linking. When a parameter is linked, the GAS recursion happens in the domain of $\tilde{f}$ and then one can recover the original parameter by $f = \left(h\right)^{-1}(\tilde f)$. We refer to this procedure as unlinking. The new recursion becomes:

\[\begin{equation*}\left\{\begin{array}{ccl} f_{t} &=& h^{-1}(\tilde f_t), \\ \tilde f_{t+1} &=& \omega + \sum_{i=1}^p A_{i}\tilde s_{t-i+1} + \sum_{j=1}^q B_{j}\tilde f_{t-j+1} \end{array} \right. \end{equation*}\]

Notice that a different parametrization alters the dynamics of the model. For example, the GAS(1,1) model with Normal distribution and scaling $d = 1$ is equivalent to the well-known GARCH(1, 1) model. Conversely, if a different parametrization is utilized, the model will no longer be equivalent.

Types of links

The abstract type Link subsumes any type of link that can be expressed.

ScoreDrivenModels.IdentityLink — Type

IdentityLink <: Link

Define the map $\tilde{f} = f$ where $f \in \mathbb{R}$ and $\tilde{f} \in \mathbb{R}$

ScoreDrivenModels.LogLink — Type

LogLink <: Link

Define the map $\tilde{f} = \ln(f - a)$ where $f \in [a, \infty), a \in \mathbb{R}$ and $\tilde{f} \in \mathbb{R}$

ScoreDrivenModels.LogitLink — Type

LogitLink <: Link

Define the map $\tilde{f} = \ln(\frac{f - a}{b - f})$ where $f \in [a, b], a, b \in \mathbb{R}$ and $\tilde{f} \in \mathbb{R}$

Link functions

ScoreDrivenModels.link — Function

link(args...)

The link function is a map that brings a parameter $f$ in a subspace $\mathcal{F} \subset \mathbb{R}$ to $\mathbb{R}$.

ScoreDrivenModels.unlink — Function

unlink(args...)

The unlink function is the inverse map of link. It brings $\tilde{f}$ in $\mathbb{R}$ to the subspace $\mathcal{F} \subset \mathbb{R}$.

ScoreDrivenModels.jacobian_link — Function

jacobian_link(args...)

Evaluates the derivative of the link with respect to the parameter $f$.

Forecasting

ScoreDrivenModels.jl allows users to generate point forecasts, confidence intervals forecasts or ensembles of scenarios. Point forecasts are obtained using the function forecast and ensembles of scenarios are obtained using the function simulate.

Missing docstring.

Missing docstring for forecast_quantiles. Check Documenter's build log for details.

ScoreDrivenModels.simulate — Function

simulate(series::Vector{T}, gas::Model{D, T}, H::Int, S::Int, kwargs...) where {D, T}

Generate scenarios for the future of a time series by updating the GAS recursion H times and taking a sample of the distribution until it generates S scenarios.

By default this method uses the stationary_initial_params method to perform the score driven recursion. If you estimated the model with a different set of initial_params use them here to maintain the coherence of your estimation.

ScoreDrivenModels distributions

The following section presents how every distribution is parametrized, its score, Fisher information and the time_varying_params map. Every distribution is originally imported to ScoreDrivenModels.jl from Distributions.jl. Some distributions may have different parametrizations from Distributions.jl, this is handled internally.

Distribution	Identity scaling	Inverse and inverse square root scalings
`Beta`	✓	✓
`BetaLocationScale`	✓	x
`Exponential`	✓	✓
`Gamma`	✓	✓
`LogitNormal`	✓	✓
`LogNormal`	✓	✓
`NegativeBinomial`	✓	x
`Normal`	✓	✓
`Poisson`	✓	✓
`TDist`	✓	✓
`TDistLocationScale`	✓	✓
`Weibull`	✓	x

Distributions.Beta — Type

Beta

Parametrization
Score
Fisher Information
time_varying_params map.
Default link

ScoreDrivenModels.BetaLocationScale — Type

BetaLocationScale

Parametrization \mu, \sigma, \alpha, \beta
Score
Fisher Information
time_varying_params map.
Default link

Distributions.Exponential — Type

Exponential

Parametrization

parametrized in \lambda

Score
Fisher Information
time_varying_params map.
Default link

Distributions.Gamma — Type

Gamma

Parametrization

parametrized in \alpha and \theta

Score
Fisher Information
time_varying_params map.
Default link

Distributions.LogitNormal — Type

LogitNormal

Parametrization

parametrized in \mu and \sigma^2

Score
Fisher Information
time_varying_params map.
Default link

Distributions.LogNormal — Type

LogNormal

Parametrization

parametrized in \mu and \sigma^2

Score
Fisher Information
time_varying_params map.
Default link

Distributions.NegativeBinomial — Type

NegativeBinomial

Parametrization

parametrized in r, p

Score
Fisher Information
time_varying_params map.
Default link

Distributions.Normal — Type

Normal

Parametrization

parametrized in \mu and \sigma^2

Score
Fisher Information
time_varying_params map.
Default link

Distributions.Poisson — Type

Poisson

Parametrization

parametrized in \lambda

Score
Fisher Information
time_varying_params map.
Default link

Distributions.TDist — Type

Student's t

Parametrization

parametrized in \nu

Score
Fisher Information
time_varying_params map.
Default link

ScoreDrivenModels.TDistLocationScale — Type

Student's t location scale

Parametrization

parametrized in \mu, \sigma^2 and \nu

Score
Fisher Information
time_varying_params map.
Default link

Distributions.Weibull — Type

LogNormal

Parametrization

parametrized in \alpha and \theta

Score
Fisher Information
time_varying_params map.
Default link

Implementing a new distribution

If you want to add a new distribution please feel free to make a pull request.

Each distribution must have the following methods:

ScoreDrivenModels.score!
ScoreDrivenModels.fisher_information!
ScoreDrivenModels.log_likelihood
link interface
ScoreDrivenModels.update_dist
ScoreDrivenModels.params_sdm
ScoreDrivenModels.num_params

The details of the new distribution must be documented following the example in Normal and added to the ScoreDrivenModels distributions section. The new implemented distribution must also be added to the constant DISTS and exported in the distributions/common_interface.jl file.

ScoreDrivenModels.score! — Function

score!(score_til::Matrix{T}, y::T, D::Type{<:Distribution}, param::Matrix{T}, t::Int) where T

Fill score_til with the score of distribution D with parameters param[:, t] considering the observation y.

ScoreDrivenModels.fisher_information! — Function

fisher_information!(aux::AuxiliaryLinAlg{T}, D::Type{<:Distribution}, param::Matrix{T}, t::Int) where T

Fill aux with the fisher information of distribution D with parameters param[:, t].

ScoreDrivenModels.log_likelihood — Function

log_likelihood(D::Type{<:Distribution}, y::Vector{T}, param::Matrix{T}, n::Int) where T

Evaluate the log-likelihood of the distribution D considering the time-varying parameters param and the observations y.

ScoreDrivenModels.link! — Function

link!(param_tilde::Matrix{T}, D::Type{<:Distribution}, param::Matrix{T}, t::Int) where T

Fill param_tilde after the unlinking procedure of param.

ScoreDrivenModels.unlink! — Function

unlink!(param::Matrix{T}, D::Type{<:Distribution}, param_tilde::Matrix{T}, t::Int) where T

Fill param after the unlinking procedure of param_tilde.

ScoreDrivenModels.jacobian_link! — Function

jacobian_link!(aux::AuxiliaryLinAlg{T}, D::Type{<:Distribution}, param::Matrix{T}, t::Int) where T

Write the jacobian of the link map in aux.

ScoreDrivenModels.update_dist — Function

update_dist(D::Type{<:Distribution}, param::Matrix{T}, t::Int) where T

Create a new distribution from Distributions.jl based on the parametrization used in ScoreDrivenModels.jl.

ScoreDrivenModels.params_sdm — Function

params_sdm(d::Distribution)

Recover the parametrization used in ScoreDrivenModels.jl based on a Distribution from Distributions.jl.

ScoreDrivenModels.num_params — Function

num_params(D::Type{<:Distribution})

Number of parameters of a given distribution.

Reference

ScoreDrivenModels.Unknowns — Type

Unknowns

Structure that stores the positions of the parameters to be estimated in the Model.