ssfortran.MappedModel#

class ssfortran.MappedModel(endog, k_states=None, k_params=None, k_posdef=None, param_names=None, start_params=None)#

A model declared by the matrix entries each parameter sets.

The declaration is held by the library, so no Python runs during estimation and fit_many() can fit the model in parallel.

Parameters:

endogarray_like, shape (n,) or (n, p), or Representation: Observations, time first; NaN marks missing values. A Representation is copied instead, with its matrices and initialization; pass k_params and the rest by keyword.
k_statesint: Number of states m; not used with a Representation.
k_paramsint: Number of parameters.
k_posdefint, optional: Number of state disturbances r; default k_states.
param_nameslist of str, optional: Parameter names; default param1, param2, …
start_paramsarray_like, optional: Constrained starting values; default 0.1 each.

See also

StructuralModel: Models assembled from built-in components.
MLEModel: Models whose matrices are set by Python code.

Notes

Set the fixed matrices with mod[name] = value and the initialization with the initialize_* methods, as on a Representation; then declare the map with map() (single entries), cov() (covariance blocks) and constrain() (transforms). Parameters in no transform group are unconstrained. Mapped entries are overwritten at every evaluation. A map to a single period of a time-varying matrix needs that matrix set first.

Examples

The local level model:

>>> y = np.cumsum(np.random.default_rng(3).standard_normal(100))
>>> mod = ss.MappedModel(y, k_states=1, k_params=2,
...                      param_names=["sigma2.irregular", "sigma2.level"],
...                      start_params=[0.5, 0.5])
>>> mod["design"] = mod["transition"] = mod["selection"] = [[1.0]]
>>> mod.initialize_diffuse()
>>> _ = mod.map(0, "obs_cov", 0, 0).map(1, "state_cov", 0, 0)
>>> _ = mod.constrain([0, 1], "positive")
>>> res = mod.fit()
>>> res.converged
True

__getitem__(name)#: Copy of a system matrix of the model’s representation.

__setitem__(name, value)#: Set a system matrix of the model’s representation.

components(params, variance=False)#

Compute the smoothed contribution of each component to the data.

For a component with states \(b\), the contribution is \(Z_{t,b} \hat\alpha_{t,b}\); for the irregular it is \(\hat\varepsilon_t\). The contributions add up to the observations.

Parameters:

paramsarray_like, shape (k,): Constrained parameters.
variancebool, optional: Also return the variances of the contributions.

Returns:

componentsdict: {name: ndarray}, shape (n,) or (n, p). Names are the component kinds ("level", "seasonal", …), numbered when repeated.
variancesdict: The same for the variances; only with variance=True.

Raises:

TypeError: If the model is not a StructuralModel.

property concentrate_scale#

Whether a scale is concentrated out of the likelihood.

When true, H, Q and \(P_*\) set by the parameters are relative to a scale \(\sigma^2\), which is estimated in closed form (DK §2.10.2) and is not a parameter.

constrain(params, kind, bounds=(0.0, 0.0))#

Set the transform of consecutive parameters.

Parameters:

paramsint or sequence of int: Consecutive parameter indices.
kind{“positive”, “interval”, “stationary”, “invertible”}: positive: \(\exp(2x)\), for variances (DK §7.3.2). interval: \(m + h x / \sqrt{1 + x^2}\) within bounds. stationary: AR coefficients of a stationary polynomial (Monahan 1984). invertible: MA coefficients of an invertible polynomial.
boundstuple of float, optional: (lower, upper) for interval.

Returns:

MappedModel: This model, to chain calls.

Raises:

ValueError: If the parameters are not consecutive.

cov(first_param, matrix, offset, dim)#

Let parameters set a covariance block.

Parameters first_param, ..., first_param + dim (dim + 1) / 2 - 1 are the lower triangle, by columns, of the block. They are estimated through a Cholesky factor with log diagonal, which keeps the block positive definite.

Parameters:

first_paramint: First parameter index.
matrix{“obs_cov”, “state_cov”}: The matrix.
offsetint: First row and column of the block (0-based).
dimint: Size of the block.

Returns:

MappedModel: This model, to chain calls.

filter(params)#

Run the Kalman filter at given parameters.

Parameters:

paramsarray_like, shape (k,): Constrained parameters.

Returns:

FilterResults: The filter output.

fit(start_params=None, maxiter=500, m=10, factr=10000000.0, pgtol=1e-05, compute_cov=True, gradient='auto')#

Estimate the parameters by maximum likelihood (DK §7.3).

L-BFGS-B minimizes -loglike / n over the unconstrained parameters. The defaults are those of statsmodels.

Parameters:

start_paramsarray_like, optional: Constrained starting values; default start_params.
maxiterint, optional: Maximum number of iterations.
mint, optional: Number of L-BFGS corrections.
factrfloat, optional: Stop when the relative reduction of the objective is below factr times the machine epsilon; 10 gives a tight optimum.
pgtolfloat, optional: Stop when the projected gradient is below pgtol.
compute_covbool, optional: Compute cov_params and bse from a numerical Hessian.
gradient{“auto”, “analytic”, “numerical”}, optional: "auto" uses the analytic score where it applies (DK §7.3.3) and central differences elsewhere.

Returns:

FitResults: Estimates and fit statistics.

Raises:

StateSpaceError: If the likelihood cannot be evaluated at the start.

Notes

The score covers parameters in H, R, Q and \(P_*\) through the smoothed disturbances (DK eq. 7.14, 7.16). Parameters that move Z or T get central differences, as DK recommend. Standard errors come from the Hessian in the unconstrained parameters and the delta method.

