grocery-sim

A structural microsimulation of a small neighborhood grocery store, with a fully known causal ground truth

What this is

grocery-sim generates one or three years of a small grocery store’s full paper trail (receipts, invoices, a ledger, a tax filing) from a simulated economy of customers, an owner, and scripted macro shocks, not from sampled distributions. Every number has a traceable, documented cause.

  • Real ground truth. Every figure is the output of a specific, documented decision or shock, gradeable against a hidden answer key. See Checking ground truth for how that actually works, and every hidden table this package ships.
  • Exact counterfactuals. Every random draw is keyed by identity, so deleting one scripted event and replaying the world gives the exact causal effect of that event, not an estimate of it.
  • A generated business-case brief. Every run also produces a client: an owner, a letter, an intake interview, built entirely from that run’s own settings and results. See a real one in the API reference or a worked case.
  • Realistic, gradeable mess. Ten paperwork-defect families (duplicate invoices, missing deliveries, mis-typed counts, …) planted at low rates, each logged to a hidden answer key.
  • A 62-question analysis catalog, from data cleaning through causal inference, prediction, prescription, and policy experiments.

How to start

In a terminal:

pip install grocery-sim

In a Python script or notebook:

from grocery_sim import GroceryStoreSimulation

sim = GroceryStoreSimulation()
sim.setup(dict(
    basic = dict(
        name = "My Grocery Store",
        random_seed = 42,
        year = 3,
        budget = 60_000,
    ),
    events = dict(
        competitor = "2026-06-01",
        typhoon = "2025-07-15",
    ),
    potential_investment = dict(
        bigger_store = True,
    ),
))
sim.simulate()

sim.data()           # in-memory tables (receipts, invoices, ledger, ...)
sim.db()             # the same tables behind a DuckDB connection
sim.erd()            # a Mermaid ER diagram of this run's schema
sim.describe()       # a generated business-case brief for this run

sim.setup({}) (or any partial dict) works too, every key not mentioned falls back to its default. See the API reference for every setting sim.setup() accepts, with a full example.

Where to go from here

  • Theory: the intuition behind the construction, why the world is split into decisions and scripts, and why that split is what lets a counterfactual be exactly true instead of merely estimated.
  • Complete DGP: the full causal graph behind every generated run, drawn whole, from the scripted macro layer down to the paperwork an analyst actually receives.
  • API reference: every public method, with real signatures, parameters, and output.
  • Analysis catalog: the layered set of questions this data is built to answer, from cleaning the paperwork through structural, causal, and predictive modeling.
  • Checking ground truth: how grading actually works, in code, and a full reference of every hidden table this package ships.
  • Exemplar analyses: worked examples on real generated arms, added over time.