SimulationResults#

class bamengine.SimulationResults(role_data=<factory>, economy_data=<factory>, relationship_data=<factory>, config=<factory>, metadata=<factory>)[source]#

Bases: object

Container for simulation results with convenient data access methods.

This class is returned by Simulation.run() and provides structured access to simulation data, including time series of role states, economy-wide metrics, relationship edge data, and metadata about the simulation run.

Variables:

  • role_data (dict) – Time series data for each role, keyed by role name. Each value is a dict of arrays with shape (n_periods, n_agents).

  • economy_data (dict) – Time series of economy-wide metrics with shape (n_periods,).

  • relationship_data (dict) – Time series data for each relationship, keyed by relationship name. Each value is a dict of arrays. When aggregated, arrays have shape (n_periods,). When not aggregated, values are lists of variable-length arrays (one per period).

  • config (dict) – Configuration parameters used for this simulation.

  • metadata (dict) – Run metadata (seed, runtime, n_periods, etc.).

Examples

>>> sim = bam.Simulation.init(n_firms=100, seed=42)
>>> results = sim.run(n_periods=100, collect=True)
>>> # Get all data as DataFrame
>>> df = results.to_dataframe()
>>> # Get specific role data
>>> prod_df = results.get_role_data("Producer")
>>> # Access economy metrics directly
>>> unemployment = results.economy_data["unemployment_rate"]
>>> # Access relationship data (when collected)
>>> results = sim.run(n_periods=100, collect={"LoanBook": True, "aggregate": "sum"})
>>> total_principal = results.relationship_data["LoanBook"]["principal"]
role_data#

Per-role time series data keyed by role name then variable name.

economy_data#

Economy-wide metric time series keyed by metric name.

relationship_data#

Per-relationship time series data keyed by relationship name then field name.

config#

Configuration parameters used for this simulation run.

metadata#

Run metadata including seed, runtime, and period count.

to_dataframe(roles=None, variables=None, include_economy=True, aggregate=None, relationships=None)[source]#

Export results to a pandas DataFrame.

Parameters:

  • roles (list of str, optional) – Specific roles to include. If None, includes all roles.

  • variables (list of str, optional) – Specific variables to include. If None, includes all variables.

  • include_economy (bool, default True) – Whether to include economy-wide metrics.

  • aggregate ({'mean', 'median', 'sum', 'std'}, optional) – How to aggregate agent-level data. If None, returns all agents.

  • relationships (list of str, optional) – Specific relationships to include. If None, includes all relationships with aggregated data. Relationships with non-aggregated data (list of arrays) are skipped with a warning.

Returns:

DataFrame with simulation results. Index is period number. Columns depend on parameters and aggregation method.

Return type:

pd.DataFrame

Raises:

ImportError – If pandas is not installed.

Examples

# Get everything >>> df = results.to_dataframe()

# Get only Producer price and inventory, averaged >>> df = results.to_dataframe( … roles=[“Producer”], variables=[“price”, “inventory”], aggregate=”mean” … )

# Get only economy metrics >>> df = results.to_dataframe(include_economy=True, roles=[])

# Include relationship data >>> df = results.to_dataframe(relationships=[“LoanBook”])

get_role_data(role_name, aggregate=None)[source]#

Get data for a specific role as a DataFrame.

Parameters:

  • role_name (str) – Name of the role (e.g., ‘Producer’, ‘Worker’).

  • aggregate ({'mean', 'median', 'sum', 'std'}, optional) – How to aggregate across agents.

Returns:

DataFrame with the role’s time series data.

Return type:

pd.DataFrame

Raises:

ImportError – If pandas is not installed.

Examples

>>> prod_df = results.get_role_data("Producer")
>>> prod_mean = results.get_role_data("Producer", aggregate="mean")
get_relationship_data(rel_name, aggregate=None)[source]#

Get data for a specific relationship as a DataFrame.

