Public documentation

estimating_function_template(nobs::Function, 
                             ef_contribution::Function)

Composite type for defining an estimating_function_template.

Arguments

• nobs: a function of data that computes the number of observations of the particular data type,
• ef_contribution: a function of the parameters theta, the data and the observation index i that returns a vector of length length(theta).

Result

An estimating_function_template object with fields nobs and obj_contributions.

get_estimating_function(data::Any,
                        template::estimating_function_template,
                        br::Bool = false,
                        concentrate::Vector{Int64} = Vector{Int64}(),
                        regularizer::Any = Vector{Int64}())

Construct the estimating functions by adding up all contributions in the data according to estimating_function_template.

Arguments

• data: typically an object of composite type with all the data required to compute the estimating_function.
• template: an estimating_function_template object.
• br: a Bool. If false (default), the estimating functions is constructed by adding up all contributions in

data, according to estimating_function_template, before it is evaluated at theta. If true then the empirical bias-reducing adjustments in Kosmidis & Lunardon, 2020 are computed and added to the estimating functions.

• concentrate: a Vector{Int64}; if specified, empirical bias-reducing adjustments are added only to the subset of estimating functions indexed by concentrate. The default is to add empirical bias-reducing adjustments to all estimating functions.
• regularizer: a function of theta and data returning a Vector of dimension equal to the number of the estimating functions, which is added to the (bias-reducing) estimating function; the default value will result in no regularization.

Result

An in-place function that stores the value of the estimating functions inferred from template, in a preallocated vector passed as its first argument, ready to be used withing NLsolve.nlsolve. This is the in-place version of estimating_function with the extra regularizer argument.

estimating_function(theta::Vector,
                    data::Any,
                    template::estimating_function_template,
                    br::Bool = false,
                    concentrate::Vector{Int64} = Vector{Int64}())

Evaluate a vector of estimating functions at theta by adding up all contributions in data, according to an estimating_function_template.

Arguments

• theta: a Vector of parameter values at which to evaluate the estimating functions
• data: typically an object of composite type with all the data required to compute the estimating_function.
• template: an estimating_function_template object.
• br: a Bool. If false (default), the estimating functions is constructed by adding up all contributions in

data, according to estimating_function_template, before it is evaluated at theta. If true then the empirical bias-reducing adjustments in Kosmidis & Lunardon, 2020 are computed and added to the estimating functions.

• concentrate: a Vector{Int64}; if specified, empirical bias-reducing adjustments are added only to the subset of estimating functions indexed by concentrate. The default is to add empirical bias-reducing adjustments to all estimating functions.

Result

A Vector.

Details

data can be used to pass additional constants other than the actual data to the objective.

objective_function_template(nobs::Function, 
                            obj_contribution::Function)

A constructor of objects of composite type for defining an objective_function_template.

Arguments

• nobs: a function of data that computes the number of observations of the particular data type,
• obj_contribution: a function of the parameters theta, the data and the observation index i that returns a Float64.

Result

An objective_function_template object with fields nobs and obj_contributions.

objective_function(theta::Vector, 
                   data::Any, 
                   template::objective_function_template, 
                   br::Bool = false)

Evaluates the objective function at theta by adding up all contributions in data, according to objective_function_template.

Arguments

• theta: a Vector of parameter values at which to evaluate the objective function
• data: typically an object of composite type with all the data required to compute the objective_function.
• template: an objective_function_template object
• br: a Bool. If false (default), the objective function is constructed by adding up all contributions in

data, according to objective_function_template, before it is evaluated at theta. If true then the bias-reducing penalty in Kosmidis & Lunardon, 2020 is computed and added to the objective function.

Result

A Float64.

Details

data can be used to pass additional constants other than the actual data to the objective.

fit(template::objective_function_template,
    data::Any,
    theta::Vector{Float64};
    estimation_method::String = "M",
    br_method::String = "implicit_trace",
    regularizer::Function = function regularizer(theta::Vector{Float64}, data::Any) Vector{Float64}() end,
    lower::Vector{Float64} = Vector{Float64}(),
    upper::Vector{Float64} = Vector{Float64}(),
    optim_method = LBFGS(),
    optim_options = Optim.Options(),
    optim_arguments...)

