macroforecast.meta

Back to reference

Purpose

macroforecast.meta stores package-wide execution settings. These settings are used when a run does not pass a more specific value through a direct function argument. They do not choose data, preprocessing, features, models, evaluation metrics, or output files.

The module is intentionally small. It owns defaults and temporary overrides; direct function arguments and runner policies always take precedence over global settings.

Public Functions

Function	Purpose
configure	Update one or more global execution settings.
get_config	Return the full active configuration.
get_option	Return one active configuration value.
resolve_n_jobs	Resolve the configured worker count ('auto' resolves to the CPU count).
reset_config	Restore package defaults.
use_config	Temporarily override settings inside a with block.

Public Values

Symbol	Meaning
DEFAULT_RANDOM_SEED	Package default seed value, currently 42.
MetaConfig	Dictionary-like output schema for active meta settings.
NJobs	Accepted worker-count type: positive integer or "auto".
OnError	Stored failure-mode type: "raise" or "continue".
StageDefaultScope	Runner stage-scope type: "full_panel", "origin_available", or "fit_window".
MetadataLevel	Runner metadata detail type: "minimal", "standard", or "full".

MetaConfig

MetaConfig is the output schema returned by configure, get_config, reset_config, and yielded by use_config.

Output Schema

Key	Type	Default	Meaning
random_seed	int | None	42	Seed used by stochastic functions when no run-specific seed is supplied. None leaves stochastic components unseeded.
n_jobs	int | “auto”	1	Default worker count. 1 means serial execution; "auto" lets the package choose a bounded worker count.
on_error	failure mode	stop on error	Default cell failure behavior. See Failure Mode Values.
verbose	int	0	Default verbosity level for future logging surfaces.
default_preprocessing_scope	"full_panel", "origin_available", or "fit_window"	"origin_available"	Default forecasting.run(..., preprocessing_policy=...) scope when preprocessing is supplied and no explicit policy is passed.
default_feature_scope	"full_panel", "origin_available", or "fit_window"	"fit_window"	Default feature_policy scope.
default_selection_scope	"full_panel", "origin_available", or "fit_window"	"fit_window"	Default model_selection_policy scope.
metadata_level	"minimal", "standard", or "full"	"standard"	Runner metadata detail. minimal suppresses per-origin stage records; standard and full currently keep the same stage ledger.

The default seed is owned by macroforecast.meta.config.DEFAULT_RANDOM_SEED and is exported as macroforecast.meta.DEFAULT_RANDOM_SEED.

Failure Mode Values

User-facing mode	Stored value	Meaning
Stop on error	raise	Stop immediately when a supported execution cell fails.
Continue where supported	continue	Record the failure and continue for call sites that support non-fatal errors.

Stage Scope Aliases

Stage-scope inputs are normalized before storage. Docs and metadata use the canonical stored values.

Accepted input	Stored value	Meaning
"full", "full_panel", "global"	"full_panel"	Fit the stage on the full panel.
"origin", "origin_available", "available"	"origin_available"	Fit the stage on observations available at each forecast origin.
"fit", "fit_window", "train", "train_window"	"fit_window"	Fit the stage on the model fit window.

Example output:

{
    "random_seed": 42,
    "n_jobs": 1,
    "on_error": "raise",
    "verbose": 0,
    "default_preprocessing_scope": "origin_available",
    "default_feature_scope": "fit_window",
    "default_selection_scope": "fit_window",
    "metadata_level": "standard",
}

configure

Update package-wide execution settings and return the active configuration.

Signature

macroforecast.meta.configure(
    *,
    random_seed: int | None = ...,
    n_jobs: int | "auto" = ...,
    on_error: str = ...,
    verbose: int = ...,
    default_preprocessing_scope: "full_panel" | "origin_available" | "fit_window" = ...,
    default_feature_scope: "full_panel" | "origin_available" | "fit_window" = ...,
    default_selection_scope: "full_panel" | "origin_available" | "fit_window" = ...,
    metadata_level: "minimal" | "standard" | "full" = ...,
) -> MetaConfig

All inputs are keyword-only. Omitted inputs keep their current values.

Input

Name	Type	Default if omitted	Allowed Values	Meaning
random_seed	int | None	keep current value	non-negative integer or None	Sets the default seed for stochastic components.
n_jobs	int | “auto”	keep current value	positive integer or "auto"	Sets the default worker count.
on_error	failure mode	keep current value	Stop on error (raise) or continue where supported (continue)	Sets default failure behavior.
verbose	int	keep current value	non-negative integer	Sets default verbosity.
default_preprocessing_scope	str	keep current value	"full_panel", "origin_available", "fit_window"	Sets the default preprocessing stage scope for forecasting.run(...).
default_feature_scope	str	keep current value	"full_panel", "origin_available", "fit_window"	Sets the default feature-engineering stage scope.
default_selection_scope	str	keep current value	"full_panel", "origin_available", "fit_window"	Sets the default model-selection stage scope.
metadata_level	str	keep current value	"minimal", "standard", "full"	Sets the default runner metadata detail.

Stage-scope inputs also accept the aliases listed in Stage Scope Aliases. The returned MetaConfig always stores the canonical value.

Output

Returns MetaConfig, a copy of the full active configuration after the update.

Output	Type	Meaning
config	MetaConfig	The active package-wide execution settings.

Side Effects

configure changes global package state. Later calls that consult macroforecast.meta will see the updated values.

Validation

