Specifies control parameters for the model estimation process in [estimate].

set_estimation_opt(
  initial_parameters = NULL,
  fixed_parameters = NULL,
  max_iterations = 20,
  convergence_criterion = 0.001,
  initial_damping = NULL,
  damping_increase_factor = 2,
  damping_decrease_factor = 3,
  return_interval_loglik = FALSE,
  return_probabilities = FALSE,
  engine = c("default_c", "default", "gather_compute")
)

Arguments

initial_parameters

A numeric vector. It includes initial parameter values used to initialize the estimation process. Default is NULL, which means parameters are initialized at zero, except for the rate intercept when present.

fixed_parameters

A numeric vector of the same length as the number of parameters to be estimated in the model. NA values indicate parameters to be estimated, while numeric values indicate parameters to be fixed at the given value. For example, if the vector is c(2, NA) then the first component of the parameter is fixed to 2 during the estimation process. Default is NULL (all parameters are estimated).

max_iterations

An integer. The maximum number of iterations in the Gauss-Fisher scoring algorithm. Default is 20.

convergence_criterion

A numeric value. The convergence criterion for the estimation. The algorithm stops if the sum of absolute scores is smaller than this value. Default is 0.001.

initial_damping

A numeric value. The initial damping factor for the Gauss-Fisher scoring algorithm. Default is NULL, which allows estimate_dynam(), estimate_rem() and estimate_dynami() to set a context-dependent default (e.g., 30 or 10 based on wheter the model has windows effects). If set, this value is used directly.

damping_increase_factor

A numeric value. Factor by which damping is increased when improvements in the estimation are found. Must be >= 1. Default is 2.

damping_decrease_factor

A numeric value. Factor by which damping is decreased when no improvements in the estimation are found. Must be >= 1. Default is 3.

return_interval_loglik

A logical value. Whether to keep and return the log-likelihood for each event. Default is FALSE.

return_probabilities

A logical value. Whether to keep and return the probabilities for all alternatives for each event.

  • When subModel = "choice" the probabilities correspond to all actors in the choice set present at the time of the event.

  • When model = "REM" the probabilities correspond to all dyads present at the time of the event. Default is FALSE.

engine

A character string specifying the estimation engine. Options are:

default_c

C++ based implementation using RcppEigen and RcppParallel.

default

R-based implementation.

gather_compute

C++ based implementation with a different data structure that reduces the time but it can increase the memory usage.

Default is "default_c".

Value

An object of class estimation_opt.goldfish (a list object), where the components values are the default values or the values provided to the function. The list object has the following components:

initial_parameters

Initial parameter values used during the estimation process.

fixed_parameters

Values for parameters fixed during the estimation process.

max_iterations

Maximum number of iterations in the estimation process.

convergence_criterion

Convergence criterion for the estimation process.

initial_damping

Initial damping factor for the estimation process.

damping_increase_factor

Factor by which damping is increased when improvements in the estimation are found.

damping_decrease_factor

Factor by which damping is decreased when no improvements in the estimation are found.

return_interval_loglik

Logical value indicating whether to return the log-likelihood for each event.

engine

Estimation engine used in the estimation process.

Details

The damping factors arguments control the step size at each iteration of the Newton-Raphson algorithm. They have a bigger impact in the first iterations of the algorithm and will decrease by half after each iteration. In particular, the increase factor is the one that is expected to play a role during the first iterations where it's easier to improve the log-likelihood. In scenarios where the model is fit in a large dataset, for example, when the number of actors in the system is large, the damping_increase_factor and the damping_decrease_factor arguments can be increased from the default values (e.g., 4 or 6) to speed up the estimation process with large changes in the coefficients. However, this should have the opposite effect in small datasets producing large changes in the coefficients that would create more iterations (in a similar vein to the step size parameter in gradient descendent).

Examples

est_ctrl <- set_estimation_opt(
  max_iterations = 50,
  convergence_criterion = 1e-4
)