Frbus Object API

frbus.Frbus(filepath[, mce])
frbus.Frbus.__init__(filepath[, mce])	Initialize FRB/US model object.
frbus.Frbus.append_replace(eqs_map)	Append new equations to the model, or replace existing equations.
frbus.Frbus.exogenize(exoglist)	Exogenize a list of endogenous variables in the model.
frbus.Frbus.init_trac(start, end, input_data)	Initialize tracking residuals (add-factors).
frbus.Frbus.mcontrol(start, end, input_data, ...)	Solve model, forcing target variables to specified trajectories.
frbus.Frbus.solve(start, end, input_data[, ...])	Solve the model over the given dataset.
frbus.Frbus.stochsim(nrepl, input_data, ...)	Runs a series of simulations with shocks drawn from historical residuals.

class pyfrbus.frbus.Frbus(filepath, mce=None)

__init__(filepath, mce=None)

Initialize FRB/US model object.

Parameters:

• filepath (str) – Path to FRB/US model file in .xml format

• mce (Optional[Union[str, List[str]]) – Option to load MCE equations. Valid MCE types are all, mcap, wp, and mcap+wp, or a list of model variables to be read in as MCE.

Returns:

FRB/US model object

Return type:

Frbus

append_replace(eqs_map)

Append new equations to the model, or replace existing equations.

Parameters:

eqs_map (Dict[str, str]) – Dictionary mapping equation names to equations

exogenize(exoglist)

Exogenize a list of endogenous variables in the model.

This function takes a list of endogenous variables present in the model and transforms them into exogenous variables. Note: all variables that you want to be exogenous must be passed in as exoglist at the same time. Calling exogenize twice in a row will give a model with only the second exoglist variables exogenized.

Parameters:

exoglist (List[str]) – List of endogenous model variables

init_trac(start, end, input_data)

Initialize tracking residuals (add-factors).

Given a baseline dataset input_data and a date range start to end, init_trac will compute tracking residuals such that each equation will solve to the trajectory given for that variable in input_data. As in, output = model.init_trac(start, end, input_data), then model.solve(start, end, output) will be the same as output.

Tracking residuals are stored in additional columns in output, named according to their respective endogenous variables, e.g. the tracking residual for xgdp is stored as xgdp_trac.

Parameters:

• start (Union[str, Period]) – Date to begin computing residuals

• end (Union[str, Period]) – Date to end residuals (inclusive)

• input_data (DataFrame) – Dataset with trajectories that residuals are computed with respect to

Returns:

output – input_data plus columns for tracking residuals

Return type:

DataFrame

mcontrol(start, end, input_data, targ, traj, inst, options=None)

Solve model, forcing target variables to specified trajectories.

mcontrol is a trajectory-matching control procedure which adjusts the value of instrument variables such that target variables are forced to specified trajectories, as mediated by the model’s dynamics.

targ is a list of model variables (“targets”), and traj is the list of series in input_data that those variables should be forced to (“trajectories”), in the same order; e.g. the first variable in targ is matched to the first trajectory in traj, etc.

inst is a list of exogenous model variables (“instruments”) which will take on values such that the trajectories are achieved. The selected instruments may be unable to achieve the specified trajectories - e.g. because there is no instrument which is able to affect one or more of the specified targets, or because one or more of the specified trajectories contains an invalid value for that target variable. In that case, the model will fail to solve and an error will instruct you to verify that your setup for mcontrol is valid.

Targets are only forced to their trajectories when a trajectory is present. A particular target can be disabled by setting the corresponding trajectory to numpy.nan over the date range where it should be inactive. When the trajectory is set to numpy.nan, the corresponding target is allowed to take on the value produced by the model.

Parameters:

• start (Union[str, Period]) – Date to begin computing solution

• end (Union[str, Period]) – Date to end solution (inclusive)

• input_data (DataFrame) – Dataset to solve over, including series for trajectories specified in traj

• targ (List[str]) – List of endogenous model variables to force (in order)

• traj (List[str]) – List of trajectories in input_data to force targ variables to (in order)

• inst (List[str]) – Instruments used to control forcing procedure

• options (Optional[Dict]) – Options passed to solver - see additional documentation under Frbus.solve. Some options will be overridden if they are unable to be used with mcontrol procedure; mcontrol requires the use of either Newton or trust-region solvers (defaults to "newton") and requires single_block set to True.

Returns:

output – Dataset shaped like input_data, with a solution consistent with the specified forced trajectories between start and end, inclusive. Data from output outside this period is identical to input_data.

Return type:

DataFrame

solve(start, end, input_data, options=None)

Solve the model over the given dataset.

Given the DataFrame input_data, this procedure returns the model solution over the period from start to end. Detailed information on the solution algorithm can be found in the User Guide.

Frbus.solve will solve both backwards-looking VAR and forwards-looking MCE (model-consistent expectations/rational expectations) models. The options dictionary can be passed to configure the solution algorithm, as specified below.

Parameters:

• start (Union[str, Period]) – Date to begin computing solution

• end (Union[str, Period]) – Date to end solution (inclusive)

• input_data (DataFrame) – Dataset to solve over

• options (Optional[Dict]) –

  Options to pass to solver:

  newton: Optional[str]

  Whether to use sparse Newton’s method solver ("newton"), sparse trust-region solver ("trust"), or dense solver from SciPy (None). Defaults to None.

  single_block: bool

  When set to True, disables the VAR block decomposition step. Defaults to False.

  debug: bool

  When set to True, enables verbose output of solver status. Defaults to False.

  xtol: float

  Set stepsize termination condition for Newton and trust-region algorithms. Use a smaller value for more precise solution, at the expense of runtime. Defaults to 1e-4.

  rtol: float

  Set residual termination condition for Newton and trust-region algorithms. Solver will fail if step reaches xtol but residual is greater than rtol. Defaults to 5e-4.

  maxiter: int

  Maximum number of iterations for Newton and trust-region algorithms. Solver will fail if algorithm iterates maxiter times without reaching xtol. Increase to allow more time for convergence. Defaults to 50.

  trust_radius: float

  Maximum size of the trust radius in trust-region algorithm. Altering radius can change convergence path. Defaults to 1000000.

  precond: bool

  When set to True, use matrix preconditioner to decrease condition number of Jacobian. Disable if it causes problems. Defaults to True.

  check_jac: bool

  When set to True, check Jacobian (in addition to objective function) for boundary violations during damped Newton step. Enable if an invalid Jacobian is encountered. Defaults to False.

  force_recompute: bool

  When set to True, disable Jacobian re-use during Newton solver, forcing Jacobian to be re-computed at every step. Defaults to False.

  try_umfpack: bool

  When set to True, use scikit_umfpack with either the Newton or trust-region solver, if scikit_umfpack is also installed. Set to False if scikit_umfpack is installed and causing issues. Defaults to True.

Returns:

output – Dataset shaped like input_data, with trajectories for endogenous variables produced by model solution between start and end, inclusive. Data in output from outside this period is identical to input_data.

Return type:

DataFrame

stochsim(nrepl, input_data, simstart, simend, residstart, residend, multiproc=True, nextra=0, seed=1000, trim_output=True, options=None)

Runs a series of simulations with shocks drawn from historical residuals.

The stochsim procedure performs a stochastic simulation by applying sequences of shocks to the model, as drawn randomly from historical residuals. Before using this procedure, the DataFrame input_data must have residuals computed over both history and the simulation period with Frbus.init_trac'.

The procedure begins by drawing nrepl sequences of quarters from the dataset input_data over the periods residstart to residend, where the length of that sequence goes from simstart to simend. That is, for a particular replication, each quarter in the simulation period is randomly assigned a quarter from residual period. In that quarter of the simulation, all stochastic variables (specified with a stochastic_type tag in the model) have a shock applied from a particular quarter in the residual period, where the shock values are pulled from the _trac variables in input_data - e.g., the variable xgdp is shocked with a value pulled from xgdp_trac over history.

These scenarios are passed to the solver, in parallel if multiproc is set to True, and the solutions are returned as a list of DataFrames. Any failed simulations will be returned as an error string. The argument nextra can be passed to allow the procedure to run extra simulations to replace those failures.

Parameters:

• nrepl (int) – Number of simulations to run

• input_data (DataFrame) – Dataset to solve over

• simstart (Union[str, Period]) – Date to begin computing solution

• simend (Union[str, Period]) – Date to end solution (inclusive)

• residstart (Union[str, Period]) – Date to begin drawing shocks

• residend (Union[str, Period]) – Date to end drawing shocks (inclusive)

• multiproc (bool) – Option to run simulations in parallel

• nextra (int) – Option to specify how many additional simulations to run, in case of errors

• seed (int) – Random seed used when drawing shocks

• trim_output (bool) – Optionally trim date range of output data to save memory

• options (Optional[Dict]) – Options passed to solver - see additional documentation under Frbus.solve.

Returns:

solutions – List of datasets shaped like input_data, with solutions to stochastic simulations as returned from Frbus.solve. List contains error strings instead of data for simulations that fail.

Return type:

List[Union[DataFrame, str]]