Condition	Error
random_seed is negative	ValueError
random_seed is not int or None	TypeError
n_jobs is not a positive integer or "auto"	TypeError or ValueError
on_error is not a supported failure mode	ValueError
verbose is not a non-negative integer	TypeError or ValueError
stage default scope is not one of the allowed scopes	ValueError
metadata_level is not "minimal", "standard", or "full"	ValueError

Example

import macroforecast as mf

config = mf.meta.configure(
    random_seed=7,
    n_jobs="auto",
    on_error="continue",
    default_feature_scope="origin_available",
    metadata_level="standard",
    verbose=1,
)

assert config["random_seed"] == 7

get_config

Return the active package-wide execution settings.

Signature

macroforecast.meta.get_config() -> MetaConfig

Input

No input.

Output

Returns MetaConfig.

Output	Type	Meaning
config	MetaConfig	Copy of the active package-wide execution settings.

The returned object is a copy. Mutating it does not change global package state.

Example

import macroforecast as mf

config = mf.meta.get_config()
print(config["n_jobs"])

get_option

Return one active configuration value.

Signature

macroforecast.meta.get_option(name: str) -> object

Input

Name	Type	Allowed Values	Meaning
name	str	any MetaConfig key	Configuration key to read.

Output

Returns the value for name.

name	Output Type
"random_seed"	int | None
"n_jobs"	int | “auto”
"on_error"	failure mode string
"verbose"	int
"default_preprocessing_scope"	"full_panel", "origin_available", or "fit_window"
"default_feature_scope"	"full_panel", "origin_available", or "fit_window"
"default_selection_scope"	"full_panel", "origin_available", or "fit_window"
"metadata_level"	"minimal", "standard", or "full"

Errors

Condition	Error
name is not a known option	KeyError

Example

import macroforecast as mf

seed = mf.meta.get_option("random_seed")

reset_config

Restore package-wide execution settings to their defaults.

Signature

macroforecast.meta.reset_config() -> MetaConfig

Input

No input.

Output

Returns MetaConfig after reset.

Key	Reset Value
random_seed	42
n_jobs	1
on_error	"raise"
verbose	0
default_preprocessing_scope	"origin_available"
default_feature_scope	"fit_window"
default_selection_scope	"fit_window"
metadata_level	"standard"

Side Effects

reset_config changes global package state.

Example

import macroforecast as mf

mf.meta.configure(random_seed=123, n_jobs=4)
config = mf.meta.reset_config()

assert config["random_seed"] == 42
assert config["n_jobs"] == 1

use_config

Temporarily override package-wide execution settings inside a context manager.

Signature

macroforecast.meta.use_config(
    *,
    random_seed: int | None = ...,
    n_jobs: int | "auto" = ...,
    on_error: str = ...,
    verbose: int = ...,
    default_preprocessing_scope: "full_panel" | "origin_available" | "fit_window" = ...,
    default_feature_scope: "full_panel" | "origin_available" | "fit_window" = ...,
    default_selection_scope: "full_panel" | "origin_available" | "fit_window" = ...,
    metadata_level: "minimal" | "standard" | "full" = ...,
) -> Iterator[MetaConfig]

Input

The inputs match configure.

Name	Type	Default if omitted	Allowed Values	Meaning
random_seed	int | None	keep current value inside context	non-negative integer or None	Temporary default seed.
n_jobs	int | “auto”	keep current value inside context	positive integer or "auto"	Temporary worker count.
on_error	failure mode	keep current value inside context	Stop on error (raise) or continue where supported (continue)	Temporary failure behavior.
verbose	int	keep current value inside context	non-negative integer	Temporary verbosity.
default_preprocessing_scope	str	keep current value inside context	"full_panel", "origin_available", "fit_window"	Temporary preprocessing default scope.
default_feature_scope	str	keep current value inside context	"full_panel", "origin_available", "fit_window"	Temporary feature default scope.
default_selection_scope	str	keep current value inside context	"full_panel", "origin_available", "fit_window"	Temporary model-selection default scope.
metadata_level	str	keep current value inside context	"minimal", "standard", "full"	Temporary metadata detail.

Stage-scope inputs use the same alias normalization as configure.

Output

Yields MetaConfig, the active configuration inside the context.

Output	Type	Meaning
config	MetaConfig	Active temporary settings inside the with block.

Side Effects

use_config changes global package state only for the duration of the with block. The previous configuration is restored when the block exits, including when an exception is raised.

Example

import macroforecast as mf

mf.meta.configure(random_seed=42)

with mf.meta.use_config(random_seed=7, n_jobs=2) as config:
    assert config["random_seed"] == 7
    # Run code here with the temporary settings.

assert mf.meta.get_option("random_seed") == 42

Usage Behavior

Direct package functions can read macroforecast.meta when no more specific value is provided by the caller.

Setting	Use
random_seed	Used as the default run seed and propagated to stochastic estimators where supported.
n_jobs	Used as the default worker count for run-level and selected model-level parallel work.
on_error	Default failure handling. raise stops on failure; continue continues where supported.
verbose	Reserved as the package-wide verbosity setting.
default_preprocessing_scope	Used by forecasting.run(...) when preprocessing is supplied without preprocessing_policy.
default_feature_scope	Used by forecasting.run(...) when feature_policy is omitted.
default_selection_scope	Used by forecasting.run(...) when model_selection_policy is omitted.
metadata_level	Controls how much run-level metadata is recorded. minimal drops per-origin stage records; standard and full currently keep the same stage ledger.

Forecast results record the active config under metadata["run"]["config"] so a completed run can be audited against the settings in force at execution time.