pw_solver_control: Control Solver Settings for Pseudo-Weight Estimation

Description

pw_solver_control() creates a solver control object used by est_pw to manage numerical settings for pseudo-weight estimation.

Usage

pw_solver_control(
  solver = "nleqslv",
  maxit = NULL,
  trace = FALSE,
  method = c("Newton", "Broyden"),
  global = c("dbldog", "cline", "pwldog", "qline", "gline", "hook", "none"),
  xscalm = c("fixed", "auto"),
  ftol = 1e-08,
  xtol = 1e-08,
  nleqslv_control = list()
)

Value

A flat list containing all solver control settings for pseudo-weight estimation:

solver: The selected numerical solver.

method

The nleqslv numerical method.

global

The nleqslv global strategy.

xscalm

The nleqslv scaling method.

ftol

The function-value convergence tolerance.

xtol

The parameter-step convergence tolerance.

maxit

The maximum number of solver iterations, stored as an integer. 150 if a global strategy is used; 20 if global = "none". Since the default global strategy is "dbldog", the effective default is 150 unless global = "none" is explicitly specified.

trace

Logical value indicating whether tracing information is requested.

nleqslv_control

A list of additional options passed to nleqslv::nleqslv().

Arguments

solver: Character string specifying the numerical solver used for solving the estimating equations. Currently, only "nleqslv" is supported. Default is "nleqslv".
maxit: Positive finite numeric value passed to nleqslv::nleqslv() as the maximum number of solver iterations. The value is converted to an integer before being stored in the returned control object. Default is 150 when a global strategy is specified (i.e., global != "none"), and 20 when no global strategy is used (global = "none"), matching nleqslv's own defaults. Since the default global strategy is "dbldog", the effective default is 150 unless global = "none" is explicitly specified.
trace: Logical. If TRUE, tracing or solver progress information may be requested from the underlying numerical routine when supported. Default is FALSE.
method: Character string specifying the numerical method passed to nleqslv::nleqslv(). Supported values are "Newton" and "Broyden". Default is "Newton".
global: Character string specifying the global strategy passed to nleqslv::nleqslv(). Supported values are "dbldog", "cline", "pwldog", "qline", "gline", "hook", and "none". Default is "dbldog".
xscalm: Character string specifying the scaling method passed to nleqslv::nleqslv(). Supported values are "fixed" and "auto". Default is "fixed".
ftol: Positive finite numeric value passed to nleqslv::nleqslv() as the function-value convergence tolerance. This controls convergence based on the size of the estimating function. Default is 1e-8.
xtol: Positive finite numeric value passed to nleqslv::nleqslv() as the parameter-step convergence tolerance. This controls convergence based on changes in the parameter vector. Default is 1e-8.
nleqslv_control: A list of additional control options passed to nleqslv::nleqslv(). This can include less commonly used control options, such as btol, cndtol, sigma, and scalex. See nleqslv for details.

Details

The control object stores solver settings used by pseudo-weight estimation step. It is passed to est_pw through the control argument.

Currently, only solver = "nleqslv" is supported. The arguments method, global, xscalm, ftol, xtol, and maxit correspond to options used by nleqslv::nleqslv(). They are collected internally and passed to nleqslv::nleqslv() at the pseudo-weight estimation step.

The argument ftol is the function-value convergence tolerance. It controls convergence based on the size of the estimating function. The argument xtol is the parameter-step convergence tolerance. It controls convergence based on changes in the parameter vector. The argument maxit controls the maximum number of solver iterations.

Additional, less commonly used nleqslv control options can be supplied through nleqslv_control. To avoid ambiguity, do not supply ftol, xtol, maxit, or trace inside nleqslv_control; use the main arguments instead.

Examples

Run this code

## Default solver control settings
ctrl <- pw_solver_control()

## Custom nleqslv solver settings
ctrl <- pw_solver_control(
  maxit  = 20,
  trace  = FALSE,
  method = "Newton",
  global = "cline",
  xscalm = "auto",
  ftol   = 1e-8,
  xtol   = 1e-10
)

## Additional nleqslv control options
ctrl <- pw_solver_control(
  method = "Newton",
  global = "dbldog",
  nleqslv_control = list(
    btol = 1e-3
  )
)