Recipe API quickstart#

Run a core layer-contract forecast in under 5 minutes.

This quickstart uses mf.run(...), the v0.9.0 public entry point. It executes the core L1-L8 runtime: custom panels, deterministic L3 features, linear sklearn L4 models, point metrics, lightweight L6/L7 artifacts, diagnostics, and L8 file export.

For the exact support boundary, read Runtime Support Matrix.

Run A Minimal Core Recipe#

import macroforecast as mf

recipe = """
1_data:
  fixed_axes:
    custom_source_policy: custom_panel_only
    frequency: monthly
    horizon_set: custom_list
  leaf_config:
    target: y
    target_horizons: [1]
    custom_panel_inline:
      date: [2020-01-01, 2020-02-01, 2020-03-01, 2020-04-01, 2020-05-01, 2020-06-01]
      y: [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]
      x1: [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]
      x2: [2.0, 1.0, 2.0, 1.0, 2.0, 1.0]

2_preprocessing:
  fixed_axes:
    transform_policy: no_transform
    outlier_policy: none
    imputation_policy: none_propagate
    frame_edge_policy: keep_unbalanced

3_feature_engineering:
  nodes:
    - {id: src_X, type: source, selector: {layer_ref: l2, sink_name: l2_clean_panel_v1, subset: {role: predictors}}}
    - {id: src_y, type: source, selector: {layer_ref: l2, sink_name: l2_clean_panel_v1, subset: {role: target}}}
    - {id: lag_x, type: step, op: lag, params: {n_lag: 1}, inputs: [src_X]}
    - {id: y_h, type: step, op: target_construction, params: {mode: point_forecast, method: direct, horizon: 1}, inputs: [src_y]}
  sinks:
    l3_features_v1: {X_final: lag_x, y_final: y_h}
    l3_metadata_v1: auto

4_forecasting_model:
  nodes:
    - {id: src_X, type: source, selector: {layer_ref: l3, sink_name: l3_features_v1, subset: {component: X_final}}}
    - {id: src_y, type: source, selector: {layer_ref: l3, sink_name: l3_features_v1, subset: {component: y_final}}}
    - id: fit_ridge
      type: step
      op: fit_model
      params: {family: ridge, alpha: 1.0, min_train_size: 2, forecast_strategy: direct, training_start_rule: expanding, refit_policy: every_origin, search_algorithm: none}
      inputs: [src_X, src_y]
    - {id: predict_ridge, type: step, op: predict, inputs: [fit_ridge, src_X]}
  sinks:
    l4_forecasts_v1: predict_ridge
    l4_model_artifacts_v1: fit_ridge
    l4_training_metadata_v1: auto

5_evaluation:
  fixed_axes:
    primary_metric: mse
    point_metrics: [mse, rmse, mae]

8_output:
  fixed_axes:
    saved_objects: [forecasts, metrics, ranking]
  leaf_config:
    output_directory: ./macroforecast_output/quickstart/
"""

import macroforecast as mf
result = mf.run(recipe)
print(result.sink("l5_evaluation_v1").metrics_table)
print(result.sink("l8_artifacts_v1").output_directory)

mf.run accepts both YAML string and path.

What Gets Materialized#

The result object is an in-memory sink map:

forecasts = result.sink("l4_forecasts_v1")
metrics = result.sink("l5_evaluation_v1").metrics_table
ranking = result.sink("l5_evaluation_v1").ranking_table
output = result.sink("l8_artifacts_v1")

With 8_output enabled, the runtime writes:

macroforecast_output/quickstart/
  manifest.json
  recipe.json
  summary/
    metrics_all_cells.csv
    ranking.csv
  cell_001/
    forecasts.csv

Enabling Diagnostics, Tests, And Importance#

Add these blocks when needed:

1_5_data_summary:
  enabled: true
2_5_pre_post_preprocessing:
  enabled: true
3_5_feature_diagnostics:
  enabled: true
4_5_generator_diagnostics:
  enabled: true
6_statistical_tests:
  enabled: true
  sub_layers:
    L6_G_residual:
      enabled: true
7_interpretation:
  enabled: true
  nodes:
    - id: src_model
      type: source
      selector: {layer_ref: l4, sink_name: l4_model_artifacts_v1, subset: {model_id: fit_ridge}}
    - id: src_X
      type: source
      selector: {layer_ref: l3, sink_name: l3_features_v1, subset: {component: X_final}}
    - id: linear_imp
      type: step
      op: model_native_linear_coef
      params: {model_family: ridge}
      inputs: [src_model, src_X]
  sinks:
    l7_importance_v1:
      global: linear_imp

Next Steps#

Note on FRED data and real-time vintages: macroforecast v0.9.x uses final-revised FRED data (current vintage) when custom_source_policy: official_only is set. Real-time vintage tracking (ALFRED) is planned for v1.x; vintage_policy: real_time_alfred raises NotImplementedError in v0.9.x. For details and workarounds, see Your First Study — Real-Time Data Caveat.

Note on output directory naming: The runtime default is ./macrocast_output/<recipe_id>/<timestamp>/ (defined in macroforecast.core.types and macroforecast.core.layers.l8). To override, set output_directory in the 8_output.leaf_config block, as the examples above do (./macroforecast_output/quickstart/). The historical macrocast_output/ default is preserved for backward compatibility with v0.1-era manifests.