estimate_model: Estimate LNRE Model Parameters (zipfR)

In zipfR: Statistical Models for Word Frequency Distributions

Description

Internal function: Generic method for estimation of LNRE model parameters. Based on the class of its first argument, the method dispatches to a suitable implementation of the estimation procedure.

Unless you are a developer working on the zipfR source code, you are probably looking for the lnre manpage.

Usage

  estimate.model(model, spc, param.names,
                 method, cost.function, m.max=15,
                 runs=3, debug=FALSE, ...)

Arguments

model	LNRE model object of the appropriate class (a subclass of lnre). All parameters of the LNRE model that are not listed in param.names must have been initialized to their prespecified values in the model object.
spc	an observed frequency spectrum, i.e. an object of class spc. The values of the missing parameters will be estimated from this frequency spectrum.
param.names	a character vector giving the names of parameters for which values have to be estimated ("missing" parameters)
method	name of the minimization algorithm used for parameter estimation (see lnre for details)
cost.function	cost function to be minimized (see lnre for details). NB: this is a direct reference to the function object rather than just the name of the cost function. Look-up of the appropriate cost function implementation is performed in the lnre constructor.
m.max	number of spectrum elements that will be used to compute the cost function (passed on to cost.function)
runs	number of parameter optimization runs with random initialization. Parameters from the run that achieves the smallest value of the cost function will be selected. Some method implementations may not support multiple optimization runs.
debug	if TRUE, some debugging and progress information will be printed during the estimation procedure
...	additional arguments are passed on and may be used by some implementations

Details

By default, estimate.model dispatches to a generic implementation of the estimation procedure that can be used with all types of LNRE models (estimate.model.lnre).

This generic implementation can be overridden for specific LNRE models, e.g. to calculate better init values or improve the estimation procedure in some other way. To provide a custom implementation for Zipf-Mandelbrot models (of class lnre.zm), for instance, it is sufficient to define the corresponding method implementation estimate.model.lnre.zm. If no custom implementation is provided but the user has selected the Custom method (which is the default), estimate.model falls back on Nelder-Mead for multi-dimensional minimization and NLM for one-dimensional minimization (where Nelder-Mead is considered to be unreliable).

Parmeter estimation is performed by minimization of the cost function passed in the cost.function argument (see lnre for details). Depending on the method argument, a range of different minimization algorithms can be used (see lnre for a complete listing). The minimization algorithm always operates on transformed parameter values, making use of the transform utility provided by LNRE models (see lnre.details for more information about utility functions). All parameters are initialized to 0 in the transformed scale, which should translate to sensible starting points.

Note that the estimate.model implementations do not perform any error checking. It is the responsibility of the caller to make sure that the arguments are sensible and complete. In particular, all model parameters that will not be estimated (i.e. are not listed in param.names) must have been initialized to their prespecified values in the model passed to the function.

Value

A modified version of model, where the missing parameters listed in param.names have been estimated from the observed frequency spectrum spc. In addition, goodness-of-fit information is added to the object.

See Also

The user-level function for estimating LNRE models is lnre. Its manpage also lists available cost functions and minimization algorithms.

The internal structure of lnre objects (representing LNRE models) is described on the lnre.details manpage, which also outlines the necessary steps for implementing a new LNRE model.

The minimization algorithms used are described in detail on the nlm and optim manpages from R's standard library.

zipfR documentation built on Jan. 8, 2021, 2:37 a.m.