Public Python API#

Back to reference

The importable surface is module-based and pandas-first. The table below mirrors macroforecast.__all__: every symbol listed there should be importable from the top-level package. Module-level helpers that are not top-level convenience exports are documented on their module reference pages.

Top-Level Exports#

Symbol

Source

Description

meta, data, preprocessing, feature_engineering, filters, data_analysis, feature_analysis, feature_diagnostic, forecast_analysis, forecast_diagnostic, models, model_ensemble, model_selection, forecasting, metrics, tests, evaluation, window, interpretation, output, reporting

package namespaces

Top-level module namespaces. feature_diagnostic and forecast_diagnostic are compatibility aliases for the corresponding analysis modules.

configure, get_config, get_option, reset_config, use_config, DEFAULT_RANDOM_SEED, StageDefaultScope, MetadataLevel

macroforecast.meta

Global package defaults and config types.

DataBundle, DataSpec, RegimeDirection, SamePeriodPolicy, as_panel, attach_metadata, custom_dataset, metadata, panel_info, set_frequencies, spec, validate_panel

macroforecast.data

Canonical panel and metadata helpers.

align_frequency, chow_lin_disaggregate, infer_frequencies, frequency_hardening_issues, availability_lag, same_period_predictors, define_regime

macroforecast.data

Frequency alignment/inference, Chow-Lin disaggregation, data availability, same-period predictor, and regime metadata policies.

load_fred_md, load_fred_qd, load_fred_sd, load_fred_md_sd, load_fred_qd_sd

macroforecast.data

Dataset loaders.

load_custom_csv, load_custom_parquet, list_vintages, combine

macroforecast.data

Custom loading, vintage discovery, and panel combination.

reprocess, custom_preprocess, standardize_panel, PreprocessedData

macroforecast.preprocessing

Direct pandas preprocessing.

PreprocessSpec, FittedPreprocessor, preprocess_spec, custom_preprocess_step

macroforecast.preprocessing

Runner-compatible preprocessing fit/transform specs.

FeatureSet, FeatureSpec, FittedFeatureBuilder, build_features, feature_spec

macroforecast.feature_engineering

Aligned forecast matrices, metadata, and runner-compatible feature specs.

direct_target, average_target, forward_average_target, path_targets

macroforecast.feature_engineering

Direct, forward-average, and path target construction.

feature_matrix, compose_features

macroforecast.feature_engineering

Paper-style feature blocks and sequential feature composition.

lag, mixed_frequency_lags, rolling_mean, moving_average_ladder, scale_features, pca_features, sparse_pca_chen_rohe_features, varimax_features, group_pca, maf_features, time_features, custom_features

macroforecast.feature_engineering

Core direct pandas feature transforms.

transform_features, log_features, diff_features, log_diff_features, pct_change_features, cumsum_features, seasonal_lag, season_dummy, fourier_features, polynomial_features, interaction_features, hp_filter_features, hamilton_filter_features, savitzky_golay_features, wavelet_features, adaptive_ma_rf_features, asymmetric_trim_features, rank_space_features, moving_average_changes, align_reference_weights, weighted_aggregate, partial_least_squares_features, sliced_inverse_regression_features, dfm_features, variance_selection, correlation_selection, lasso_selection, lasso_path_selection, rfe_selection, boruta_selection, stability_selection, genetic_selection, select_features, feature_selection_requires_target, normalize_feature_selection_method, FeatureSelectionResult, random_projection_features, nystroem_features

macroforecast.feature_engineering

Additional transform, seasonal, expansion, filter, supervised aggregation, supervised factor, feature-selection, and kernel-approximation feature functions.

lag_step, rolling_step, moving_average_step, marx_step, transform_step, seasonal_lag_step, season_dummy_step, fourier_step, time_step, polynomial_step, interaction_step, scale_step, pca_step, sparse_pca_chen_rohe_step, varimax_step, group_pca_step, maf_step, hamilton_step, random_projection_step, nystroem_step, partial_least_squares_step, sliced_inverse_regression_step, custom_step

macroforecast.feature_engineering

Reusable step dictionaries for compose_features and runner-safe feature_spec pipelines. Feature selection uses individual method names in step mappings instead of a generic step builder.

