Skip to content

Simultaneous models

Categorical list of functions

Creating new Simultaneous models

Function Description
from_portable Create Simultaneous model from portable dictionary
from_portable_file Read a Simultaneous object from a portable JSON file
Simultaneous.from_file Create Simultaneous model object from source file or files
Simultaneous.from_string Create Simultaneous model from string

Getting information about Simultaneous models

Function Description

Applying structural filters on Simultaneous models

Function Description
kalman_filter Run Kalman filter on a model using time series data
neg_log_likelihood

Manipulating Simultaneous model parameters

Function Description
rescale_stds Rescale the standard deviations of model shocks

Serializing, saving and loading Simultaneous models

Function Description
to_portable Serialize Simultaneous model to portable dictionary
to_portable_file Write a Simultaneous object to a portable JSON file

Directly accessible properties

Property Description
is_deterministic True for models declared as deterministic
is_flat True for models declared as flat
is_linear True for models declared as linear
max_lag Maximul lag in the model (negative or zero)
max_lead Maximul lead in the model (positive or zero)
num_measurement_equations Number of measurement equations
num_transition_equations Number of transition equations

☐ from_portable

Create Simultaneous model from portable dictionary

Create a Simultaneous model object from a portable dictionary. See Simultaneous.to_portable for details on the structure of the portable dictionary.

self = Simultaneous.from_portable(portable)

Input arguments

portable

A dictionary with the structure described in the documentation of Simultaneous.to_portable.

Returns

self

A new Simultaneous model object created from the portable dictionary.

☐ from_portable_file

Read a Simultaneous object from a portable JSON file

Read a JSON file and convert the contents to a Simultaneous object. See Simultaneous.from_portable for details on the conversion from a portable dictionary.

self = Simultaneous.from_portable_file(
    file_name,
    json_settings=None,
)

Input arguments

file_name

Filename from which to read the JSON file.

json_settings

Optional settings to pass to json.load.

Returns

self

A new Simultaneous object created from the contents of the JSON file.

☐ Simultaneous.from_file

Create Simultaneous model object from source file or files

Read and parse one or more source files specified by file_names (a string or a list of strings) with model source code, and create a Simultaneous model object.

self = Simultaneous.from_file(
    file_names,
    /,
    context=None,
    description="",
)

Input arguments

file_names

The name of the model source file from which the Simultaneous model object will be created, or a list of file names; if multiple file names are specified, they will all combined together in the given order.

context

Dictionary supplying the values used in preparsing commands, and the definition of non-standard functions used in the equations.

description

Desscription of the model specified as a text string.

Returns

self

Simultaneous model object created from the file_names.

☐ Simultaneous.from_string

Create Simultaneous model from string

Read and parse a text string with a model source code, and create a Simultaneous model object. Otherwise, this function behaves the same way as Simultaneous.from_file.

self = Simultaneous.from_string(
    string,
    /,
    context=None,
    description="",
)

Input arguments

string

Text string from which the Simultaneous model object will be created.

See Simultaneous.from_file for other input arguments.

Returns

See Simultaneous.from_file for return values.

☐ kalman_filter

Run Kalman filter on a model using time series data

Executes a Kalman filter on a model, compliant with KalmanFilterableProtocol, using time series observations from the input Databox. This method enables state estimation and uncertainty quantification in line with the model's dynamics and the time series data.

kalman_output = self.kalman_filter(
    input_db,
    span,
    diffuse_scale=None,
    return_=("predict", "update", "smooth", "predict_err", "predict_mse_obs", ),
    return_predict=True,
    return_update=True,
    return_smooth=True,
    return_predict_err=True,
    return_predict_mse_obs=True,
    rescale_variance=False,
    likelihood_contributions=True,
    shocks_from_data=False,
    stds_from_data=False,
    prepend_initial=False,
    append_terminal=False,
    deviation=False,
    check_singularity=False,
    unpack_singleton=True,
    return_info=False,
)

kalman_output, info = self.kalman_filter(
    ...
    return_info=True,
)

Input arguments

self

The model, compliant with KalmanFilterableProtocol, performing the Kalman filtering.

input_db

A Databox containing time series data to be used for filtering.

span

A date span over which the filtering process is executed based on the measurement time series.

diffuse_scale

A real number or None, specifying the scale factor for the diffuse initialization. If None, the default value is used.

return_

An iterable of strings indicating which steps' results to return: "predict", "update", "smooth".

return_predict

If True, return prediction step results.

return_update

If True, return update step results.

return_smooth

If True, return smoothing step results.

rescale_variance

If True, rescale all variances by the optimal variance scale factor estimated using maximum likelihood after the filtering process.

likelihood_contributions

If True, return the contributions of individual periods to the overall (negative) log likelihood.

shocks_from_data

If True, use possibly time-varying shock values from the data; these values are interpreted as the medians (means) of the shocks. If False, zeros are used for all shocks.

stds_from_data

If True, use possibly time-varying standard deviation values from the data. If False, currently assigned constant values are used for the standard deviations of all shocks.

prepend_initial

If True, prepend observations to the resulting time series to cover initial conditions based on the model's maximum lag. No measurement observations are used in these initial time periods (even if some are available in the input data).

append_terminal

If True, append observations to the resulting time series to cover terminal conditions based on the model's maximum lead. No measurement observations are used in these terminal time periods (even if some are available in the input data).

deviation

If True, the constant vectors in transition and measurement equations are set to zeros, effectively running the Kalman filter as deviations from steady state (a balanced-growth path)

