Stata 15 help for ucm

[TS] ucm -- Unobserved-components model


ucm depvar [indepvars] [if] [in] [, options]

options Description ------------------------------------------------------------------------- Model model(model) specify trend and idiosyncratic components seasonal(#) include a seasonal component with a period of # time units cycle(# [, frequency(#f)]) include a cycle component of order # and optionally set initial frequency to #f, 0 < #f < pi; cycle() may be specified up to three times constraints(constraints) apply specified linear constraints collinear keep collinear variables

SE/Robust vce(vcetype) vcetype may be oim or robust

Reporting level(#) set confidence level; default is level(95) nocnsreport do not display constraints display_options control columns and column formats, row spacing, display of omitted variables and base and empty cells, and factor-variable labeling

Maximization maximize_options control the maximization process

coeflegend display legend instead of statistics -------------------------------------------------------------------------

model Description ------------------------------------------------------------------------- rwalk random-walk model; the default none no trend or idiosyncratic component ntrend no trend component but include idiosyncratic component dconstant deterministic constant with idiosyncratic component llevel local-level model dtrend deterministic-trend model with idiosyncratic component lldtrend local-level model with deterministic trend rwdrift random-walk-with-drift model lltrend local-linear-trend model strend smooth-trend model rtrend random-trend model -------------------------------------------------------------------------

You must tsset your data before using ucm; see [TS] tsset. indepvars may contain factor variables; see fvvarlist. indepvars and depvar may contain time-series operators; see tsvarlist. by, fp, rolling, and statsby are allowed; see prefix. coeflegend does not appear in the dialog box. See [TS] ucm postestimation for features available after estimation.


Statistics > Time series > Unobserved-components model


Unobserved-components models (UCMs) decompose a time series into trend, seasonal, cyclical, and idiosyncratic components and allow for exogenous variables. ucm estimates the parameters of UCMs by maximum likelihood.

All the components are optional. The trend component may be first-order deterministic or it may be first-order or second-order stochastic. The seasonal component is stochastic; the seasonal effects at each time period sum to a zero-mean finite-variance random variable. The cyclical component is modeled by the stochastic-cycle model derived by Harvey (1989).


+-------+ ----+ Model +------------------------------------------------------------

model(model) specifies the trend and idiosyncratic components. The default is model(rwalk). The available models are listed in Syntax above and discussed in detail in Models for the trend and idiosyncratic components in [TS] ucm.

seasonal(#) adds a stochastic-seasonal component to the model. # is the period of the season, that is, the number of time-series observations required for the period to complete.

cycle(#) adds a stochastic-cycle component of order # to the model. The order # must be 1, 2, or 3. Multiple cycles are added by repeating the cycle(#) option with up to three cycles allowed.

cycle(#, frequency(#f)) specifies #f as the initial value for the central-frequency parameter in the stochastic-cycle component of order #. #f must be in the interval (0, pi).

constraints(constraints), collinear; see [R] estimation options.

+-----------+ ----+ SE/Robust +--------------------------------------------------------

vce(vcetype) specifies the estimator for the variance-covariance matrix of the estimator.

vce(oim), the default, causes ucm to use the observed information matrix estimator.

vce(robust) causes ucm to use the Huber/White/sandwich estimator.

+-----------+ ----+ Reporting +--------------------------------------------------------

level(#), nocnsreport; see [R] estimation options.

display_options: noci, nopvalues, noomitted, vsquish, noemptycells, baselevels, allbaselevels, nofvlabel, fvwrap(#), fvwrapon(style), cformat(%fmt), pformat(%fmt), and sformat(%fmt); see [R] estimation options.

+--------------+ ----+ Maximization +-----------------------------------------------------

maximize_options: difficult, technique(algorithm_spec), iterate(#), [no]log, trace, gradient, showstep, hessian, showtolerance, tolerance(#), ltolerance(#), nrtolerance(#), and from(matname); see [R] maximize for all options except from(), and see below for information on from().

from(matname) specifies initial values for the maximization process. from(b0) causes ucm to begin the maximization algorithm with the values in b0. b0 must be a row vector; the number of columns must equal the number of parameters in the model; and the values in b0 must be in the same order as the parameters in e(b).

If you model fails to converge, try using the difficult option. Also see the technical note below example 5 in [TS] ucm.

The following option is available with ucm but is not shown in the dialog box:

coeflegend; see [R] estimation options.


--------------------------------------------------------------------------- Setup . webuse unrate

Fit a random-walk model on the civilian unemployment rate . ucm unrate

Add a cycle to the previous model . ucm unrate, cycle(1)

Add a second cycle and provide starting values for the cycle frequencies . ucm unrate, cycle(1,frequency(2.9)) cycle(2,frequency(0.9))

--------------------------------------------------------------------------- Setup . webuse icsa1

Fit a local-level model to the weekly series of new claims for job-loss insurance in the United States . ucm icsa, model(llevel)


Stored results

Because ucm is estimated using sspace, most of the sspace stored results appear after ucm. Not all of these results are relevant for ucm; programmers wishing to treat ucm results as sspace results should see Stored results of [TS] sspace. See Methods and formulas of [TS] ucm for the state-space representation of UCMs, and see [TS] sspace for more documentation that relates to all the stored results.

ucm stores the following in e():

Scalars e(N) number of observations e(k) number of parameters e(k_aux) number of auxiliary parameters e(k_eq) number of equations in e(b) e(k_dv) number of dependent variables e(k_cycles) number of stochastic cycles e(df_m) model degrees of freedom e(ll) log likelihood e(chi2) chi-squared e(p) p-value for model test e(tmin) minimum time in sample e(tmax) maximum time in sample e(stationary) 1 if the estimated parameters indicate a stationary model, 0 otherwise e(rank) rank of VCE e(ic) number of iterations e(rc) return code e(converged) 1 if converged, 0 otherwise

Macros e(cmd) ucm e(cmdline) command as typed e(depvar) unoperated names of dependent variables in observation equations e(covariates) list of covariates e(tvar) variable denoting time within groups e(eqnames) names of equations e(model) type of model e(title) title in estimation output e(tmins) formatted minimum time e(tmaxs) formatted maximum time e(chi2type) Wald; type of model chi-squared test e(vce) vcetype specified in vce() e(vcetype) title used to label Std. Err. e(opt) type of optimization e(initial_values) type of initial values e(technique) maximization technique e(tech_steps) iterations taken in maximization technique e(properties) b V e(estat_cmd) program used to implement estat e(predict) program used to implement predict e(marginsnotok) predictions disallowed by margins e(asbalanced) factor variables fvset as asbalanced e(asobserved) factor variables fvset as asobserved

Matrices e(b) parameter vector e(Cns) constraints matrix e(ilog) iteration log (up to 20 iterations) e(gradient) gradient vector e(V) variance-covariance matrix of the estimators e(V_modelbased) model-based variance

Functions e(sample) marks estimation sample


Harvey, A. C. 1989. Forecasting, Structural Time Series Models and the Kalman Filter. Cambridge: Cambridge University Press.

© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index