pca_then_lags, lags_then_pca, moving_average_pca_lags

macroforecast.feature_engineering

Convenience composed feature callables.

ModelFit, VolatilityFit, SavedModel, save_fit, load_fit

macroforecast.models

Fitted model result wrappers and low-level fit persistence.

ols, ridge, nonneg_ridge, shrink_to_target_ridge, fused_difference_ridge, random_walk_ridge, tvp_ridge, lasso, elastic_net, adaptive_lasso, adaptive_elastic_net, group_lasso, sparse_group_lasso, bayesian_ridge, huber, kernel_ridge, knn, glmboost, pls, scaled_pca, supervised_pca, supervised_scaled_pca

macroforecast.models

Linear, penalized, grouped, time-varying ridge, kernel, nearest-neighbor, and supervised dimension-reduction models.

supervised_aggregation, component_aggregation, rank_aggregation, assemblage_regression, albacore_components, albacore_ranks

macroforecast.models

Generic supervised aggregation and Albacore/assemblage wrappers.

solve_nonnegative_ridge, solve_simplex_ridge, solve_target_shrinkage_ridge, solve_mean_aligned_ridge, solve_fused_difference_ridge

macroforecast.models

Low-level constrained aggregation solver helpers returning weight vectors.

svr, linear_svr, nu_svr

macroforecast.models

Support-vector regression models.

nn, lstm, gru, transformer, hemisphere_nn, density_hnn

macroforecast.models

Torch-backed neural-network and density-forecast regressors; require macroforecast[deep].

ar, arima, auto_arima, var, bvar_minnesota, bvar_normal_inverse_wishart, ets, holt_winters, theta_method, naive, seasonal_naive, random_walk_drift, stlf, far, favar

macroforecast.models

Time-series, Bayesian VAR, exponential-smoothing, and factor-augmented forecasting models.

dfm_mixed_mariano_murasawa, dfm_unrestricted_midas, midas_almon, midas_beta, midas_step, restricted_midas, unrestricted_midas

macroforecast.models

Mixed-frequency dynamic-factor and MIDAS models.

decision_tree, random_forest, extra_trees, gradient_boosting, mars, xgboost, lightgbm, lgb_plus, lgba_plus, catboost

macroforecast.models

Tree, spline, ML, and LGB+ hybrid regressors.

quantile_regression_forest, macro_random_forest

macroforecast.models

Macro-specific tree models.

LGBPlusRegressor, LGBAPlusRegressor

macroforecast.models

LGB+ competition and LGB^A+ alternating estimator classes.

garch11, egarch, gjr_garch, tgarch, realized_garch

macroforecast.models

Volatility models.

ModelSpec, ModelParameter, custom_model, get_model, list_model_specs, describe_model, model_search_space

macroforecast.models

Model-owned defaults and hyperparameter spaces.

BaggingRegressor, BoogingRegressor, RandomSubspaceRegressor, StackingRegressor, SuperLearnerRegressor, MODEL_ENSEMBLE_BASE_ESTIMATORS, MODEL_ENSEMBLE_SPECS, bagging, subagging, random_subspace, stacking, super_learner, booging, custom_model_ensemble, get_model_ensemble, list_model_ensemble_bases, list_model_ensemble_specs, describe_model_ensemble, model_ensemble_search_space

macroforecast.model_ensemble

Fit-time model-composition callables, estimator classes, and specs.

WindowSpec, EstimationWindow, ValWindow, TestWindow, AlignmentWindow, StagePolicy, Split

macroforecast.window

Forecast experiment and stage timing objects.

from_cutoffs, estimation_expanding, estimation_rolling, estimation_fixed, val_last_block, val_poos, val_expanding, val_rolling_blocks, val_blocked_kfold, val_random_kfold, test_origins, alignment_drop_incomplete, alignment_keep_missing

macroforecast.window

Component window builders.

last_block, poos, expanding, rolling_blocks, blocked_kfold, random_kfold

macroforecast.window

Shortcut window specs.

stage_policy, custom_stage_policy, stage_index, stage_panel, last_block_split, poos_split, expanding_split, rolling_blocks_split, blocked_kfold_split, random_kfold_split, make_splitter, resolve_window, resolve_stage_policy, split_table, normalize_window_name

