Functions and Types

MSMOptions

MSMOptions is a mutable struct that contains options related to the optimization.

Examples

julia> options = MSMOptions(maxFuncEvals=1000, globalOptimizer = :dxnes, localOptimizer = :LBFGS)

MSMProblem

MSMProblem is a mutable struct that caries all the information needed to perform the optimization and display the results.

J_test(sMMProblem::MSMProblem, theta0::Array{Float64,1}, tData::Int64, tSimData::Int64, alpha::Float64)

Run a J-test, also called a test for over-identifying restrictions. The null hypothesis that the model is “valid”. The alternative hypothesis that model is “invalid”. For the test to be valid, the weight matrix must converge in probability to Sigma0^-1, where Sigma0 is the (long-run) variance of the empirical moments.

With tau = tData/tSimData, the statistic is J = tData/(1 + tau)*g'Wg, where g is the gap between empirical and simulated moments at theta0. Under the null, J converges in distribution to a Chi²(k-l), where k is the number of moments and l the number of parameters. See Lee and Ingram (1991, p. 202 and p. 204).

#Output:

• J: value of the J-statistic
• c: critical value associated to the J-test

calculate_Avar!(sMMProblem::MSMProblem, theta0::Array{Float64,1}; tau::Float64 = 1.0)

Calculate the asymptotic variance of the SMM estimator using the sandwich formula. This function assume that your model is simulating time series. As a result, the asymptotic variance of the SMM estimator is (1+tau) times the asymptotic variance for the GMM estimator, where tau is the ratio of the sample size to the size of the simulated sample. See Duffie and Singleton (1993) and Gouriéroux and Monfort (1996).

calculate_CI(sMMProblem::MSMProblem, theta0::Array{Float64,1}, tData::Int64, i::Int64, alpha::Float64)

Function to calculate a two-sided (1 - alpha) confidence interval for the ith parameter. alpha is the significance level (e.g. alpha = 0.05 gives a 95% confidence interval).

calculate_D(sMMProblem::MSMProblem, theta0::Array{Float64,1})

Function to calculate the jacobian of the simulated moments at theta0, by central finite differences (5-point stencil, FiniteDifferences.jl). Rows follow the order of the empirical moments, columns the order of the priors. If the simulation is long enough, this provides a good approximation for the expected value of the jacobian. The output is the "D" matrix in the terminology of Gouriéroux and Monfort (1996).

calculate_pvalue(sMMProblem::MSMProblem, theta0::Array{Float64,1}, tData::Int64, i::Int64)

Function to calculate the two-sided p-value of the ith parameter (value theta0[i]) associated to following test: H0: thetai = 0 H1: thetai != 0 The ordering of parameters is the one given by the ordered dictionary sMMProblem.priors

calculate_se(sMMProblem::MSMProblem, tData::Int64, i::Int64)

Function to calculate the standard error associated to the ith parameter, respecting the ordering given by the ordered dictionary sMMProblem.priors. tData is the length of the empirical sample. Requires calculate_Avar! first.

calculate_t(sMMProblem::MSMProblem, theta0::Array{Float64,1}, tData::Int64, i::Int64)

Function to calculate the t-statistic of the ith parameter (value theta0[i]) associated to following test: H0: thetai = 0 H1: thetai != 0 The ordering of parameters is the one given by the ordered dictionary sMMProblem.priors

check_problem(sMMProblem::MSMProblem)

Check that the MSMProblem is ready for the optimization, and throw an informative error otherwise. The objective function returns the penalty value on any error, so without this check a mistake (e.g. a weight matrix of the wrong size, a misspelled moment name, or a bug in the simulation function) would give a flat objective function and the optimization would run to completion.

Checks that the priors, the empirical moments, the simulation function and the objective function are set, that W is k×k (k empirical moments), and simulates the moments once, at the initial values of the priors: the simulation must not throw, must return every empirical moment, and the simulated moments must be finite.

Called by msm_optimize! and msm_multistart!, unless check = false.

constructobjectivefunction!(sMMProblem::MSMProblem)

Function that construct an objective function, using the function MSMProblem.simulateempiricalmoments.

convert_to_fminbox(s::Symbol)

function to convert local optimizer (of type Symbol) to a Fminbox usable by Optim.

