doGauge: Gauge onls against published, closed-form, ODRPACK and NIST...

In onls: Orthogonal Nonlinear Least-Squares Regression

Gauge onls against published, closed-form, ODRPACK and NIST reference values

Description

Runs the demo gauge of the package, which fits the reference problems of orthogonal distance regression and compares every result of onls (parameters, standard errors, objective) with a reference value, and shows or writes its complete output (code and results). The result of each comparison (PASS, NOTE or DIFF) is highlighted. A summary of all comparisons is printed and returned.

Usage

doGauge(output = c("console", "html", "pdf"), outdir = tempdir(), fontsize = 14,
        silent = TRUE, file = system.file("demo", "gauge.R", package = "onls"))

Arguments

output	"console" (default): the output is printed; "html" or "pdf": it is written to the file onls-gauge.html or onls-gauge.pdf in outdir.
outdir	the directory in which the HTML or PDF file is written. The default is a temporary directory; use, e.g., getwd() to keep the file.
fontsize	the font size of the output in pixels (HTML); for PDF, the size is scaled accordingly and reduced if necessary, so that the longest line fits the page width.
silent	logical. If TRUE, messages and warnings issued while the demo runs are suppressed.
file	the demo file; only needed to run a modified copy of the demo.

Details

The demo contains five kinds of comparison (column 2 of the output):

• published: values printed in the cited publications: the ODRPACK User's Reference Guide (example 2.C.i), Algorithm 676 (ODRPACK), the bounded example of ODRPACK95 (TOMS 869), Pearson's data with York's weights (York 1966; values of the York et al. 2004 equations, as reported by the R package 'bfsl'), Daeron & Vermeesch (2024, Table 3) and the XLSTAT Deming regression example. The tolerance is half a unit of the last printed decimal; for results of iterative ODRPACK runs, the convergence of that run is added (10^{-3} of the standard error for parameters, a relative 10^{-4} for standard errors and 10^{-7} for the objective).

• closed form: exact solutions computed in the demo: total least squares and generalized (correlated-error) total least squares by singular value decomposition (Golub & Van Loan 1980), and Deming regression; relative tolerance 10^{-6}.

• ODRPACK: ODRPACK 2.01 (Boggs et al. 1989) through scipy.odr 1.18.1, with the same data, model, weights and starting values, run to convergence (sstol = partol = 1e-14), for problems without published orthogonal-regression results: the example with separate response and predictor weights (ODRPACK's WE, WD), and the NIST problems Chwirut2, Gauss1, ENSO and the Rat43 data (Gompertz model) as orthogonal regressions with unit precisions. Parameters are compared to 10^{-3} of their standard error, standard errors to a relative 10^{-4}, the objective to a relative 10^{-7}.

• consistency: properties that must hold (the functions around the fit, and the agreement of the two algorithms); PASS if the property holds.

• NIST: the certified values of the NIST StRD nonlinear regression data sets Chwirut2, Gauss1, ENSO and Rat43, which refer to ordinary least squares. With a negligible sigma_x, the orthogonal fit becomes ordinary least squares, so onls must reproduce the certified parameters (relative tolerance 10^{-6}) and residual sums of squares (10^{-9}).

Results:

• PASS: agreement within the tolerance.

• NOTE: a documented discrepancy of the reference, explained in a comment of the demo (the ODRPACK95 reference run reports a higher objective than the bounded optimum; a truncated instead of rounded published value).

• DIFF: a deviation that is neither within the tolerance nor documented. The expected result is DIFF = 0.

The demo can also be run directly with demo("gauge", package = "onls"). It replaces the reference examples of onls and the function NIST of earlier versions.

Value

Invisibly, a list with

file	the path of the file written (NULL for output = "console").
results	a data frame with one row per comparison: item, kind (of reference), reference, onls, diff, tol and result.
summary	a table with the numbers of PASS, NOTE and DIFF.

Author(s)

Andrej-Nikolai Spiess

References

ALGORITHM 676 ODRPACK: Software for Weighted Orthogonal Distance Regression.
Boggs PT, Donaldson JR, Byrd RH and Schnabel RB.
ACM Trans Math Soft (1989), 15, 348-364.
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.1145/76909.76913")}

User's Reference Guide for ODRPACK Version 2.01. Software for Weighted Orthogonal Distance Regression.
Boggs PT, Byrd RH, Rogers JE and Schnabel RB.
NISTIR (1992), 4834: 1-113.

Algorithm 869: ODRPACK95: A weighted orthogonal distance regression code with bound constraints.
Zwolak JW, Boggs PT and Watson LT.
ACM Trans Math Soft (2007), 33: 27.
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.1145/1268776.1268782")}

Least squares fitting of a straight line.
York D.
Canadian Journal of Physics (1966), 44: 1079-1086.
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.1139/p66-090")}

Unified equations for the slope, intercept, and standard errors of the best straight line.
York D, Evensen NM, Martinez ML and De Basabe Delgado J.
American Journal of Physics (2004), 72: 367-375.

Omnivariant generalized least squares regression.
Daeron M and Vermeesch P.
Chemical Geology (2024), 647: 121881.
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.chemgeo.2023.121881")}

An analysis of the Total Least Squares problem.
Golub GH and Van Loan CF.
SIAM Journal on Numerical Analysis (1980), 17: 883-893.
\Sexpr[results=rd]{tools:::Rd_expr_doi("10.1137/0717073")}

Statistical Reference Datasets (StRD), nonlinear regression.
National Institute of Standards and Technology.
https://www.itl.nist.gov/div898/strd/nls/nls_main.shtml

See Also

onls, check_o.

Examples

res <- doGauge()
res$summary
## HTML file in the working directory:
## doGauge(output = "html", outdir = getwd())

onls documentation built on Nov. 9, 2026, 5:06 p.m.