# Data simulator

> Create a live, parameterized what-if simulation: a runnable model the user drives with sliders and play/scrub controls, every output recomputing as they move.

Source: https://mockflow.com/developers/reference/item-types/data-simulator

Send `"type": "data_simulator"`.

Create a live, parameterized what-if simulation: a runnable model the user drives with sliders and play/scrub controls, every output recomputing as they move. Use this for business models (growth, churn, revenue, unit economics), funnels with conversion rates, forecasts and projections, capacity/queue models, epidemic/population dynamics, financial models (compound interest, runway), sensitivity/what-if analysis, and data infographics (metric cards, charts, gauges and funnels composed around one topic). Use this INSTEAD of a chart or table whenever the point is to explore how outcomes CHANGE as the inputs change over time.

Also available as the MCP tool `render_datasimulator`. The same payload works through either surface.

### Fields

- `title` (string): Short title of the simulation
- `description` (string): One short sentence describing what it models
- `seed` (number): Random seed so stochastic runs replay identically (default 42)
- `time` (object): Simulation horizon
    - `steps` (number): Number of steps to run (1-1000)
  - `unit` (string): Name of one step, e.g. month, day, week, year
- `layout` (object): Dashboard grid layout
    - `columns` (number): Grid density, 2-6
  - `controls` (enum<string>): Where the what-if control panel docks. One of `right`, `left` or `bottom`.
- `parameters` (object[]): The user's what-if levers, rendered as live controls. Each must be read by at least one rule, derived expression or view.
    - `id` (string, required): Unique id, referenced by expressions
  - `label` (string, required): Human label shown on the control
  - `control` (enum<string>, required): One of `slider`, `knob`, `number`, `select`, `toggle`, `stepper` or `segmented`.
  - `min` (number)
  - `max` (number)
  - `step` (number)
  - `value` (number, required): Default value
  - `format` (enum<string>): One of `number`, `integer`, `percent` or `currency`.
  - `options` (object[]): For select/segmented: [{ label, value }]
  - `group` (string): Optional heading clustering related controls
- `state` (object[], required): The evolving model variables. init is the step-0 value (a number, or a parameter-id expression string).
    - `id` (string, required)
  - `label` (string)
  - `init` (any, required): Starting value: a number or an expression string
  - `format` (enum<string>): One of `number`, `integer`, `percent` or `currency`.
- `rules` (object[]): Run once per step in order; each assigns expr to a state id (target). t is 1..steps.
    - `target` (string, required): A state id
  - `expr` (string, required): Expression evaluated each step
- `derived` (object[]): Recomputed from state and parameters after the rules each step (cannot accumulate across steps).
    - `id` (string, required)
  - `label` (string)
  - `expr` (string, required)
  - `format` (enum<string>): One of `number`, `integer`, `percent` or `currency`.
- `views` (object[], required): Dashboard tiles. CRITICAL: each view type binds to its data through a SPECIFIC field, and a view with the wrong field (or no binding field) renders as 0. Use exactly: metric/sparkline/progress/gauge -> "value" (a single id); progress also "target"; gauge also "min"/"max"/"thresholds". table -> "columns" (array of ids). funnel -> "stages". line/area/bar/pie/doughnut/compare/radar -> "series" (array of ids). scatter -> "x" and "y". sensitivity -> "parameter" and "metric". distribution -> "metric". mapregions -> "regions"; mappoints -> "points". text -> "content" (and optional "variant"). Do NOT put a single value under "series", and never leave a view without its binding field.
    - `type` (enum<string>, required)
  - `title` (string)
  - `span` (number): 1..columns grid width
  - `tall` (boolean)
  - `value` (string): metric/sparkline/progress/gauge: the SINGLE state/derived/parameter id this tile shows
  - `series` (any[]): line/area/bar/pie/doughnut/compare/radar: ids to plot; an entry is an id string or { id, as: "line"|"bar" }
  - `columns` (string[]): table: the ids to show one column each
  - `stages` (object[]): funnel: [{ label, value }] stage bars
  - `target` (any): progress: the goal, a number or another id
  - `min` (number): gauge: dial minimum
  - `max` (number): gauge: dial maximum
  - `thresholds` (number[]): gauge: [greenUpTo, amberUpTo] in the value's units
  - `stacked` (boolean): line/area/bar: stack the series
  - `horizontal` (boolean): compare: horizontal bars
  - `x` (string): scatter: the x-axis series id
  - `y` (string): scatter: the y-axis series id
  - `parameter` (string): sensitivity: the parameter id to sweep
  - `metric` (string): sensitivity/distribution: the id whose final value is measured
  - `samples` (number): sensitivity: number of sweep points
  - `runs` (number): distribution: number of seeded runs
  - `regions` (object[]): mapregions: [{ region, value }]
  - `points` (object[]): mappoints: [{ label, lat, lng, value }]
  - `level` (string): mapregions: "country" | "state"
  - `ramp` (string): mapregions: color ramp name
  - `content` (string): text: the copy to show
  - `variant` (string): text: "heading" | "note"

## Example

```json
{
  "type": "data_simulator",
  "data": {
    "title": "Q4 Launch Planning",
    "description": "string",
    "seed": 0,
    "time": {
      "steps": 0,
      "unit": "string"
    },
    "layout": {
      "columns": 0,
      "controls": "right"
    },
    "parameters": [
      {
        "id": "string",
        "label": "string",
        "control": "slider",
        "min": 0,
        "max": 0,
        "step": 0,
        "value": 0,
        "format": "number",
        "options": [
          {}
        ],
        "group": "string"
      }
    ],
    "state": [
      {
        "id": "string",
        "label": "string",
        "init": "string",
        "format": "number"
      }
    ],
    "views": [
      {
        "type": "line",
        "title": "Q4 Launch Planning",
        "span": 0,
        "tall": false,
        "value": "string",
        "series": [
          "string"
        ],
        "columns": [
          "string"
        ]
      }
    ]
  }
}
```