macroforecast.window

Stage timing, resolver helpers, and train/val split inspection.

metrics

macroforecast.metrics

Forecast scoring namespace, including point scores and risk-adjusted forecast-return metrics. Use mf.metrics.rmse, not mf.rmse.

tests

macroforecast.tests

Forecast-comparison test namespace, including mf.tests.custom_test, mf.tests.equal_predictive_tests, mf.tests.model_confidence_set, mf.tests.blocked_oob_reality_check, mf.tests.superior_predictive_ability_test, mf.tests.reality_check_test, mf.tests.stepm_test, interval coverage, and PIT diagnostics. Use mf.tests.dm_test, not mf.dm_test.

EvaluationReport, evaluate_report, aggregate_scores, filter_oos_period, error_decomposition, benchmark_comparison, regime_scores

macroforecast.evaluation

Multi-slice evaluation reports, OOS filtering, error decomposition, benchmark comparisons, and regime scoring.

evaluation

macroforecast.evaluation

Evaluation namespace exposing report functions plus metrics and tests; raw metric/test functions are not re-exported directly from it.

pipeline

macroforecast.pipeline

Comprehensive POOS pipeline namespace: pipeline_spec, resolve_target, Arm, EvalSpec, CombinationContender, TCODE_TARGET_MAP.

SearchSpec, SearchResult, SearchError, ParamDistribution, search_spec, select_params

macroforecast.model_selection

Model-parameter selection over a supplied window and metric.

fixed, grid, random_search, cv_path, bayesian_search, genetic_search, custom_search, choice, uniform, log_uniform, randint

macroforecast.model_selection

Search specification and distribution builders.

ForecastResult, run, run_forecast

macroforecast.forecasting

Windowed forecast runner.

CombinationSpec, combination_spec, custom_combination, combine_mean, combine_median, combine_trimmed_mean, combine_winsorized_mean, combine_inverse_mspe, combine_dmspe, combine_best_n, combine_bates_granger, combine_granger_ramanathan, combine_constrained_ls, combine_eigenvector, combine_regularized, combine_linear_pool, combine_log_pool

macroforecast.forecasting

Runner-integrated and direct forecast combination methods.

Submodules#

Module

Purpose

macroforecast.meta

Global defaults.

macroforecast.data

Data loading and study data specs.

macroforecast.preprocessing

Pandas preprocessing functions.

macroforecast.filters

Direct one-series filters and smoothers such as HP, Hamilton, Savitzky-Golay, wavelet-style components, and AlbaMA.

macroforecast.feature_engineering

Direct-forecast target construction and composable ML feature transforms.

macroforecast.feature_analysis

Feature-matrix analysis after feature engineering.

macroforecast.feature_diagnostic

Compatibility alias for macroforecast.feature_analysis.

macroforecast.models

Callable model fits.

macroforecast.model_ensemble

Fit-time model composition over multiple member models.

macroforecast.window

Macro forecasting time-frame specs.

macroforecast.model_selection

Hyperparameter search and parameter selection.

macroforecast.forecasting

Windowed runner and forecast combination.

macroforecast.forecast_analysis

Forecast-result analysis after runner execution.

macroforecast.forecast_diagnostic

Compatibility alias for macroforecast.forecast_analysis.

macroforecast.metrics

Scoring metrics, forecast ranking, and metric resolution.

macroforecast.tests

Forecast-comparison tests and residual diagnostics.

macroforecast.evaluation

Evaluation reports, OOS filtering, error decomposition, benchmark comparisons, regime scoring, and namespace links to metrics and tests.

macroforecast.interpretation

Model-native importance, model-agnostic effects, SHAP/anatomy attribution, OLS-as-attention, VAR interpretation, and deep optional helpers.

macroforecast.output

Output generation, artifact writing, provenance collection, hashing, and compression.

macroforecast.reporting

Presentation/report formatting, paper-table presets, and rendering without artifact writing.

macroforecast.pipeline

Comprehensive POOS pipeline: spec generator, t-code target resolution, arms, combinations, evaluation.

macroforecast.data_analysis

Single-panel diagnostics, summaries, and raw-versus-processed comparison.