Shock

class Shock(
    T: int,
    dist: Literal['norm', 't', 'uni'] | rv_generic | multi_rv_generic | None = None,
    multivar: bool = False,
    seed: int | None = 0, # (1)!
    dist_args: tuple = (),
    dist_kwargs: dict | None = None,
    shock_arr: ndarray | None = None,
    )

Notice the default behavior will produce seeded results. Pass None explicitly to disable this behavior.

Shock provides the infrastructure necessary to produce simulation shocks. All distributions that are subclasses of SciPy's rv_generic and multi_rv_generic are supported by the interface. Moreover, Normal, Student-t, and Uniform shocks are supported natively inside the class object.

Multivariate Uniform Distribution Support

Multivariate uniforms are not identifiable even with known bounds and covariances. A specific support function must be supplied to determine an exact shape; with the exceptions of rectangular (no covariance) and ellipsoid (assumed shape) cases.

Support functions, and derivation techniques for multivariate uniform distributions will not be implemented unless explicitly requested.

Custom Distributions

The underlying generators are written to accept any class implementing a .rvs method (abstract method from SciPy). Writing a subclass of either SciPy abstraction and implementing said method allows the creation of random values in any desired way.

Generator Factories

Generator factories being utilized in this class are currently not part of the public API of SymbolicDSGE. Robust and defensive alternatives of generators will be written specifically for the public API in future releases.

Attributes:

Name	Description
T	Period length to generate shocks for.
dist	Distribution to use when drawing random values.
multivar	Generate shocks for multiple correlated components if `True`.
seed	Random state seed.
dist_args	Positional arguments passed-through to the distribution's `.rvs` method.
dist_kwargs	Keyword arguments passed-through to the distribution's `.rvs` method.
shock_arr	Array of shock values to configure.

Methods:

Shock.shock_generator() -> Callable[[...], ndarray]

Creates a callable that returns an entire shock array according to the class attributes when called.

Inputs:

None

Returns:

Single Return

Only one Callable specification from the table below is returned.

Type(s)	Description
`Callable[[float], ndarray[float]]`	Callable taking a single shock standard deviation (sigma) parameter. (This signature is returned for univariate shocks)
`Callable[[ndarray[float]], ndarray[float]]`	Callable taking a shock covariance matrix. (This signature is returned for multivariate shocks.)

@overload
Shock.place_shocks(
    shock_spec: dict[int, float],
) -> np.ndarray[float]

@overload
Shock.place_shocks(
    shock_spec: dict[tuple[int, int], float]
) -> np.ndarray[float]

Modifies the specified indices of a given shock array to the corresponding values. (Returns a modified zero vector if shock_arr isn't specified in the class instance)

place_shocks supports univariate and multivariate array manipulations via overloading.

Array Shape Inference

In univariate cases, the array shape can be inferred accurately using Shock.T.

In multivariate cases, the number of columns cannot be inferred uniquely from T alone. If shock_arr is not provided, SymbolicDSGE infers K from shock_spec as K = max_col_idx + 1 where max_col_idx = max(col_idx for (t, col_idx) in shock_spec).

Index Bound Enforcement

Out-of-bounds or negative indices raise IndexError.

Overloaded shock_spec Scheme:

Mode	Type	Description
Univariate	`dict[int, float]`	Keys indicate the time index to place the values at.
Multivariate	`dict[tuple[int, int], float]`	Keys contain a two-dimensional indexer `(time_idx, arr_idx)` to access the 2D array using the conventional `(row, col)` specification. Values are placed in the element described by the indexer.

Inputs:

Name	Description
shock_spec	`dict` indicating the position and value required for a modification of `shock_arr`.

Returns:

Type	Description
`np.ndarray[float]`	Array with specified indices modified as per the specification.

Examples:

# Univariate
Shock(T=10).place_shocks(
    {
        0: 1.0,
        3: -0.5 # (1)!
    }
)  # (2)!

# Multivariate (K inferred as 2)
Shock(T=10, multivar=True).place_shocks(
    {
        (0,0): 1.0,
        (0,1): 2.0, # (3)!
    }
)  # (4)!

Sets output[0] = 1.0 and output[3] = -0.5.
Returns shape (10,)
Sets output[0, 0] = 1.0 and output[0, 1] = 2.0.
Returns shape (10, 2)