cultivars.typing#
Public type aliases for the categorical options a specification takes.
A model specification in this package is a handful of numbers and a
handful of words: an order, a penalty weight, and then trend="ct",
vol="GJR", frequency="flow". The numbers are validated by
shape; the words are validated against a closed list, and this package
is where those lists live as types. Each name is a PEP 695 type
alias over a Literal, so a static checker rejects a
misspelled option at the call site of any parameter annotated with it,
and the alias is also what the package’s own runtime check reads:
validate_choice(value, Trend, "trend") unwraps the alias to its
permitted values and raises SpecificationError
on anything else, so the type and the check cannot drift apart. The
one exception is OptimizerOptions, an alias of the
scipy-stubs TypedDict for scipy.optimize.minimize()’s
options, present so that a mistyped optimizer key is a type error and
not a silently ignored dictionary entry; at runtime it is dict.
The package has one rule that every alias keeps: a name here is a
specification choice with statistical content, never a display option.
CointegrationTrend selects one of Johansen’s five deterministic
cases and with it the asymptotic distribution of the rank statistics;
Frequency decides whether a low-frequency reading pins one
latent value (a stock) or a weighted sum (a flow); PanelEffects
decides whether the estimator carries the Nickell bias. Where a family
is a different specification surface rather than another value – the
fractionally integrated GARCH beside Vol, unit-varying slopes
beside PanelEffects – it is deliberately not a value, and the
alias’s docstring says so.
Each name is imported from this package: from cultivars.typing import
Trend. Nothing here is a class to instantiate or a function to call;
the aliases are annotations and validator arguments, and their
docstrings are the reference for what each option means. They are
re-exported from _core._types, where the private aliases the
internals use beside them also live.
Layout, by the surface each alias governs. Univariate conditional mean:
Trend ("n", "c", "ct"), Method ("css",
"exact"), Transition (LSTAR or ESTAR), Activation
(neural mean functions), LongMemoryMethod ("gph",
"local_whittle"). Conditional variance: Mean and
Vol. Multivariate: CointegrationTrend (Johansen’s
cases), PanelEffects, Penalty (sparse-VAR families),
Frequency (mixed-frequency observation types),
FunctionalBasis (curve bases). Switching and observed-regime
models: ProbabilityType ("smoothed", "filtered",
"predicted") and Regime ("lower", "upper").
Optimization: OptimizerMethod and OptimizerOptions.
Example
An alias annotates a variable, enumerates its own values, and validates at runtime through the same object:
>>> from typing import get_args
>>> from cultivars.engine._core._validators import _validate_choice
>>> trend: Trend = "ct"
>>> get_args(Trend.__value__)
('n', 'c', 'ct')
>>> _validate_choice(trend, Trend, "trend")
'ct'
>>> _validate_choice("quadratic", Trend, "trend")
Traceback (most recent call last):
...
cultivars.exceptions.SpecificationError: trend must be one of ('n', 'c', 'ct'); got 'quadratic'.
>>> get_args(CointegrationTrend.__value__)
('none', 'restricted_constant', 'constant', 'restricted_trend', 'trend')
Classes#
An identification scheme: reduced-form innovations in, a structural view out. |
|