Fit an objective_function_template on data using M-estimation (estimation_method = "M"; default) or RBM-estimation (reduced-bias M estimation; Kosmidis & Lunardon, 2020; estimation_method = "RBM")

Arguments

• template: an objective_function_template object.
• data: typically an object of composite type with all the data required to compute the objective_function.
• theta: a Vector{Float64} of parameter values to use as starting values in Optim.optimize.

Keyword arguments

• estimation_method: either "M" (default) or "RBM"; see Details.
• br_method: either "implicittrace" (default) or "explicittrace"; see Details.
• regularizer: a function of theta and data returning a Float64, which is added to the (bias-reducing penalized) objective; the default value will result in no regularization.
• lower: a Vector{Float64} of dimension equal to theta for setting box constraints for the optimization. The default will result in unconstrained optimization. See Details.
• upper: a Vector{Float64} of dimension equal to theta for setting box constraints for the optimization. The default will result in unconstrained optimization. See Details.
• optim_method: the optimization method to be used; deafult is Optim.LBFGS(). See Details.
• optim_options: the result of a call to Optim.Options to be passed to Optim.optimize. Default is Optim.Options(). See details.
• optim_arugments...: extra keyword arguments to be passed to Optim.optimize. See Details.

Details

Bias reduction is either through the maximization of the bias-reducing penalized objective in Kosmidis & Lunardon (2020) (br_method = "implicit_trace"; default) or by subtracting an estimate of the bias from the M-estimates (br_method = "explicit_trace"). The bias-reducing penalty is constructed internally using automatic differentiation (using the ForwardDiff package), and the bias estimate using a combination of automatic differentiation and numerical differentiation (using the FiniteDiff package).

The maximization of the objective or the penalized objective is done using the Optim package. Optimization methods and options can be supplied directly through the optim_method and optim_options, respectively. optim_options expects an object constructed through Optim.Options. Keyword arguments (e.g. autodiff = :forward) can be passed directly to Optim.optimize through extra keyword arguments. See the Optim documentation for more details on the available options.

An extra additive regularizer to either the objective or the bias-reducing penalized objective can be suplied via the keyword argument regularizer, which must be a scalar-valued function of the parameters and the data; the default value will result in no regularization.

lower and upper can be used to provide box contraints. If valid lower and upper vectors are supplier, then the internal call to Optim.optimize will use Fminbox(optim_method) as a method; see the Optim documentation on box minimization for more details.

fit(template::estimating_function_template,
    data::Any,
    theta::Vector{Float64};
    estimation_method::String = "M",
    br_method::String = "implicit_trace",
    concentrate::Vector{Int64} = Vector{Int64}(),
    regularizer::Function = function regularizer(theta::Vector{Float64}, data::Any) Vector{Float64}() end,
    nlsolve_arguments...)

Fit an estimating_function_template on data using M-estimation (estimation_method = "M"; default) or RBM-estimation (reduced-bias M estimation; Kosmidis & Lunardon, 2020; estimation_method = "RBM")

Arguments

• template: an estimating_function_template object.
• data: typically an object of composite type with all the data required to compute the objective_function.
• theta: a Vector{Float64} of parameter values to use as starting values in Optim.optimize.

Keyword arguments

• estimation_method: either "M" (default) or "RBM"; see Details.
• br_method: either "implicittrace" (default) or "explicittrace"; see Details.
• concentrate: a Vector{Int64}; if specified, empirical bias-reducing adjustments are added only to the subset of estimating functions indexed by concentrate. The default is to add empirical bias-reducing adjustments to all estimating functions.
• regularizer: a function of theta and data returning a Vector{Float64} of dimension equal to the number of the estimating functions, which is added to the (bias-reducing) estimating function; the default value will result in no regularization.
• nlsolve_arguments...: extra keyword arguments to be passed to NLsolve.nlsolve. See Details.

