simulatingrisk 1.0.0__tar.gz → 1.1.0__tar.gz

{simulatingrisk-1.0.0 → simulatingrisk-1.1.0}/.github/workflows/unit_tests.yml

@@ -4,6 +4,20 @@ on:
   push: # run on every push or PR to any branch
   pull_request:
 
+permissions:
+  contents: read
+
+concurrency:
+  # Cancel existing job(s) for workflow when a new one is queued
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Prevent uv from including develop dependencies by default
+  UV_NO_DEV: 1
+  # Prevent uv run from syncing by default
+  UV_NO_SYNC: 1
+
 jobs:
   python-unit:
     name: Python unit tests
@@ -11,33 +25,22 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
-          python-version: 3.12
+          persist-credentials: false
 
-      # base the python cache on the hash of all pyproject.toml,
-      # which includes python requirements.
-      # if any change, the cache is invalidated.
-      - name: Cache pip
-        uses: actions/cache@v4
-        with:
-          path: ~/.cache/pip
-          key: pip-${{ hashFiles('pyproject.toml') }}
-          restore-keys: |
-            pip-${{ hashFiles('pyproject.toml') }}
-            pip-
+      - name: Install uv and Python version
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v.8.2.0
+        # pull version from .python-version file, currently 3.12
 
-      - name: Install dependencies
-        run: pip install ".[dev]"
+      - name: Install package dependencies, including test dependencies
+        run: uv sync --group test
 
       - name: Run pytest
-        run: pytest --cov=./ --cov-report=xml
+        run: uv run pytest --cov=./ --cov-report=xml
 
       - name: Upload test coverage to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
 
       # Set the color of the slack message used in the next step based on the
       # status of the build: "danger" for failure, "good" for success,
@@ -61,4 +64,4 @@ jobs:
           SLACK_TITLE: "Workflow `${{ github.workflow }}`: ${{ job.status }}"
           SLACK_MESSAGE: "Run <https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}|#${{ github.run_number }}> on <https://github.com/${{ github.repository }}/|${{ github.repository }}@${{ github.ref }}>"
           SLACK_FOOTER: "<https://github.com/${{ github.repository }}/commit/${{ github.sha }}|View commit>"
-          MSG_MINIMAL: true  # use compact slack message format
+          MSG_MINIMAL: true # use compact slack message format

simulatingrisk-1.1.0/.justfile

@@ -0,0 +1,16 @@
+# justfile for building and serving notebooks as local html
+set default-list := true
+
+# TODO: may need base url option with exports to run properly on github pages
+
+# Export marimo app and analysis notebooks to html docs
+docs:
+    @echo "Exporting app ui to html-wasm in docs/sim/"
+    uv run marimo --quiet export html-wasm simulatingrisk/app.py -o docs/sim/ --mode run --no-sandbox --force
+
+#uv run marimo export html notebooks/evolv/convergence.py -o docs/analysis/evolve/convergence.html
+
+# serve documentation locally for dev/
+serve-docs:
+    @echo "Serving docs/ at http://localhost:8000/"
+    python -m http.server --directory docs/

simulatingrisk-1.1.0/.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+  # Ruff Python linter and formatter (configs in pyproject.toml)
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: 22f0422809455ec89ffdcf5a00170ba816e42ddb # frozen: v0.15.16
+    hooks:
+      # Run the linter
+      - id: ruff-check
+        args: [--fix, --show-fixes] # enable lint fixes
+      # Run the formatter
+      - id: ruff-format

simulatingrisk-1.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# 1.1.0 - 2026-07-10
+
+Updates to support the paper "Playing Risky Games."
+
+Changes that affect both versions of the Hawk/Dove model:
+
+- Revise default random play odds to 0.1 ; add to default batch run parameters
+- Add boolean parameter to control whether to include extreme risk-attitudes 0 and 9 (`include_endpoints`, default is True)
+- Add `include_endpoints` parameter to interactive simulation controls
+- Update labels and legends in the interactive simulation and analysis notebooks to match language in the paper.
+- Add a marimo notebook to serve as the interface for running the Hawk/Dove simulation interactively; supports export to html+wasm for publication via static site.
+
+Model-specific changes:
+
+## Sim 1. Multiple Risk-Attiudes (no adjustment)
+
+- Significance testing for payoff results from previous batch run data
+- Set minimum number of rounds to 50 before checking for convergence
+
+## Sim 2. Evolving Risk-Attiudes (with adjustment)
+
+- Tie-breaker: chose randomly when there is a tie for best payoff when selecting neighbor to emulate
+- Set minimum number of rounds to 300 before checking for convergence
+- Improved logic for sum of agents with changed risk attitudes in the last adjustment round (part of convergence check)
+
+## Improvements to custom batch run script
+
+- Improve multiprocessing logic
+  - Add a timeout on the wait so main loop doesn't wait forever
+  - Cycle workers to avoid memory leaks on long runs
+- Shift data collection schedule logic to the model: only collect data needed for convergence checks and requested reporting (agent data optional; end of round or adjustment rounds only)
+
+## Miscellaneous
+
+- Jupyter notebooks from prior analysis have been moved to `notebooks/archive/`
+- Static html exports from jupyter notebooks have to `docs/analysis/prev/`