check_singularity

If True, check the one-step ahead MSE matrix for the measurement variables for singularity, and throw a SingularMatrixError exception if the matrix is singular.

unpack_singleton

If True, unpack out_info into a plain dictionary for models with a single variant.

return_info

If True, return additional information about the Kalman filtering process.

Returns

kalman_output

A Databox containing some of the following items (depending on the user requests):

| Attribute | Type | Description |-------------------|--------------------------------------------------- | predict_med | Databox | Medians from the prediction step | predict_std | Databox | Standard deviations from the prediction step | predict_mse_obs | list | Mean squared error matrices for the prediction step of the available observations of measurement variables | update_med | Databox | Medians from the update step | update_std | Databox | Standard deviations from the update step | predict_err | Databox | Prediction errors | smooth_med | Databox | Medians from the smoothing step | smooth_std | Databox | Standard deviations from the smoothing step

out_info

A dictionary containing additional information about the filtering process, such as log likelihood and variance scale. For models with multiple variants, out_info is a list of such dictionaries. If unpack_singleton=False, also out_info is a one-element list containing the dictionary for singleton models, too.

☐ neg_log_likelihood

☐ rescale_stds

Rescale the standard deviations of model shocks

Adjust the standard deviations of the model shocks by a specified factor. This method allows scaling the standard deviations for the shocks in the model based on the provided factor.

self.rescale_stds(
    factor,
    kind=None,
)

Input arguments

factor

A real non-negative number by which to scale the standard deviations of the model shocks. This value is used to multiply the existing standard deviations.

kind

An optional parameter to narrow down the types of shocks to rescale. It can be one, or a combination, of the following:

  • ir.UNANTICIPATED_STD
  • ir.ANTICIPATED_STD
  • ir.MEASUREMENT_STD

If None, the standard deviations of all shocks will be rescaled.

Returns

None

This method does not return any value but modifies the standard deviations of model shocks in-place, rescaling them.

☐ to_portable

Serialize Simultaneous model to portable dictionary

Convert a Simultaneous model object to a dictionary of primitive values that can be saved to a JSON file or transmitted over the network. The structure of the portable dictionary is described below.

portable = self.to_portable()

Input arguments

self

Simultaneous model object to be serialized.

Returns

portable

A JSON-serializable dictionary with the structure described below.

Details

Structure of the portable dictionary, format 0.3.0:

The portable dictionary has the following structure:

    {
        "portable_format": "0.3.0",
        "source": {
            "description": <str>,
            "flags": {
                "is_linear: <bool>,
                "is_flat": <bool>,
                "is_deterministic": <bool>
            },
            "quantities": [ <QUANTITY>, ... ],
            "equations": [ <EQUATION>, ... ],
            "context": {},
        "variants": [ <VARIANT>, ... ],
    }

The meaning of the flags is as follows:

  • is_linear is True if the model has been created with the linear=True, and the calculation of first-order solution matrices is expected to be independent of the model steady state. * is_flat is True

  • is_flat is True if the model has been created with the flat=True, and the calculation of the model steady state is done assuming that no model variable is growing over time in steady state.

  • is_deterministic is True if the model has been created with the deterministic=True, and the model is expected to have no stochastic shocks; all shocks are assumed to be deterministic add-factors, and there are no std parameter created.

The quantities is a list of quantities, with each <QUANTITY> described as a five-element tuple:

[ <KIND>, <NAME>, <LOGLY>, <DESCRIPTION>, <ATTRIBUTES> ]

where

  • <KIND> is a string representing the kind of the quantity,

  • <NAME> is a string with the name of the quantity,

  • <LOGLY> is a boolean or None indicating whether the quantity is declared as a log variable None if irrelevant for the respective kind of variables),

  • <DESCRIPTION> is a string with the description of the quantity,

  • <ATTRIBUTES> is a string containing all attributes separated by a white space.

The kinds of variables are coded as follows:

Kind of variable Code
Transition variable #x
Measurement variable #y
Unanticipated shock #u
Anticipated shock #v
Measurement shock #w
Parameter #p
Exogenous variable #z

The equations is a list of equations, with each <EQUATION> described as a five-tuple:

[ <KIND>, <DYNAMIC>, <STEADY>, <DESCRIPTION>, <ATTRIBUTES> ]

where * <KIND> is a string representing the kind of the equation,

  • <DYNAMIC> is a string with the dynamic variant of the equation,

  • <STEADY> is a string with the steady-state variant of the equation,

  • <DESCRIPTION> is a string with the description of the equation,

  • <ATTRIBUTES> is a string containing all attributes separated by a white space.

The kinds of equations are coded as follows:

Kind of equation Code
Transition equation #T
Measurement equation #M
Steady autovalues #A

The variants is a list of parameter (and steady-state) variants, with each <VARIANT> being a dictionary with its keys corresponding to the names of the model quantities (including std_ names for the standard deviations of shocks), and the values being two-tuples consisting of the level and the changes of the respective quantity; the change is None whenever irrelevant for the respective kind of quantity.

☐ to_portable_file

Write a Simultaneous object to a portable JSON file

Convert the Simultaneous object to a portable dictionary and write it to a JSON file. See Simultaneous.to_portable for details on the conversion to a portable dictionary.

self.to_portable_file(
    file_name,
    json_settings=None,
)

Input arguments

file_name

Filename under which to save the JSON file.

json_settings

Optional settings to pass to json.dump.

Returns

The method returns None.