R/05a_control.R

In rdmatheus/BCNSM: Multivariate Box-Cox Symmetric Distributions Generated by a Normal Scale Mixture Copula

#' Optimization Control Parameters Passed to Optim
#'
#' Optimization parameters passed to \code{\link[stats]{optim}} for the fit of a multivariate
#'     Box-Cox symmetric distribution generated by a normal scale mixture copula. This function acts
#'     in the same spirit as \code{\link[betareg]{betareg.control}} from the \code{betareg} package.
#'     Its primary purpose is to gather all the optimization control arguments in a single function.
#'
#' @param method the method to be used. See 'Details' in \code{\link[stats]{optim}}. The default
#'     method (\code{"BFGS"}) is a quasi-Newton method (also known as a variable metric algorithm),
#'     specifically that published simultaneously in 1970 by Broyden, Fletcher, Goldfarb and Shanno.
#' @param maxit the maximum number of iterations of the algorithm. Defaults to \code{2000}.
#' @param hessian logical. Should a numerically differentiated Hessian matrix be returned?
#' @param start an optional vector with starting values for all parameters for fitting a BCNSM
#'     distribution. It must be passed in the order: \code{(mu, sigma, lambda, nu, gamma)}, where
#'     \code{mu}, \code{sigma}, \code{lambda}, and \code{nu} are parameters associated with marginal
#'     distributions and \code{gamma} are parameters related to the association matrix.
#' @param mu_inits initial values for the scale parameters of the marginal distributions.
#' @param sigma_inits initial values for the relative dispersion parameters of the marginal distributions.
#' @param lambda_inits initial values for the skewness parameters of the marginal distributions.
#' @param nu_inits initial values for the heavy-tailness parameters of the marginal distributions.
#' @param gamma_inits initial values for the parameters related to the association matrix.
#' @param ... further arguments to be passed to \code{\link[stats]{optim}}.
#'
#' @references Cribari-Neto, F., and Zeileis, A. (2010). Beta regression in R.
#'     \emph{Journal of statistical software}, 34, 1-24.
#'
#' Vanegas, L. H., and Paula, G. A. (2016). Log-symmetric distributions: statistical properties and
#'     parameter estimation. \emph{Brazilian Journal of Probability and Statistics}, 30, 196-220.
#'
#' Ferrari, S. L. P., and Fumes, G. (2017). Box-Cox symmetric distributions and applications to
#'     nutritional data. \emph{AStA Advances in Statistical Analysis}, 101, 321-344.
#'
#' Medeiros, R. M. R. de, and Ferrari, S. L. P. (2024). Multivariate Box-Cox symmetric distributions
#'     generated by a normal scale mixture copula.
#'
#' @author Rodrigo M. R. de Medeiros <\email{rodrigo.matheus@live.com}>
#'
#' @return A list with the arguments specified.
#' @export
control_fit <- function(method = "BFGS", maxit = 2000, hessian = TRUE, start = NULL,
                        mu_inits = NULL, sigma_inits = NULL, lambda_inits = NULL,
                        nu_inits = NULL, gamma_inits = NULL, ...) {
  rval <- list(
    method = method, maxit = maxit, hessian = hessian,
    start = start, mu_inits = mu_inits, sigma_inits = sigma_inits,
    lambda_inits = lambda_inits, nu_inits = nu_inits, gamma_inits = gamma_inits
  )

  rval <- c(rval, list(...))

  if (!is.null(rval$fnscale)) {
    warning("fnscale must not be modified\n")
  }

  rval$fnscale <- -1

  rval
}