simulatingrisk-1.1.0/CITATION.cff

@@ -0,0 +1,35 @@
+# This CITATION.cff file was generated doi2cff, updated with cffinit.
+cff-version: 1.2.0
+title: simulating-risk v1.0
+message: >-
+  If you use this software, please cite it using these
+  metadata.
+type: software
+authors:
+  - given-names: Rebecca Sutton
+    family-names: Koeser
+    affiliation: Princeton University
+    orcid: 'https://orcid.org/0000-0002-8762-8057'
+  - given-names: Lara
+    family-names: Buchak
+    affiliation: Princeton University
+    orcid: 'https://orcid.org/0000-0002-0232-4274'
+repository-code: 'https://github.com/Princeton-CDH/simulating-risk'
+url: 'https://cdh.princeton.edu/projects/simulating-risk/'
+abstract: >-
+  Code associated with the "Simulating risk, risking
+  simulations" led by Lara Buchak, supported by the Center
+  for Digital Humanities at Princeton University
+  Simulations are implemented in the Mesa Framework, using
+  Agent Based Modeling to explore risk attitudes within
+  populations.
+keywords:
+  - Computer Simulation
+  - Decision Theory
+  - Game Theory
+  - Risk Attitudes
+  - Risk-Weighted Expected Utility
+license: Apache-2.0
+version: '1.0'
+date-released: '2026-01-24'
+doi: 10.5281/zenodo.18361157

{simulatingrisk-1.0.0 → simulatingrisk-1.1.0}/PKG-INFO

@@ -1,54 +1,40 @@
 Metadata-Version: 2.4
 Name: simulatingrisk
-Version: 1.0.0
+Version: 1.1.0
 Summary: Agent-based modeling for simulations related to risk and rationality
 License: Apache-2
 Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.7
