simulatingrisk 1.0.0__py3-none-any.whl

simulatingrisk/hawkdovemulti/analysis_utils.py

@@ -0,0 +1,83 @@
+"""
+utility methods for analyzing data collected generated by this model
+"""
+
+import altair as alt
+import polars as pl
+
+from simulatingrisk.hawkdovemulti.model import RiskState
+
+
+def groupby_population_risk_category(df):
+    """takes a polars dataframe populated with model data generated
+    by hawk/dove multi model, groups by population risk category and
+    adds group labels."""
+    # currently written for polars dataframe
+
+    # group on risk category to get totals for the  number of runs that
+    # ended up in each different type
+    poprisk_grouped = df.group_by("population_risk_category").count()
+    poprisk_grouped = poprisk_grouped.rename(
+        {"population_risk_category": "risk_category"}
+    )
+    poprisk_grouped = poprisk_grouped.sort("risk_category")
+
+    # add column with readable group labels for the numeric categories
+    poprisk_grouped = poprisk_grouped.with_columns(
+        pl.Series(
+            name="type",
+            values=poprisk_grouped["risk_category"].map_elements(
+                RiskState.category, return_type=pl.datatypes.String
+            ),
+        )
+    )
+    return poprisk_grouped
+
+
+def graph_population_risk_category(poprisk_grouped):
+    """given a dataframe grouped by :meth:`groupby_population_risk_category`,
+    generate an altair chart graphing the number of runs in each type,
+    grouped and labeled by the larger categories."""
+    return (
+        alt.Chart(poprisk_grouped)
+        .mark_bar(width=15)
+        .encode(
+            x=alt.X(
+                "risk_category",
+                title="risk category",
+                axis=alt.Axis(tickCount=13),  # 13 categories
+                scale=alt.Scale(domain=[1, 13]),
+            ),
+            y=alt.Y("count", title="Number of runs"),
+            color=alt.Color("type", title="type"),
+        )
+        .properties(title="Distribution of runs by final population risk category")
+    )
+
+
+def grouped_risk_totals(df):
+    """Given a Polars dataframe populated with model data generated
+    by hawk/dove multi model, calculate total number of agents by
+    groups of risk level categories."""
+
+    # NOTE: based on risk level groupings used in
+    # model method for calculating population risk category
+
+    return df.with_columns(
+        # risk inclined: 0, 1, 2
+        pl.col("total_r0")
+        .add(pl.col("total_r1"))
+        .add(pl.col("total_r2"))
+        .alias("risk_inclined"),
+        # risk moderate: 3, 4, 5, 6
+        pl.col("total_r3")
+        .add(pl.col("total_r4"))
+        .add(pl.col("total_r5"))
+        .add(pl.col("total_r6"))
+        .alias("risk_moderate"),
+        # risk avoidant: 7, 8, 9
+        pl.col("total_r7")
+        .add(pl.col("total_r8"))
+        .add(pl.col("total_r9"))
+        .alias("risk_avoidant"),
+    )

simulatingrisk/hawkdovemulti/app.py

