Skip to content
WHATIFOpen demo
All guides

Guide 01 / Start here

Run your first comparison

A useful simulation starts with a specific question: what changes under this intervention, compared with an explicit baseline? This guide takes you from the public demo to a project of your own, without treating a synthetic result as a prediction about real people.

What you will do

You will know how to access the demo, prepare your own project, and read the first baseline/intervention comparison.

Before you start

  • A running WhatIf installation, either your own checkout or one an operator has configured.
  • An account for creating projects and running your own scenarios. The basic demo overview is public; prepared private source and individual evidence requires the seeded owner session.
  • A concrete decision and a baseline you can describe before changing any inputs.

Step / 01

Tour the guided sample workspace

Open demo and select Demo — Decision laboratory, marked Guided sample workspace. Its normal project overview has a Sample workspace marker and a Choose your simulation workflow section. The prepared examples cover data foundations, paired runs, and evidence inspection through the regular product tools.

Explore the main household FX shock and a gentler shock on the same households, isolated FX-price calibration with holdout, and full-detail workplace, economy, flood, and health mechanisms. The basic product-price example includes agent/event inspection. Their artificial values and declared source context are part of the experiment, not customer outcomes.

The demo project overview is publicly readable. Reviewed source, household, calibration, and modular evidence requires the seeded owner account; running or changing its examples requires that account too. Signing in with a different account does not grant ownership. In a local development checkout, the default seeded owner is demo@whatif.local with demo-password, unless the operator changed those values. These are development defaults, not credentials for an arbitrary hosted installation.

With the seeded owner session, open a prepared household FX report and start with Aggregate outcomes. Choose Individuals and events to inspect retained household/member records, then Inputs and evidence to check source and replay context. Open a modular report to follow entity, account, and event evidence. The calibration example separates fitting and held-out assessment. These are normal product views, so the route from summary to evidence is the same for your own experiment.

After signing in with your own account, create your own project from the projects page. Its private workflows and evidence belong to that account. Public sample read access does not grant access to another owner’s private inputs or authorize mutations.

Step / 02

Choose the right starting point

Use Choose your simulation workflow in the project overview. Household and FX connects reviewed household records, explicit prices and resources, and a compatible world. Modular mechanisms uses reviewed workplace, economy, public-policy, flood, or contact-health modules with explicit entities, accounts, and resources. Product-price scenarios uses the separate legacy synthetic-agent path.

A project is a place to organize inputs and experiments; creating it or uploading data does not automatically attach that data to a run. Reviewed preparation selects compatible source mappings, population evidence, model versions, and scenario configuration. The legacy product-price path generates its own demo population rather than using uploaded household records.

  1. Name the question

    Write down the proposed change, who or what is represented, the units, the location, and the period. Decide which quantities you want to compare.

  2. Describe the baseline

    State what happens without the change. A baseline is an explicit continuation or supplied path, not an automatically inferred future.

  3. Review the inputs

    Identify which values are observed, generated, or assumed. Confirm the required assumptions and resolve blocked readiness diagnostics before running.

  4. Run and inspect

    Queue the reviewed scenario, watch its status, and inspect both arms. Keep input versions and evidence alongside the result so you can explain what was compared.

Step / 03

Run a local checkout

The repository README contains the complete installation instructions. Use the pinned Node/pnpm versions, Python 3.12 or newer, uv, and Docker Compose. Copy the example environment before first use, start the backing services, apply migrations, and seed the demo. The web app and queue worker run in separate terminals.

The default environment enables object storage. Start its Compose storage profile for historical data and the reviewed private workflows. Calibration fitting additionally needs supported Linux Landlock and seccomp isolation. A Node-only web host cannot run the Python review and verification steps.

pnpm db:seed creates the base project and invokes pnpm demo:seed to prepare the varied sample evidence through the normal APIs and lease checks. Preparation runs synchronously and needs no web or background worker process. Full samples require configured private storage and supported calibration isolation. Without storage, the base seed remains and the command explains how to prepare the full set after storage becomes available; then run pnpm demo:seed.

From a prepared repository checkout
pnpm install --frozen-lockfile
uv sync --frozen
cp .env.example .env
docker compose -f infrastructure/docker/docker-compose.yml --profile storage up -d
pnpm db:migrate
# Base project + full samples when storage and isolation are available:
pnpm db:seed
# Separate terminals after preparation:
pnpm dev:next
pnpm dev:worker

Step / 04

Read the result before changing the scenario

Compare the baseline and intervention on matching metrics and periods. Inspect the distributions and paired differences, then read the assumptions, source scope, and any unavailable measures. A completed job tells you the declared calculation finished; it does not certify that the model is empirically valid.

If a run fails, inspect its recorded reason instead of interpreting missing results as zero. Private workflows can block when a source is unavailable, a required assumption is unconfirmed, or storage cannot publish verified evidence. Fix the input or runtime issue, review again, and create a new run.