-Description-Content-Type: text/x-rst
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mesa==2.1.5
-Requires-Dist: matplotlib
-Requires-Dist: altair>5.0.1
-Provides-Extra: dev
-Requires-Dist: pre-commit; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Provides-Extra: analysis
-Requires-Dist: jupyterlab; extra == "analysis"
-Requires-Dist: polars; extra == "analysis"
-Requires-Dist: hvplot; extra == "analysis"
-Requires-Dist: pyarrow; extra == "analysis"
-Requires-Dist: altair; extra == "analysis"
-Requires-Dist: scipy; extra == "analysis"
-Requires-Dist: scikit-learn; extra == "analysis"
-Requires-Dist: seaborn; extra == "analysis"
-Requires-Dist: vegafusion[embed]>=1.5.0; extra == "analysis"
-Requires-Dist: vl-convert-python; extra == "analysis"
-Requires-Dist: great-tables; extra == "analysis"
+Requires-Dist: altair>=6.0
+Requires-Dist: marimo>=0.23.11
 Dynamic: license-file
 
 # Simulating Risk
 
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18361156.svg)](https://doi.org/10.5281/zenodo.18361156)
 [![DH community code review: June 2024](https://img.shields.io/badge/DHCodeReview-June_2024-blue)](https://github.com/DHCodeReview/simulating-risk/pull/1) [![unit tests](https://github.com/Princeton-CDH/simulating-risk/actions/workflows/unit_tests.yml/badge.svg)](https://github.com/Princeton-CDH/simulating-risk/actions/workflows/unit_tests.yml)
 
 The code in this repository is associated with the CDH project [Simulating risk, risking simulations](https://cdh.princeton.edu/projects/simulating-risk/).
 
 Simulations are implemented with [Mesa](https://mesa.readthedocs.io/en/stable/), using Agent Based Modeling to explore risk attitudes within populations.
 
----- 
+---
 
-## Simulations with agent interaction
+## Simulations with risk attitudes and agent interaction
 
 - [Hawk/Dove with risk attitudes](simulatingrisk/hawkdove)
 - [Hawk/Dove with multiple risk attitudes and adjustment](simulatingrisk/hawkdovemulti)
 
-The code for **Hawk/Dove with risk attitudes** and **Hawk/Dove with multiple risk attitudes** in this codebase was [reviewed](https://github.com/DHCodeReview/simulating-risk/pull/1) in June 2024 by [Scott Foster](https://github.com/sgfost) and [Malte Vogl](https://github.com/maltevogl) (Senior Research Fellow, Max Planck Institute of Geoanthropology) via [DHTech Community Code Review](https://dhcodereview.github.io/); review was faciliated by [Cole Crawford](https://github.com/ColeDCrawford) (Senior Software Engineer, Harvard Arts and Humanities Research Computing).
+> [!TIP]  
+> Run an interactive version of the simulation online: [Hawk/Dove with multiple risk attitudes](https://py.cafe/rlskoeser/simulatingrisk-hawk-dove-multirisk)
 
+> [!NOTE]
+> Altenately, run the simulation in a Jupyter notebook: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Princeton-CDH/simulating-risk.git/HEAD?urlpath=%2Fdoc%2Ftree%2Fsimulatingrisk%2Fhawkdovemulti%2Frun_simulation.ipynb)
 
-View an interactive version of the [Hawk/Dove with multiple risk attitudes](https://py.cafe/rlskoeser/simulatingrisk-hawk-dove-multirisk) simulation online.
-
-The simulation can also be run in a Jupyter notebook: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Princeton-CDH/simulating-risk.git/HEAD?urlpath=%2Fdoc%2Ftree%2Fsimulatingrisk%2Fhawkdovemulti%2Frun_simulation.ipynb)
+The code for **Hawk/Dove with risk attitudes** and **Hawk/Dove with multiple risk attitudes** in this codebase was [reviewed](https://github.com/DHCodeReview/simulating-risk/pull/1) in June 2024 by [Scott Foster](https://github.com/sgfost) and [Malte Vogl](https://github.com/maltevogl) (Senior Research Fellow, Max Planck Institute of Geoanthropology) via [DHTech Community Code Review](https://dhcodereview.github.io/); review was facilitated by [Cole Crawford](https://github.com/ColeDCrawford) (Senior Software Engineer, Harvard Arts and Humanities Research Computing).
 
 ## Simulations with risky choices (environment)
 
@@ -61,53 +47,91 @@ Across simulations, we define agents with risk attitudes tracked via a numeric `
 
 When the risky bet might be better or worse than the safe bet by the same amount (for example, the risky bet yields 3 or 1 and the safe bet yields 2), an agent who maximizes expected utility will prefer the risky bet when p > 0.5 and will prefer the safe bet when 'p < 0.5'; and they will be indifferent between the risky bet and the safe bet. Thus, r = 0.5 corresponds to expected utility maximization except in the case in which the probability is exactly 0.5 (or, we might say, a point epsilon units to the left of 0.5, where epsilon is smaller than the fineness of our random number generator, corresponds to expected utility maximization). These complications make no difference in practice, so we can simply say that r = 0.5 corresponds to expected utility maximization.
 
+```mermaid
+---
+title: risk attitude / risk level (for probabilistic choices)
+---
+flowchart LR
+    r0["<b>0.0</b>
+always takes risky choice
+(any risk is acceptable)"]
+    reu["<b>0.5</b>
+risk neutral
+(expected utility maximizer)"]
+    r1["<b>1.0</b>
+always takes safe choice
+(no risk is acceptable)"]
+    r0 ---|risk seeking|reu---|risk averse|r1
+```
 
 ## Development instructions
 
 Initial setup and installation:
 
-- *Recommmended*: create and activate a Python 3.12 virtualenv:
+- _Recommmended_: use [`uv`](https://docs.astral.sh/uv/) to create a Python 3.12 virtualenv and install dependencies, including development dependencies:
 
 ```sh
-python3 -m venv simrisk
-source simrisk/bin/activate
+uv sync
 ```
 
-- Install the package, dependencies, and development dependencies:
+### Install pre-commit hooks
+
+Install pre-commit hooks (currently [black](https://github.com/psf/black) and [ruff](https://beta.ruff.rs/docs/)):
 
 ```sh
-pip install -e .
-pip install -e ".[dev]"
+pre-commit install
 ```
 
-To run the Solara app with tabs for all simulations that are available as Solara apps:
+### Interactive interface to the simulations
+
+We use a marimo notebook as the interface for running the Hawk/Dove simulation interactively. To run locally for development, using
+the local development environment, run with sandbox disabled:
+
 ```sh
-solara run simulatingrisk/app.py
+uv run marimo edit simulatingrisk/app.py --no-sandbox
 ```
 
-To run a single simulation, run Solara with the model-specific app file:
+For publication via static site, this notebook should be saved as html + web assembly. This requires a version of the `simulatingrisk` package that can be installed in pyodide, either by a published version on pypi or a local wheel for testing.
+
+To export as html+wasm in edit mode, to debug any wasm-specific problems:
+
 ```sh
-solara run simulatingrisk/hawkdovemulti/app.py
+uv run marimo export html-wasm simulatingrisk/app.py -o docs/sim/ --mode edit
 ```
 
-An interactive version of the [Solara app with tabs for all simulations](https://py.cafe/app/rlskoeser/simulatingrisk) 
-is available online.
+For convenience, a `.justfile` is included for building documentation and serving locally. Requires [just](https://github.com/casey/just) version 1.52 or newer.
 
+With `just` installed, run the following to build the documentation and serve it locally:
 
-### Running the simulations  (non-solara versions)
+````sh
+just docs
+just serve-docs
+```
 
-- Simulations can be run interactively with mesa runserver by specifying
-  the path to the model, e.g. `mesa runserver simulatingrisk/risky_bet/`
-  Refer to the readme for each model for more details.
-- Simulations can be run in batches to aggregate data across multiple
-  runs and different parameters. For example,
-  `./simulatingrisk/batch_run.py riskyfood`
-  
-  
-### Install pre-commit hooks
+That is equivalent to running the following commands. To export manually in run mode:
 
-Install pre-commit hooks (currently [black](https://github.com/psf/black) and [ruff](https://beta.ruff.rs/docs/)):
+```sh
+uv run marimo export html-wasm simulatingrisk/app.py -o docs/sim/ --mode run --no-sandbox -f
+````
+
+To view locally, start a python webserver:
 
 ```sh
-pre-commit install
+python -m http.server --directory docs/
+```
+
+The interacvite simulation will be available at http://localhost:8000/sim/
+
+For testing the html+wasm application notebook with a local version of the simrisk code (notebook must be updated
+to install simulatingrisk from the wheel).
+
+```sh
+uv build --wheel -o docs/sim/
+uv run marimo export html-wasm simulatingrisk/app.py --mode edit -o docs/sim/ --no-sandbox -f
+```
+
+To export static html copies of analysis notebooks:
+
+```sh
+uv run marimo export html notebooks/evolv-risk-attitudes/convergence.py -o docs/analysis/evolve/index.html
 ```

simulatingrisk-1.1.0/README.md

@@ -0,0 +1,123 @@
+# Simulating Risk
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18361156.svg)](https://doi.org/10.5281/zenodo.18361156)
+[![DH community code review: June 2024](https://img.shields.io/badge/DHCodeReview-June_2024-blue)](https://github.com/DHCodeReview/simulating-risk/pull/1) [![unit tests](https://github.com/Princeton-CDH/simulating-risk/actions/workflows/unit_tests.yml/badge.svg)](https://github.com/Princeton-CDH/simulating-risk/actions/workflows/unit_tests.yml)
+
+The code in this repository is associated with the CDH project [Simulating risk, risking simulations](https://cdh.princeton.edu/projects/simulating-risk/).
+
+Simulations are implemented with [Mesa](https://mesa.readthedocs.io/en/stable/), using Agent Based Modeling to explore risk attitudes within populations.
+
+---
+
+## Simulations with risk attitudes and agent interaction
+
+- [Hawk/Dove with risk attitudes](simulatingrisk/hawkdove)
+- [Hawk/Dove with multiple risk attitudes and adjustment](simulatingrisk/hawkdovemulti)
+
+> [!TIP]  
+> Run an interactive version of the simulation online: [Hawk/Dove with multiple risk attitudes](https://py.cafe/rlskoeser/simulatingrisk-hawk-dove-multirisk)
+
+> [!NOTE]
+> Altenately, run the simulation in a Jupyter notebook: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Princeton-CDH/simulating-risk.git/HEAD?urlpath=%2Fdoc%2Ftree%2Fsimulatingrisk%2Fhawkdovemulti%2Frun_simulation.ipynb)
+
+The code for **Hawk/Dove with risk attitudes** and **Hawk/Dove with multiple risk attitudes** in this codebase was [reviewed](https://github.com/DHCodeReview/simulating-risk/pull/1) in June 2024 by [Scott Foster](https://github.com/sgfost) and [Malte Vogl](https://github.com/maltevogl) (Senior Research Fellow, Max Planck Institute of Geoanthropology) via [DHTech Community Code Review](https://dhcodereview.github.io/); review was facilitated by [Cole Crawford](https://github.com/ColeDCrawford) (Senior Software Engineer, Harvard Arts and Humanities Research Computing).
+
+## Simulations with risky choices (environment)
+
+- [Risky Food](simulatingrisk/risky_food)
+- [Risky Bet](simulatingrisk/risky_bet)
+
+## Risk attitude definitions
+
+Across simulations, we define agents with risk attitudes tracked via a numeric `r` or `risk_level` 0.0 - 1.0, where `r` is that agent's minimum acceptable risk level for taking the risky bet. When the probability 'p' of the risky bet paying off is greater than an agent's 'r', that agent will take the bet. An agent with `r=1` will always take the safe option (no risk is acceptable); an agent with `r=0` will always take the risky choice (any risk is acceptable). Notice that the agent is never indifferent; allowing indifference would require introducing a tie-breaking rule, which would be a further parameter.
+
+When the risky bet might be better or worse than the safe bet by the same amount (for example, the risky bet yields 3 or 1 and the safe bet yields 2), an agent who maximizes expected utility will prefer the risky bet when p > 0.5 and will prefer the safe bet when 'p < 0.5'; and they will be indifferent between the risky bet and the safe bet. Thus, r = 0.5 corresponds to expected utility maximization except in the case in which the probability is exactly 0.5 (or, we might say, a point epsilon units to the left of 0.5, where epsilon is smaller than the fineness of our random number generator, corresponds to expected utility maximization). These complications make no difference in practice, so we can simply say that r = 0.5 corresponds to expected utility maximization.
+
+```mermaid
+---
+title: risk attitude / risk level (for probabilistic choices)
+---
+flowchart LR
+    r0["<b>0.0</b>
+always takes risky choice
+(any risk is acceptable)"]
+    reu["<b>0.5</b>
+risk neutral
+(expected utility maximizer)"]
+    r1["<b>1.0</b>
+always takes safe choice
+(no risk is acceptable)"]
+    r0 ---|risk seeking|reu---|risk averse|r1
+```
+
+## Development instructions
+
+Initial setup and installation:
+
+- _Recommmended_: use [`uv`](https://docs.astral.sh/uv/) to create a Python 3.12 virtualenv and install dependencies, including development dependencies:
+
+```sh
+uv sync
+```
+
+### Install pre-commit hooks
+
+Install pre-commit hooks (currently [black](https://github.com/psf/black) and [ruff](https://beta.ruff.rs/docs/)):
+
+```sh
+pre-commit install
+```
+
+### Interactive interface to the simulations
+
+We use a marimo notebook as the interface for running the Hawk/Dove simulation interactively. To run locally for development, using
+the local development environment, run with sandbox disabled:
+
+```sh
+uv run marimo edit simulatingrisk/app.py --no-sandbox
+```
+
+For publication via static site, this notebook should be saved as html + web assembly. This requires a version of the `simulatingrisk` package that can be installed in pyodide, either by a published version on pypi or a local wheel for testing.
+
+To export as html+wasm in edit mode, to debug any wasm-specific problems:
+
+```sh
+uv run marimo export html-wasm simulatingrisk/app.py -o docs/sim/ --mode edit
+```
+
+For convenience, a `.justfile` is included for building documentation and serving locally. Requires [just](https://github.com/casey/just) version 1.52 or newer.
+
+With `just` installed, run the following to build the documentation and serve it locally:
+
+````sh
+just docs
+just serve-docs
+```
+
+That is equivalent to running the following commands. To export manually in run mode:
+
+```sh
+uv run marimo export html-wasm simulatingrisk/app.py -o docs/sim/ --mode run --no-sandbox -f
+````
+
+To view locally, start a python webserver:
+
+```sh
+python -m http.server --directory docs/
+```
+
+The interacvite simulation will be available at http://localhost:8000/sim/
+
+For testing the html+wasm application notebook with a local version of the simrisk code (notebook must be updated
+to install simulatingrisk from the wheel).
+
+```sh
+uv build --wheel -o docs/sim/
+uv run marimo export html-wasm simulatingrisk/app.py --mode edit -o docs/sim/ --no-sandbox -f
+```
+
+To export static html copies of analysis notebooks:
+
+```sh
+uv run marimo export html notebooks/evolv-risk-attitudes/convergence.py -o docs/analysis/evolve/index.html
+```