@@ -0,0 +1,242 @@
+# solara/jupyterviz app
+import altair as alt
+from mesa.experimental import JupyterViz
+import solara
+
+
+from simulatingrisk.hawkdovemulti.model import HawkDoveMultipleRiskModel
+from simulatingrisk.hawkdove.server import (
+    agent_portrayal,
+    common_jupyterviz_params,
+    draw_hawkdove_agent_space,
+    neighborhood_sizes,
+)
+from simulatingrisk.hawkdove.model import divergent_colors_10
+
+# start with common hawk/dove params, then add params for variable risk
+jupyterviz_params_var = common_jupyterviz_params.copy()
+jupyterviz_params_var.update(
+    {
+        "risk_adjustment": {
+            "type": "Select",
+            "value": "adopt",
+            "values": ["none", "adopt", "average"],
+            "description": "If and how agents update their risk level",
+        },
+        "risk_distribution": {
+            "type": "Select",
+            "value": "uniform",
+            "values": HawkDoveMultipleRiskModel.risk_distribution_options,
+            "description": "Distribution for initial risk attitudes",
+        },
+        "adjust_every": {
+            "label": "Adjustment frequency (# rounds)",
+            "type": "SliderInt",
+            "min": 1,
+            "max": 30,
+            "step": 1,
+            "value": 10,
+            "description": "How many rounds between risk adjustment",
+        },
+        "adjust_neighborhood": {
+            "type": "Select",
+            "value": 8,
+            "values": neighborhood_sizes,
+            "label": "Adjustment neighborhood size",
+        },
+        "adjust_payoff": {
+            "type": "Select",
+            "label": "Adjustment comparison period",
+            "value": "recent",
+            "values": HawkDoveMultipleRiskModel.supported_adjust_payoffs,
+            "description": "Compare recent payoff (since last adjustment "
+            + "round) or total (cumulative from start) when adjusting risk attitudes",
+        },
+    }
+)
+
+# use same divergent color scale across charts
+color_scale_opts = {"domain": list(range(10)), "range": divergent_colors_10}
+
+
+def plot_agents_by_risk(model):
+    """plot total number of agents for each risk attitude"""
+    agent_df = model.datacollector.get_agent_vars_dataframe().reset_index().dropna()
+    if agent_df.empty:
+        return
+
+    last_step = agent_df.Step.max()
+    # plot current status / last round
+    last_round = agent_df[agent_df.Step == last_step]
+    # count number of agents for each status
+    grouped = last_round.groupby("risk_level", as_index=False).agg(
+        total=("AgentID", "count")
+    )
+
+    # bar chart to show number of agents for each risk attitude
+    # configure domain to always display all statuses;
+    # limit changes depending on if diagonals are included
+    # (NOTE: bug in mesa 2.12, checkbox param does not propagate)
+    bar_chart = (
+        alt.Chart(grouped)
+        .mark_bar(width=15)
+        .encode(
+            x=alt.X(
+                "risk_level",
+                title="risk attitude",
+                axis=alt.Axis(tickCount=model.max_risk_level + 1),
+                scale=alt.Scale(domain=[model.min_risk_level, model.max_risk_level]),
+            ),
+            y=alt.Y("total", title="Number of agents"),
+            # NOTE: could apply divergent color scheme here, but it's actually
+            # distracting from the main point of this chart, which is quantitative
+            # color=alt.Color("risk_level:N").scale(**color_scale_opts),
+        )
+        .properties(title="Number of agents with each risk attitude")
+    )
+    return solara.FigureAltair(bar_chart)
+
+
+def plot_risklevel_changes(model):
+    """plot the number of agents who updated their risk attitude on
+    the last adjustment round"""
+    model_df = model.datacollector.get_model_vars_dataframe().reset_index()
+    if model_df.empty:
+        return
+    # subset dataframe to only the adjustment rounds
+    model_df = model_df[:: model.adjust_round_n]
+    if model_df.empty:
+        return
+    # limit to fields we need
+    model_df = model_df[["index", "num_agents_risk_changed", "sum_risk_level_changes"]]
+    # rename columns before they become variable labels
+    model_df.rename(
+        columns={
+            "num_agents_risk_changed": "agents",
+            "sum_risk_level_changes": "risk attitude totals",
+        },
+        inplace=True,
+    )
+    # "melt" to flatten so we can graph as two variables in altair
+    melted_df = (
+        model_df.melt(id_vars=["index"])
+        .dropna()
+        .rename(columns={"variable": "category"})
+    )
+
+    line_chart = (
+        alt.Chart(melted_df)
+        .mark_line()
+        .encode(
+            y=alt.Y(
+                "value",
+                title="# changes",
+                scale=alt.Scale(domain=[0, model.num_agents]),
+            ),
+            x=alt.X("index"),
+            color="category",
+        )
+        .properties(title="Risk attitude adjustments")
+    )
+
+    return solara.FigureAltair(line_chart)
+
+
+def plot_hawks_by_risk(model):
+    """plot rolling mean of percent of agents in each risk level
+    who chose hawk over last several rounds"""
+
+    # in the first round, mesa returns a dataframe full of NAs; ignore that
+    agent_df = (
+        model.datacollector.get_agent_vars_dataframe()
+        .reset_index()
+        .dropna(subset=["AgentID"])
+    )
+    if agent_df.empty:
+        return
+
+    last_step = agent_df.Step.max()
+    # limit to last N rounds (how many ?)
+    last_n_rounds = agent_df[agent_df.Step.gt(last_step - 60)].copy()
+    last_n_rounds["hawk"] = last_n_rounds.choice.apply(
+        lambda x: 1 if x == "hawk" else 0
+    )
+    # for each step and risk level, get number of agents and number of hawks
+    grouped = (
+        last_n_rounds.groupby(["Step", "risk_level"], as_index=False)
+        .agg(hawk=("hawk", "sum"), agents=("AgentID", "count"))
+        .sort_values("Step")
+    )
+    # calculate percent hawk within each group
+    grouped["percent_hawk"] = grouped.apply(lambda row: row.hawk / row.agents, axis=1)
+    # now calculate rolling percent within each risk attitude
+    # thanks to https://stackoverflow.com/a/53339204
+    grouped["rolling_pct_hawk"] = grouped.groupby("risk_level")[
+        "percent_hawk"
+    ].transform(lambda x: x.rolling(15, 1).mean())
+
+    # starting domain 0-50 so it doesn't jump / expand as much
+    max_step = max(last_step or 0, 50)
+    min_step = max(max_step - 50, 0)
+
+    chart = (
+        alt.Chart(grouped[grouped.Step.gt(min_step - 1)])
+        .mark_line()
+        .encode(
+            x=alt.X("Step", scale=alt.Scale(domain=[min_step, max_step])),
+            y=alt.Y(
+                "rolling_pct_hawk",
+                title="rolling % hawk",
+                scale=alt.Scale(domain=[0, 1]),
+            ),
+            color=alt.Color("risk_level:N", title="risk attitude").scale(
+                **color_scale_opts
+            ),
+        )
+        .properties(title="Rolling average percent hawk by risk level")
+    )
+    return solara.FigureAltair(chart)
+
+
+def plot_wealth_by_risklevel(model):
+    """plot wealth distribution for each risk level"""
+    agent_df = model.datacollector.get_agent_vars_dataframe().reset_index().dropna()
+    if agent_df.empty:
+        return
+
+    last_step = agent_df.Step.max()
+    # plot current status / last round
+    last_round = agent_df[agent_df.Step == last_step]
+
+    wealth_chart = (
+        alt.Chart(last_round)
+        .mark_boxplot(extent="min-max")
+        .encode(
+            alt.X(
+                "risk_level",
+                scale=alt.Scale(domain=[model.min_risk_level, model.max_risk_level]),
+                title="risk attitude",
+            ),
+            alt.Y("points", title="wealth").scale(zero=False),
+        )
+        .properties(title="Cumulative wealth by risk attitude")
+    )
+    return solara.FigureAltair(wealth_chart)
+
+
+page = JupyterViz(
+    HawkDoveMultipleRiskModel,
+    jupyterviz_params_var,
+    measures=[
+        plot_agents_by_risk,
+        plot_hawks_by_risk,
+        plot_wealth_by_risklevel,
+        plot_risklevel_changes,
+        # plot_hawks,
+    ],
+    name="Hawk/Dove game with multiple risk attitudes",
+    agent_portrayal=agent_portrayal,
+    space_drawer=draw_hawkdove_agent_space,
+)
+# required to render the visualization with Jupyter/Solara
+page

