cultivars.data#
Data access: the clients that bring series into the package, re-exported.
A reduced form is only as good as the series behind it, and the series
of applied macroeconometrics come from a small number of public
providers whose APIs are worth a client of their own. This package
re-exports those clients under names that say what kind of data they
carry rather than which service serves them, so that a workflow reads
from cultivars.data import economic and the choice of provider is
an implementation detail that can change without the import changing.
Nothing here is estimated or transformed. The clients return dataframes of observations with their own date index and vintage handling, and the models in the rest of the package take arrays, so a fetched frame is reduced to the columns and sample the question needs before it is passed to a model. The examples do exactly that for every model family, through a shared helper that fetches, aligns and labels a dictionary of series in one call.
The providers need credentials. The economic client reads its API key
from the FRED_API_KEY environment variable or from
set_api_key(), and raises a clear error when neither is
set; a free key is issued at
https://fred.stlouisfed.org/docs/api/api_key.html. No module in the
package touches the network unless a client is called, so importing
cultivars.data is safe offline.
Layout. economic is fedfred, a client for the Federal
Reserve Bank of St. Louis FRED and ALFRED databases: series, releases,
sources, categories, tags, vintage dates and the GeoFRED maps, in
synchronous (FredAPI) and asynchronous
(AsyncAPI) forms, with pandas, polars and dask
output. A financial client for SEC EDGAR filings is planned under the
same package. Both are independent projects with their own
documentation, versioning and release cycle; this package pins a
version and re-exports it, and their APIs are documented at their own
sites rather than here.
Example
Fetch two FRED series as a frame, keep the common sample, and hand the array to a VAR. Needs a key and a network connection, so the example is not run as a test:
>>> from cultivars.data import economic
>>> from cultivars.multivariate.reduced_form.vector_autoregression import VAR
>>> api = economic.FredAPI()
>>> frames = [
... api.get_series_observations(code, observation_start="1990-01-01", units=unit)
... for code, unit in (("INDPRO", "pch"), ("FEDFUNDS", "lin"))
... ]
>>> data = frames[0].join(frames[1], lsuffix="_ip", rsuffix="_ffr").dropna()
>>> res = VAR(data.to_numpy(), order=4, names=("ip", "ffr")).fit()
>>> res.names
('ip', 'ffr')
Modules#
This module initializes the fedfred package. |