convert_to_optim_algo(s::Symbol)

function to convert local optimizer (of type Symbol) to an Optim algo.

cov_NW(data::Matrix; l::Int64 = -1)

Function to calculate Newey–West (1987) variance-covariance matrix. data is the data matrix with each row representing a time period and each column representing a variable. l is the number of lags to include.

createlowerbound(sMMProblem::MSMProblem)

Function to generate a lower bound used by Optim when minimizing with Fminbox. The lower bound is of type Array{Float64,1}.

createupperbound(sMMProblem::MSMProblem)

Function to generate an upper bound used by Optim when minimizing with Fminbox. The upper bound is of type Array{Float64,1}.

default_function(x)

Function x->x. Used to initialize functions.

generate_bbSearchRange(sMMProblem::MSMProblem)

Function to generate a search range that matches the convention used by BlackBoxOptim.

get_now()

Returns date and time in a manner that does not clash with Windows, Linux and OSX (e.g. "2026-09-30–14h-5m-3s")

info(text)

To display information to user

is_bb_optimizer(s::Symbol)

function to check whether the global optimizer is using BlackBoxOptim

is_global_optimizer(s::Symbol)

function to check that the global optimizer chosen is available.

is_local_optimizer(s::Symbol)

function to check that the local optimizer chosen is available.

is_nes_optimizer(s::Symbol)

function to check whether the global optimizer is a natural evolution strategy of BlackBoxOptim (:dxnes, :xnes or :separable_nes), which evaluates lambda points per generation.

is_optim_optimizer(s::Symbol)

function to check whether the local minimizer uses the package Optim.

latin_hypercube_sampling(mySearchRange::Vector{Tuple{Float64, Float64}}, n::Integer; gens::Integer = 100)

Function to create an optimised Latin Hypercube Sampling Plan

Input

• mySearchRange: a vector of tuple of the form (xjmin, xjmax)
• n: number of points to draw
• gens: (optional) optimization is run for gens generations. See LatinHypercubeSampling.jl

Output

• Matrix{Float64}: row = observation; column = dimension

latin_hypercube_sampling(mins, maxs, n)

Randomly sample n vectors from the parallelogram defined by mins and maxs using the Latin hypercube algorithm. Returns an n×dims matrix (one point per row).

linspace(zstart::Real, zend::Real, z_n::Int64)

Vector of zn evenly spaced points from zstart to z_end (similar to Base.linspace on julia v. < 0.7)

msmlocalminimizer(sMMProblem::MSMProblem)

Function to get the parameter value minimizing the objective function (local)

msmlocalminimum(sMMProblem::MSMProblem)

Function to get the local minimum value of the objective function

msm_localmin(sMMProblem::MSMProblem, x0::Array{Float64,1}; verbose::Bool = true)

Function find a local minimum using a local minimization routine, with starting value x0. To be used after the following functions have been called: (i) setempiricalmoments! (ii) setpriors! (iii) setsimulateempiricalmoments! (iv) constructobjectivefunction!

msm_minimizer(sMMProblem::MSMProblem)

Function to get the parameter value minimizing the objective function

msm_minimum(sMMProblem::MSMProblem)

Function to get the minimum of the objective function

msm_multistart!(sMMProblem::MSMProblem; x0 = Array{Float64}(undef, 0,0), nums::Int64 = nworkers(), verbose::Bool = true, check::Bool = true)

Function to run several local minimization algorithms in parallel, with different starting values. The minimum is calculated as the minimum of the local minima that converged. If none converged, the best finite local minimum is used instead, with a message saying so. Changes sMMProblem.optimResults. This function also returns a list containing Optim results (nothing for a local minimization that threw an error). With check = true, check_problem is called first (see msm_optimize!).

msmmultistartminimizer(sMMProblem::MSMProblem)

Function to get the parameter value minimizing the objective function when using the multistart algorithm

msmmultistartminimum(sMMProblem::MSMProblem)

Function to get the minimum value of the objective function when using the multistart algorithm

msm_optimize!(sMMProblem::MSMProblem; verbose::Bool = true, check::Bool = true)