Parameters:

  • rel_name (str) – Name of the relationship (e.g., ‘LoanBook’).

  • aggregate ({'mean', 'median', 'sum', 'std'}, optional) – How to aggregate (only used if data needs re-aggregation).

Returns:

DataFrame with the relationship’s time series data.

Return type:

pd.DataFrame

Raises:

ImportError – If pandas is not installed.

Notes

If the relationship data was collected without aggregation (variable-length arrays per period), this method will issue a warning and return an empty DataFrame. Use results.relationship_data[rel_name] directly for such data.

Examples

>>> loans_df = results.get_relationship_data("LoanBook")
property economy_metrics#

Get economy-wide metrics as a DataFrame.

Returns:

DataFrame with economy time series (unemployment rate, GDP, etc.).

Return type:

pd.DataFrame

Raises:

ImportError – If pandas is not installed.

Examples

>>> econ_df = results.economy_metrics
>>> econ_df[["unemployment_rate", "avg_price"]].plot()
property data#

Unified access to all data (roles + economy + relationships).

Economy data is accessible under the “Economy” key. Relationship data is merged with role data (relationships have unique names so no conflicts).

Returns:

Combined role, economy, and relationship data. Keys are role names, relationship names, and “Economy” for economy metrics.

Return type:

dict

Examples

>>> results.data["Producer"]["price"]
>>> results.data["Economy"]["unemployment_rate"]
>>> results.data["LoanBook"]["principal"]  # if collected
get(name, variable_name, aggregate=None)[source]#

Get a variable as a numpy array.

This provides a convenient way to access simulation data without needing to navigate nested dictionaries.

Parameters:

  • name (str) – Role, relationship, or “Economy” name (e.g., “Producer”, “LoanBook”, “Economy”).

  • variable_name (str) – Variable name (“price”, “principal”, “unemployment_rate”, etc.)

  • aggregate ({'mean', 'sum', 'std', 'median'}, optional) – Aggregation method for 2D data. If provided, reduces (n_periods, n_agents) to (n_periods,).

Returns:

1D array (n_periods,), 2D array (n_periods, n_agents), or list of arrays for non-aggregated relationship data.

Return type:

NDArray or list[NDArray]

Raises:

KeyError – If role/relationship or variable not found.

Examples

>>> productivity = results.get("Producer", "labor_productivity")
>>> avg_prod = results.get("Producer", "labor_productivity", aggregate="mean")
>>> unemployment = results.get("Economy", "unemployment_rate")
>>> total_principal = results.get("LoanBook", "principal")
get_array(name, variable_name, aggregate=None)[source]#

Deprecated: use get() instead.

property summary#

Get summary statistics for key metrics.

Returns:

Summary statistics (mean, std, min, max) for key variables.

Return type:

pd.DataFrame

Raises:

ImportError – If pandas is not installed.

Examples

>>> print(results.summary)
save(filepath)[source]#

Save results to disk (HDF5 or pickle format).

Parameters:

filepath (str) – Path to save file. Use .h5 for HDF5, .pkl for pickle.

Examples

>>> results.save("results.h5")
>>> results.save("results.pkl")
classmethod load(filepath)[source]#

Load results from disk.

Parameters:

filepath (str) – Path to saved results file.

Returns:

Loaded results object.

Return type:

SimulationResults

Examples

>>> results = SimulationResults.load("results.h5")
__repr__()[source]#

String representation showing summary information.

__init__(role_data=<factory>, economy_data=<factory>, relationship_data=<factory>, config=<factory>, metadata=<factory>)#
__getitem__(key)[source]#

Access data via flat ‘Name.variable’ key.

__getattr__(name)[source]#

Attribute-style access to collected data namespaces.

__dir__()[source]#

List available attributes including collected data names.

available()[source]#

List all collected data as ‘Name.variable’ strings.

Returns:

Sorted list of available data keys.

Return type:

list[str]

Examples

>>> results.available()
['Economy.avg_price', 'Economy.inflation', 'Producer.production', ...]