CGNM-package: CGNM: Cluster Gauss-Newton Method

In CGNM: Cluster Gauss-Newton Method

CGNM: Cluster Gauss-Newton Method

Description

Cluster Gauss-Newton method (CGNM) finds multiple approximate minimizers of a nonlinear least squares problem argmin_x||f(x)-y*||, without assuming the minimizer is unique. In the context of model fitting, f is the model, x is the parameter vector, and y* is the observed data.

Typical workflow

1. Cluster_Gauss_Newton_method — fit the model; returns a CGNM_result list (fields X, Y, residual_history, initialX, runSetting).

2. Cluster_Gauss_Newton_Bootstrap_method (optional) — residual resampling bootstrap using the fit above, for uncertainty quantification.

3. acceptedApproximateMinimizers / acceptedIndices / bestApproximateMinimizers — select the subset of the found minimizers considered to have converged to (approximately) the same minimum sum of squared residuals.

4. table_parameterSummary — tabulate parameter estimates across the accepted minimizers.

5. plot_Rank_SSR, plot_goodnessOfFit, plot_paraDistribution_byHistogram, plot_paraDistribution_byViolinPlots, plot_parameterValue_scatterPlots, plot_profileLikelihood, plot_2DprofileLikelihood — visualize the fit (ggplot2 must be loaded by the user).

Conventions worth knowing before calling these functions

• "Unset" is NA, not NULL. Arguments such as lowerBound, upperBound, ParameterNames, and initialIterateMatrix default to NA to mean "not supplied". Passing NULL instead of NA may error rather than being treated as unset.

• saveLog=TRUE is the default for Cluster_Gauss_Newton_method() and writes iteration history to a CGNM_log (or CGNM_log_<runName>) folder under the current working directory. plot_profileLikelihood, compare_profileLikelihood, table_profileLikelihoodConfidenceInterval, plot_SSRsurface, suggestInitialLowerRange, and suggestInitialUpperRange all need that per-iteration history (a single final result normally only keeps the first and last iteration); they accept the folder path (a string, or vector of strings), the classic list (looked up from the object's own runName, so the log must still be on disk), or an outputS4 = TRUE object that retains this history in memory (see below) and needs no disk access at all.

• nonlinearFunction may be written either as vector-in/vector-out (one parameter set at a time) or matrix-in/matrix-out (one parameter set per row, for parallelization); see the Parallel computation section of vignette("CGNM-vignette", package = "CGNM").

• The classic return value is a plain list, unless you opt into outputS4 = TRUE. Cluster_Gauss_Newton_method, Cluster_Gauss_Newton_Bootstrap_method, and Cluster_Gauss_Newton_EBE_method all accept this argument (default FALSE) and return a CGNM_result-class S4 object instead, with every field still reachable via $/[[ exactly as on the list, so all postprocessing/plotting functions accept either form unmodified. This lets calling code confirm inherits(x, "CGNM_result") instead of assuming a bare list has the right shape. It also retains the per-iteration history needed for the profile-likelihood functions above (main fit, and the bootstrap run's own history too if Cluster_Gauss_Newton_Bootstrap_method is subsequently run on the object), so those functions work directly on the returned object with no saveLog/disk dependency at all.

See vignette("CGNM-vignette", package = "CGNM") for a full worked example, and the top-level CLAUDE.md / README.md in the package source repository for a condensed quick-start reference.

Author(s)

Maintainer: Yasunori Aoki [e-mail]

Authors:

• Yasunori Aoki [e-mail]

References

Aoki et al. (2020) Cluster Gauss-Newton method. Optimization and Engineering, 1-31. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1007/s11081-020-09571-2")}

Aoki and Sugiyama (2024) Cluster Gauss-Newton method for a quick approximation of profile likelihood: With application to physiologically-based pharmacokinetic models. CPT Pharmacometrics Syst Pharmacol. 13(1):54-67. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1002/psp4.13055")}

CGNM documentation built on Sept. 13, 2026, 9:06 a.m.