Function to launch an optimization. To be used after the following functions have been called: (i) setempiricalmoments! (ii) setpriors! (iii) setsimulateempiricalmoments! (iv) constructobjectivefunction! With verbose = false, the progress of the optimizer is not displayed. With check = true, check_problem is called first: it throws an error if the problem is not set up correctly, or if the simulation fails at the initial values of the priors.

msmrefineglobalmin!(sMMProblem::MSMProblem; verbose::Bool = true)

Function to refine the global minimum using a local minimization routine. To be used after the following functions have been called: (i) setempiricalmoments! (ii) setpriors! (iii) setsimulateempiricalmoments! (iv) constructobjectivefunction! (v) msm_optimize!

msm_slices(sMMProblem::MSMProblem, paramValues::Vector; nbPoints::Int64 = 5, offset::Float64 = 0.001)

Function to "slice" the objective function. That is, to hold the variables constant, except for one dimension. Each parameter θ varies in [θ - offset|θ|, θ + offset|θ|], or in [θ - offsetrange, θ + offsetrange] when θ is (numerically) zero, where range is the width of the prior of θ.

nes_lambda(globalOptimizer::Symbol, lambda::Int64, nbDimensions::Int64, nbWorkers::Int64)

Number of points λ evaluated per generation by a natural evolution strategy of BlackBoxOptim (:dxnes, :xnes, :separable_nes). If lambda > 0, returns lambda. If lambda == 0 (automatic), returns BlackBoxOptim's default for nbDimensions parameters, rounded up to a multiple of nbWorkers: the points of a generation are evaluated in parallel, and the next generation starts when all of them are done, so no worker is idle. :dxnes requires an even λ: when the multiple is odd, λ is decreased by one (one worker is idle at the end of each generation).

Examples

julia> nes_lambda(:dxnes, 0, 5, 1)    # BlackBoxOptim's default for 5 parameters
8
julia> nes_lambda(:dxnes, 0, 5, 32)
32
julia> nes_lambda(:dxnes, 0, 5, 11)   # 11 is odd: one worker idle
10
julia> nes_lambda(:dxnes, 0, 10, 4)   # default 10, rounded up to a multiple of 4
12

readempiricalmoments(pathToCsv::String)

Function to load empirical moments stored in a csv file. Returns a dictionary. The csv file should have the following columns "name", "value", "weight"

read_priors(pathToCsv::String)

Function to load priors stored in a csv file. Returns a dictionary. The csv file should have the following columns "name", "value", "upperbound", "lowerbound"

rosenbrock2d(x)

Rosenbrock function (a standard test function for optimizers). Its minimum is 0, at [1.0, 1.0].

set_Sigma0!(sMMProblem::MSMProblem, Sigma0::Array{Float64,2})

Function to change the field sMMProblem.Sigma0, where Sigma0 is the distance matrix, in the terminology of Duffie and Singleton (1993)

set_bbSetup!(sMMProblem::MSMProblem; verbose::Bool = true)

Function to set the field bbSetup for a MSMProblem. With verbose = false, BlackBoxOptim does not display the progress of the optimization. For the NES optimizers (:dxnes, :xnes, :separable_nes), the number of points per generation is nes_lambda(globalOptimizer, options.lambda, number of parameters, nworkers()).

setempiricalmoments!(sMMProblem::MSMProblem, empiricalMoments::OrderedDict{String,Array{Float64,1}})

Function to change the field sMMProblem.empiricalMoments

setglobaloptimizer!(sMMProblem::MSMProblem; verbose::Bool = true)

Function to set the fields corresponding to the global optimizer problem.

set_priors!(sMMProblem::MSMProblem, priors::OrderedDict{String,Array{Float64,1}})

Function to change the field sMMProblem.priors

setsimulateempirical_moments!(sMMProblem::MSMProblem, f::Function)

Function to set the field simulateempiricalmoments for a MSMProblem. The function simulateempiricalmoments takes parameter values and return the corresponding simulate moments values.

setweightmatrix!(sMMProblem::MSMProblem, W::Matrix{Float64})

Function to change the field sMMProblem.empiricalMoments

summary_table(sMMProblem::MSMProblem, theta0::Array{Float64,1}, tData::Int64, alpha::Float64)

Returns a table with estimates and related statistics of the model. alpha is the significance level.