euromod_linking.runner

Executing a EUROMOD simulation on transformed input.

Plain functions returning plain values. The library’s job is to produce transformed microdata (apply_scenario); running it is one call to System.run(). An application that wants caching, retries or a run registry writes that around apply_scenario rather than plugging a strategy in here.

Dataset resolution and argument normalisation live here because they are model knowledge: which .txt backs a dataset name, and how grouped constants must be shaped for constantsToOverwrite.

Paths are always arguments — a library must not silently resolve which model it runs against from the environment.

Exceptions

RunError

A simulation could not be executed (bad dataset, engine failure, ...).

Functions

bestmatch_dataset_name(→ str | None)	The connector's own best-match dataset for a system (authoritative).
dataset_file(→ pathlib.Path | None)	Locate a dataset .txt, supporting a flat repository (all files in one
execute(system, data, *, country_code, input_path[, ...])	Run one simulation and return its output DataFrame.
fallback_candidates(→ list[pathlib.Path])	All CC_*.txt datasets, newest name first.
frames_identical(→ bool)	Are two simulation outputs the same to the last cent?
normalize_constants(→ dict)	Normalise constants to the {(name, group): value} shape run() wants.
resolve_dataset(system, country_code, dataset_name, ...)	Resolve which dataset file to run.

Module Contents

exception euromod_linking.runner.RunError

A simulation could not be executed (bad dataset, engine failure, …).

euromod_linking.runner.bestmatch_dataset_name(system) → str | None

The connector’s own best-match dataset for a system (authoritative).

euromod_linking.runner.dataset_file(dataset_name: str, cc: str, input_path: str) → pathlib.Path | None

Locate a dataset .txt, supporting a flat repository (all files in one directory) or a per-country subdirectory layout.

euromod_linking.runner.execute(system, data, *, country_code: str, input_path: str, dataset_name: str | None = None, constants=None, addons=None, extensions=None)

Run one simulation and return its output DataFrame.

Raises RunError if the engine fails.

euromod_linking.runner.fallback_candidates(cc: str, input_path: str) → list[pathlib.Path]

All CC_*.txt datasets, newest name first.

euromod_linking.runner.frames_identical(a, b) → bool

Are two simulation outputs the same to the last cent?

Used to detect a scenario that transformed the input but had no effect on the results — an invalid run, not ‘the reform has no impact’.

euromod_linking.runner.normalize_constants(constants) → dict

Normalise constants to the {(name, group): value} shape run() wants.

Accepts {"$name": v}, {"$name|group": v} (split on the last |) or a list of {"name", "group"?, "value"}. Uprating factors are grouped by year, e.g. ("$f_cpi", "2023").

euromod_linking.runner.resolve_dataset(system, country_code: str, dataset_name: str | None, input_path: str)

Resolve which dataset file to run.

Explicit name wins; otherwise the system’s best match, and if that file is not on disk, the newest available CC_* dataset — flagged, never silent. Returns (path, resolved_name, bestmatch_name, used_bestmatch).