simulatingrisk/hawkdovemulti/batch_run.py

@@ -0,0 +1,328 @@
+#!/usr/bin/env python
+
+import argparse
+import csv
+import multiprocessing
+import os
+from datetime import datetime
+
+from mesa.batchrunner import _collect_data, _make_model_kwargs
+from tqdm.auto import tqdm
+
+from simulatingrisk.hawkdovemulti.model import HawkDoveMultipleRiskModel
+
+neighborhood_sizes = list(HawkDoveMultipleRiskModel.neighborhood_sizes)
+
+# NOTE: it's better to be explicit about even parameters
+# instead of relying on model defaults, because
+# parameters specified here are included in data exports
+
+
+# combination of parameters we want to run
+params = {
+    "default": {
+        "grid_size": [5, 10, 25],  # , 50],  # 100],
+        "risk_adjustment": ["adopt", "average"],
+        "play_neighborhood": neighborhood_sizes,
+        "observed_neighborhood": neighborhood_sizes,
+        "adjust_neighborhood": neighborhood_sizes,
+        "hawk_odds": [0.5, 0.25, 0.75],
+        "adjust_every": [2, 10, 20],
+        "risk_distribution": HawkDoveMultipleRiskModel.risk_distribution_options,
+        "adjust_payoff": HawkDoveMultipleRiskModel.supported_adjust_payoffs,
+        # random?
+    },
+    # specific scenarios to allow paired statistical tests
+    "risk_adjust": {
+        # any risk adjustment
+        "risk_adjustment": ["adopt", "average"],
+        "risk_distribution": "uniform",
+        # use model defaults; grid size must be specified
+        "grid_size": [5, 10, 25],
+    },
+    "payoff": {
+        "adjust_payoff": HawkDoveMultipleRiskModel.supported_adjust_payoffs,
+        "risk_distribution": "uniform",
+        # use model defaults; grid size must be specified
+        "grid_size": 25,
+    },
+    "distribution": {
+        "risk_distribution": HawkDoveMultipleRiskModel.risk_distribution_options,
+        # adopt tends to converge faster; LB also says it's more interesting & simpler
+        "risk_adjustment": "adopt",
+        # use model defaults; grid size must be specified
+        "grid_size": 10,
+    },
+    "no_adjustment": {
+        # no risk adjustment
+        "risk_adjustment": None,
+        "risk_distribution": HawkDoveMultipleRiskModel.risk_distribution_options,
+        "play_neighborhood": neighborhood_sizes,
+        "observed_neighborhood": neighborhood_sizes,
+        # adjust payoff doesn't matter since we're not adjusting
+        "grid_size": [5, 10, 25],
+        # maybe also hawk odds
+    },
+}
+
+
+# method for multiproc running model with a set of params
+def run_hawkdovemulti_model(args):
+    run_id, iteration, params, max_steps, data_collection_period = args
+    # simplified model runner adapted from mesa batch run code
+
+    model = HawkDoveMultipleRiskModel(**params)
+    while model.running and model.schedule.steps <= max_steps:
+        try:
+            model.step()
+        # by default, signals propagate to all processes
+        # take advantage of that to exit and save results
+        except KeyboardInterrupt:
+            # if we get a ctrl-c / keyboard interrupt, stop looping
+            # and finish data collection to report on whatever was completed
+            break
+
+    # by default, collect data for the last step
+    # (scheduler is 1-based index but data collection is 0-based)
+    if data_collection_period == "end":
+        collect_steps = [model.schedule.steps - 1]
+    elif data_collection_period == "adjustment_round":
+        # when requested, collect data at every adjustment round
+        every_n = params.get("adjust_every", 10)
+        collect_steps = range(0, max_steps, every_n)
+    elif data_collection_period == "every_round":
+        collect_steps = range(0, max_steps)
+
+    # make a dict of run id and params for combination with model data
+    run_data = {"RunId": run_id, "iteration": iteration, "Step": "-"}
+    run_data.update(params)
+    all_model_data = []
+    all_agent_data = []
+
+    # collect data at the specified data collection points
+    for step in collect_steps:
+        try:
+            model_data, agent_data = _collect_data(model, step)
+            # preserve order: run, iteration, step, params first
+            # then data collection from model
+            model_run_data = run_data.copy()
+            model_run_data["Step"] = step
+            model_run_data.update(model_data)
+            all_model_data.append(model_run_data)
+
+            # add step to every agent data entry
+            agent_data = [
+                {
+                    "Step": step,
+                    **agent_data,
+                }
+                for agent_data in agent_data
+            ]
+            all_agent_data.extend(agent_data)
+        except IndexError:
+            # if we requested a step that isn't available, collect last round
+            # (should capture converged status)
+            model_data, agent_data = _collect_data(model, -1)
+            model_run_data = run_data.copy()
+            model_run_data["Step"] = step
+            model_run_data.update(model_data)
+            all_model_data.append(model_run_data)
+            # add step to every agent data entry
+            agent_data = [
+                {
+                    "Step": step,
+                    **agent_data,
+                }
+                for agent_data in agent_data
+            ]
+            all_agent_data.extend(agent_data)
+            break
+
+    # populate run id and iteration for every row of agent data
+    all_agent_data = [
+        {
+            "RunId": run_id,
+            "iteration": iteration,
+            **agent_data,
+        }
+        for agent_data in all_agent_data
+    ]
+
+    return all_model_data, all_agent_data
+
+
+def batch_run(
+    params,
+    iterations,
+    number_processes,
+    max_steps,
+    progressbar,
+    collect_agent_data,
+    file_prefix,
+    max_runs,
+    param_choice,
+    data_collection_period,
+):
+    run_params = params.get(param_choice)
+
+    param_combinations = _make_model_kwargs(run_params)
+    total_param_combinations = len(param_combinations)
+    total_runs = total_param_combinations * iterations
+    print(
+        f"{total_param_combinations} parameter combinations, "
+        + f"{iterations} iteration{'s' if iterations != 1 else ''}, "
+        + f"{total_runs} total runs"
+    )
+
+    # create a list of all the parameters to run, with run id and iteration
+    runs_list = []
+    run_id = 0
+    for params in param_combinations:
+        for iteration in range(iterations):
+            runs_list.append(
+                (run_id, iteration, params, max_steps, data_collection_period)
+            )
+            run_id += 1
+
+    # if maximum runs is specified, truncate the list of run arguments
+    if max_runs:
+        runs_list = runs_list[:max_runs]
+
+    # collect data in a directory for this model
+    data_dir = os.path.join("data", "hawkdovemulti")
+    os.makedirs(data_dir, exist_ok=True)
+    datestr = datetime.today().isoformat().replace(".", "_").replace(":", "")
+    model_output_filename = os.path.join(data_dir, f"{file_prefix}{datestr}_model.csv")
+    if collect_agent_data:
+        agent_output_filename = os.path.join(
+            data_dir, f"{file_prefix}{datestr}_agent.csv"
+        )
+
+    message = f"Saving data collection results to:\n  {model_output_filename}"
+    if collect_agent_data:
+        message += f"\n  {agent_output_filename}"
+    print(message)
+
+    # open output files so data can be written as it is generated
+    with open(model_output_filename, "w", newline="") as model_output_file:
+        if collect_agent_data:
+            agent_output_file = open(agent_output_filename, "w", newline="")
+
+        model_dict_writer = None
+        agent_dict_writer = None
+
+        # adapted from mesa batch run code
+        with tqdm(total=total_runs, disable=not progressbar) as pbar:
+            with multiprocessing.Pool(number_processes) as pool:
+                for model_data, agent_data in pool.imap_unordered(
+                    run_hawkdovemulti_model, runs_list
+                ):
+                    # initialize dictwriter and start csv after the first batch
+                    if model_dict_writer is None:
+                        # get field names from first entry
+                        model_dict_writer = csv.DictWriter(
+                            model_output_file, model_data[0].keys()
+                        )
+                        model_dict_writer.writeheader()
+
+                    model_dict_writer.writerows(model_data)
+
+                    if collect_agent_data:
+                        if agent_dict_writer is None:
+                            # get field names from first entry
+                            agent_dict_writer = csv.DictWriter(
+                                agent_output_file, agent_data[0].keys()
+                            )
+                            agent_dict_writer.writeheader()
+
+                        agent_dict_writer.writerows(agent_data)
+
+                    pbar.update()
+
+        if collect_agent_data:
+            agent_output_file.close()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="hawk/dove batch_run",
+        description="Batch run for hawk/dove multiple risk attitude simulation.",
+        epilog="""Data files will be created in data/hawkdovemulti/
+        relative to current path.""",
+    )
+    parser.add_argument(
+        "-i",
+        "--iterations",
+        type=int,
+        help="Number of iterations to run for each set of parameters "
+        + "(default: %(default)s)",
+        default=100,
+    )
+    parser.add_argument(
+        "-m",
+        "--max-steps",
+        help="Maximum steps to run simulations if they have not already "
+        + "converged (default: %(default)s)",
+        default=1000,  # new convergence logic seems to converge around 400
+        type=int,
+    )
+    parser.add_argument(
+        "-p",
+        "--processes",
+        type=int,
+        help="Number of processes to use (default: all available CPUs)",
+        default=None,
+    )
+    parser.add_argument(
+        "--progress",
+        help="Display progress bar",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+    )
+    parser.add_argument(
+        "--agent-data",
+        help="Store agent data",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+    )
+    parser.add_argument(
+        "--file-prefix",
+        help="Prefix for data filenames (no prefix by default)",
+        default="",
+    )
+    parser.add_argument(
+        "--max-runs",
+        help="Stop after the specified number of runs "
+        + "(for development/troubleshooting)",
+        type=int,
+        default=None,
+    )
+    parser.add_argument(
+        "--params",
+        help="Run a specific set of parameters",
+        choices=params.keys(),
+        default="default",
+    )
+    parser.add_argument(
+        "--collect-data",
+        help="When and how often to collect model and agent data",
+        choices=["end", "adjustment_round", "every_round"],
+        default="end",
+    )
+    args = parser.parse_args()
+    batch_run(
+        params,
+        args.iterations,
+        args.processes,
+        args.max_steps,
+        args.progress,
+        args.agent_data,
+        args.file_prefix,
+        args.max_runs,
+        args.params,
+        args.collect_data,
+    )
+
+
+if __name__ == "__main__":
+    main()