Details

Bias reduction is either through the solution of the empirically adjusted estimating functions in Kosmidis & Lunardon (2020) (br_method = "implicit_trace"; default) or by subtracting an estimate of the bias from the M-estimates (br_method = "explicit_trace"). The bias-reducing adjustments and the bias estimate are constructed internally using automatic differentiation (using the ForwardDiff package).

Bias reduction for only a subset of parameters can be performed by setting concentrate to the vector of the indices for those parameters.

The solution of the estimating equations or the adjusted estimating equations is done using the NLsolve package. Keyword arguments can be passed directly to NLsolve.nlsolve through extra keyword arguments. See the NLsolve README for more information on available options.

An extra additive regularizer to either the estimating functions or the bias-reducing adjusted estimating functions can be suplied via the keyword argument regularizer, which must be a length(theta)-valued function of the parameters and the data; the default value will result in no regularization.

coef(results::MEstimation_results)

Extract the parameter estimates from a MEstimation_results object.

Arguments

• results: a MEstimation_results object.

Details

coef(results) returns results.theta

vcov(results::MEstimation_results)

Compute an estimate of the variance-covariance matrix of the M-estimator or its reduced-bias version at results.theta, from a MEstimation_results object.

Arguments

• results: a MEstimation_results object.

Result

The length(coef(results)) times length(coef(results)) estimated variance covariance matrix for the parameters. This matrix is the empirical sandwich variance covariance matrix for M- and RBM-estimators. See, for example, Stefanski and Boos (2002, expression 10).

stderror(results::MEstimation_results)

Compute estimated standard errors from a from a MEstimation_results object.

Arguments

• results: a MEstimation_results object.

Details

The estimated standard errors are computed as sqrt.(diag(vcov(results))).

coeftable(results::MEstimation_results; 
          level::Real=0.95)

Return a StatsBase.CoefTable from a MEstimation_results object.

Arguments

• results: a MEstimation_results object.

Keyword arguments

• level: a Real that determines the level of the reported confidence intervals; default is 0.95; see Details.

Details

The reported confidence intervals are Wald-type of nominal level level, using quantiles of the standard normal distribution.

tic(results::MEstimation_results)

Compute the Takeuchi Information Criterion at results.theta, from a MEstimation_results object.

Arguments

• results: a MEstimation_results object.

Details

nothing is returned if results.template is an estimating_function_template.

aic(results::MEstimation_results)

Compute the Akaike Information Criterion at results.theta, from a MEstimation_results object with an objective_function_template.

Arguments

• results: a MEstimation_results object.

Details

nothing is returned if results.template is an estimating_function_template.

slice(results::MEstimation_results,
      what::Int64;
      grid::Vector{Float64} = Vector{Float64}(),
      at::Vector{Float64} = Vector{Float64}(),
      n_points::Int64 = 50,
      n_sd::Real = 2)

Compute 1-dimensional slices of objective functions and estimating function surfaces for the parameter what over a grid of points grid, from a MEstimation_results object.

Arguments

• results: An MEstimation_results object.
• what: the index of the parameter for which to compute a slice for

Keyword arguments

• grid: a Vector{Float64}; if supplied, the slice is computed at each element of grid. The default will result in the automatic calculation of the grid; see Details.
• at: a Vector{Float64} of the sample length as coef(results), specifying the parameter values at which to compute the slice. The default results in computing the slice at coef(results).
• n_points: an Int64 specifying the number of grid points to generate. Applicable only if grid is not supplied; see Details.
• n_sd: an Int64 specifying the number of standard errors to be used for the grid generation. Applicable only if grid is not supplied; see Details.

Result

A Dict with keys "grid" and "slice", holding grid and the values of the slice at grid, respectively.

Details

The default value of grid will result in the automatic calculation of a grid of n_points points, between coef(results)[what] - n_sd * stderror(results)[what] and coef(results)[what] + n_sd * stderror(results)[what].