Skip to content

Model Estimation

Jump to bottom
Ivan Svetunkov edited this page Jun 16, 2026 · 8 revisions

title: Model Estimation slug: Model-Estimation summary: Estimation arguments: optimiser, information criterion, FI Hessian, advanced options. status: stable applies_to: [adam] related: [ADAM, Loss-Functions, Bounds, Coefficients-and-Parameters]

Model Estimation

This page documents the estimation parameters shared across ADAM and related functions. These parameters control the optimisation process, initial values, and advanced estimation options.

At a glance

Argument Type Default Valid values Applies to
ic string "AICc" "AIC", "AICc", "BIC", "BICc" All forecasting functions.
bounds string "usual" (CES/SSARIMA: "admissible") See Bounds. All forecasting functions.
silent (R) / verbose (Python) logical / int R: TRUE. Python: 0. R: TRUE/FALSE. Python: 0–3. All forecasting functions.
FI (R only) logical FALSE TRUE/FALSE R adam, om, omg. Python computes the FD-Hessian inside vcov() automatically.
stepSize (R) / step_size (Python) numeric ~1.22e-4 (= ε^(1/4)) Positive float. FI / vcov calculation.
nIterations (R) / n_iterations (Python) int 2 Positive int. Backcasting refinement loops.
smoother string "global" "global", "lowess", "ma", "supsmu" (R-only) adam / ADAM, used by msdecompose.
NLopt options R: .... Python: nlopt_kargs dict. Algorithm-specific. See NLopt Optimizer Parameters below. All.

NLopt Optimizer Parameters

The smooth package uses NLopt for numerical optimisation. These parameters control the optimisation behaviour:

Parameter R (via ...) Python (via nlopt_kargs) Default Description
algorithm Yes Yes "NLOPT_LN_NELDERMEAD" Optimiser algorithm
maxeval Yes Yes 40×len(B) Maximum evaluations
maxtime Yes Yes None/1800s Maximum time (seconds)
xtol_rel Yes Yes 1e-6 Relative parameter tolerance
xtol_abs Yes Yes 1e-8 Absolute parameter tolerance
ftol_rel Yes Yes 1e-8 Relative function tolerance
ftol_abs Yes Yes 0 Absolute function tolerance
print_level Yes Yes 0 Verbosity (0=silent, 3=detailed, 41=initials + final output)

The parameters are documented in the nlopt project.

R Usage

# Pass NLopt parameters via ...
model <- adam(y, model="AAN",
              algorithm="NLOPT_LN_SBPLX",
              maxeval=1000,
              maxtime=600,
              xtol_rel=1e-8,
              print_level=1)

Python Usage

# Pass NLopt parameters via nlopt_kargs dict
model = ADAM(model="AAN", nlopt_kargs={
             "algorithm": "NLOPT_LN_SBPLX",
             "maxeval": 1000,
             "maxtime": 600,
             "xtol_rel": 1e-8,
             "print_level": 1
})
model.fit(y)

Initial Parameter Vector (B)

B is the flat vector of all parameters passed to the optimizer. Providing it overrides the automatically computed starting point. Providing lb/ub replaces the automatically computed bounds entirely — the values are used as-is without adjustment.

The order of parameters in B depends on what the model estimates:

  1. Smoothing parameters (alpha, beta, gamma, delta) — always first
  2. Damping parameter (phi) — if a damped trend is used
  3. ARMA coefficients — if ARIMA components are present
  4. Initial ETS states (level, trend, seasonal) — only when initial="optimal" or "two-stage"
  5. Initial ARIMA states — only when initial="optimal" or "two-stage"
  6. External regressor coefficients — if regressors is not "complete"
  7. Constant term — if included

With the default initial="backcasting", initial states are not in B, so for a simple AAN model B is just [alpha, beta].

R Usage

In R, B, lb, and ub are passed via ... to adam(). They are flat numeric vectors in the same order as B above.

# AAN with backcasting: B = [alpha, beta]
model <- adam(y, model="AAN",
              B=c(0.3, 0.1),   # starting point: alpha=0.3, beta=0.1
              lb=c(0, 0),      # lower bounds
              ub=c(1, 1))      # upper bounds