Examples

A local level with variances 1 (irregular) and 0.25 (level):

>>> rng = np.random.default_rng(2)
>>> y = np.cumsum(0.5 * rng.standard_normal(1000)) + rng.standard_normal(1000)
>>> res = ss.StructuralModel(y, [ss.Irregular(), ss.Level()]).fit()
>>> res.param_names
['sigma2.irregular', 'sigma2.level']
>>> np.round(res.params, 2)
array([1.04, 0.22])

initialize(a1, Pstar, Pinf)#

Initialize with \(\alpha_1 \sim N(a_1, P_* + \kappa P_\infty)\).

The general form of DK §5.1, with \(\kappa \to \infty\) handled exactly.

Parameters:

a1array_like, shape (m,): Mean.
Pstararray_like, shape (m, m): Variance of the proper part.
Pinfarray_like, shape (m, m): Variance direction of the diffuse part; usually a selection \(A A'\).

initialize_approximate_diffuse(variance=1000000.0)#

Initialize with mean zero and a large variance, variance * I.

Parameters:

variancefloat, optional: Variance of each state; default 1e6, as in statsmodels.

See also

initialize_diffuse: The exact treatment (DK §5.2).

initialize_block(start, stop, kind, a1=None, P1=None, variance=1000000.0)#

Initialize a block of states, leaving the others as they are.

Blocks combine, for example a diffuse trend with a stationary ARMA block (DK §5.6).

Parameters:

start, stopint: The block is states start:stop (0-based, like a slice).
kindint: INIT_KNOWN, INIT_APPROX_DIFFUSE, INIT_STATIONARY or INIT_DIFFUSE.
a1, P1array_like, optional: Mean (stop - start,) and variance for INIT_KNOWN.
variancefloat, optional: Variance for INIT_APPROX_DIFFUSE.

Notes

A stationary block must not depend on states outside it through T.

Examples

A diffuse level with a stationary AR(1) disturbance:

>>> rep = ss.Representation(np.zeros(20), k_states=2)
>>> rep["transition"] = [[1.0, 0.0], [0.0, 0.5]]
>>> rep.initialize_block(0, 1, ss.INIT_DIFFUSE)
>>> rep.initialize_block(1, 2, ss.INIT_STATIONARY)

initialize_diffuse()#

Initialize every state as exact diffuse (DK §5.2).

The initial variance is \(\kappa I\) with \(\kappa \to \infty\), handled exactly by the exact initial Kalman filter; the log likelihood is then the diffuse log likelihood (DK §7.2.2).

See also

initialize_approximate_diffuse: A large finite variance instead.

initialize_known(a1, P1)#

Initialize with a known mean and variance.

Parameters:

a1array_like, shape (m,): Mean of the initial state.
P1array_like, shape (m, m): Variance of the initial state.

See also

initialize_diffuse: Exact diffuse initialization.
initialize_stationary: The unconditional distribution.
initialize_block: Different initializations for blocks of states.

initialize_stationary()#

Initialize with the unconditional distribution of the state.

The mean is \((I - T)^{-1} c\) and the variance solves \(P = T P T' + R Q R'\) (DK §5.6.2), recomputed from the current matrices at every filter run. The model must be time-invariant in T, R, Q and c at the first period.

Raises:

StateSpaceError: From the filter, with code 6, if T has an eigenvalue on or outside the unit circle.

loglike(params)#

Evaluate the log likelihood.

Parameters:

paramsarray_like, shape (k,): Constrained parameters.

Returns:

float: Log likelihood, concentrated when concentrate_scale is set; the scale is then in scale.

map(param, matrix, i, j=0, t=None, coef=1.0)#

Let a parameter set a matrix entry.

matrix[i, j, t] = coef * params[param], all indices 0-based.

Parameters:

paramint: Parameter index.
matrixstr: design, obs_cov, transition, selection, state_cov, state_intercept or obs_intercept.
i, jint: Row and column; j is ignored for the intercepts.
tint, optional: Period; None sets every period of a time-varying matrix.
coeffloat, optional: Multiplier.

Returns:

MappedModel: This model, to chain calls.

property param_names#: Parameter names, e.g. "sigma2.level".

representation(params)#

Build the representation at given parameters.

Parameters:

paramsarray_like, shape (k,): Constrained parameters.

Returns:

Representation: A copy, on the data’s scale when the scale is concentrated out.

property scale#: Concentrated scale at the last likelihood evaluation.

smooth(params)#

Run the filter and smoother at given parameters.

Parameters:

paramsarray_like, shape (k,): Constrained parameters.

Returns:

SmootherResults: Smoothed states and disturbances.

property ssm#

The model’s own representation.

Changes to it, such as filter_method or tol_steady, apply to later likelihood evaluations. Its system matrices reflect the last parameters evaluated. MappedModel and MLEModel set its matrices and initialization through mod[name] = value and their initialize_* methods.

property start_params#: Starting values for estimation, constrained.

transform_params(unconstrained)#

Map unconstrained values to parameters.

Parameters:

unconstrainedarray_like, shape (k,): Values on the optimizer’s scale.

Returns:

ndarray, shape (k,): Constrained parameters, e.g. variances \(\exp(2x)\) (DK §7.3.2).

untransform_params(constrained)#

Map parameters to the optimizer’s unconstrained scale.

Parameters:

constrainedarray_like, shape (k,): Parameters.

Returns:

ndarray, shape (k,): The inverse of transform_params().