# ANA (no trend) with backcasting: B = [alpha, gamma]
model <- adam(y, model="ANA", lags=12,
              B=c(0.4, 0.2),
              lb=c(0.1, 0.05),
              ub=c(0.9, 0.5))

If B is outside the supplied bounds, R adjusts the bounds slightly to accommodate it.

Python Usage

In Python, pass B_initial, lb, and ub inside nlopt_kargs. When provided, they are used exactly as given — the internally computed starting point and bounds are not used.

# AAN with backcasting: B = [alpha, beta]
model = ADAM(model="AAN",
             nlopt_kargs={
                 "B_initial": [0.3, 0.1],   # starting point: alpha=0.3, beta=0.1
                 "lb": [0, 0],              # lower bounds
                 "ub": [1, 1],              # upper bounds
             })
model.fit(y)

# ANA (no trend) with backcasting: B = [alpha, gamma]
model = ES(model="ANA", lags=12,
           nlopt_kargs={
               "B_initial": [0.4, 0.2],
               "lb": [0.1, 0.05],
               "ub": [0.9, 0.5],
           })
model.fit(y)

You can supply only some of the three — for example, set bounds without fixing a starting point:

# Override only bounds, keep automatic starting point
model = ADAM(model="AAN",
             nlopt_kargs={"lb": [0.05, 0.01], "ub": [0.8, 0.4]})
model.fit(y)

See Bounds for details on parameter boundaries and stability restrictions.

Smoother Parameter

The smoother parameter controls how msdecompose smooths the time series for initialisation. Available options:

Value R Python Description
"global" Yes Yes Global mean (no smoothing) — default
"lowess" Yes Yes LOcally WEighted Scatterplot Smoothing
"ma" Yes Yes Moving Average
"supsmu" Yes No Friedman's SuperSmoother

Note: Starting from smooth for R v4.4.1 and Python v1.0.1, the default smoother has changed from "lowess" to "global". This is needed to make the work of backcasting initialisation more efficient.

R Usage

model <- adam(y, model="AAN")               # uses global by default
model <- adam(y, model="AAN", smoother="lowess")

Python Usage

model = ADAM(model="AAN")                   # uses global by default
model = ADAM(model="AAN", smoother="lowess")
model.fit(y)

See msdecompose for more details on the decomposition process.

Fisher Information

The Fisher Information matrix can be computed for uncertainty quantification. R exposes it as a top-level argument to adam(); Python computes the FD-Hessian inside vcov() instead of as a separate argument (see R-Python-differences for the shared FD-Hessian implementation).

Parameter R Default Description
FI Yes FALSE Whether to compute the Fisher Information matrix.
stepSize Yes ~1.22e-4 Step size for Hessian calculation.

R Usage

model <- adam(y, model="AAN",
              FI=TRUE,
              stepSize=1e-5)

# Access Fisher Information
model$FI

The Fisher Information is used for computing standard errors and confidence intervals of parameters. This is done automatically by the vcov() method in R, see Coefficients-and-Parameters.

Backcasting Iterations

Backcasting is used to refine initial state estimates by iterating between forward and backward passes:

Parameter R Python Default Description
nIterations Yes - 2 Number of backcasting iterations
n_iterations - Yes 2 Number of backcasting iterations

R Usage

model <- adam(y, model="AAN", nIterations=5)

Python Usage

model = ADAM(model="AAN", n_iterations=5)
model.fit(y)

Higher values may improve initial state estimates but increase computation time.

Related Pages

  • Initialisation - State initialisation methods
  • Loss-Functions - Loss functions for estimation
  • Bounds - Parameter bounds and stability
  • ADAM - Main ADAM function documentation
  • ES - Exponential Smoothing documentation

References

  • Svetunkov, I. (2023). Forecasting and Analytics with the Augmented Dynamic Adaptive Model (ADAM). Chapman and Hall/CRC. Online: https://openforecast.org/adam/.

Clone this wiki locally