plotagents 0.0.0-stage → 0.5.0

package/schema.json

@@ -0,0 +1,895 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/plotagents/schema.json",
+  "title": "plotagents spec",
+  "description": "Declarative chart spec. Data as rows (tidy) plus the field name for each role. Everything else has well-designed defaults.",
+  "type": "object",
+  "required": [
+    "data"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": [
+        "auto",
+        "bar",
+        "column",
+        "count",
+        "line",
+        "area",
+        "scatter",
+        "bubble",
+        "treemap",
+        "sunburst",
+        "donut",
+        "pie",
+        "heatmap",
+        "sankey",
+        "kpi",
+        "hist",
+        "kde",
+        "ecdf",
+        "regplot",
+        "residplot",
+        "jointplot",
+        "box",
+        "violin",
+        "strip",
+        "swarm",
+        "point",
+        "radar",
+        "network",
+        "chord",
+        "pyramid",
+        "flowchart",
+        "choropleth",
+        "symbolmap",
+        "barplot",
+        "countplot",
+        "columns",
+        "lineplot",
+        "areaplot",
+        "scatterplot",
+        "histplot",
+        "histogram",
+        "kdeplot",
+        "density",
+        "ecdfplot",
+        "lmplot",
+        "reg",
+        "regression",
+        "joint",
+        "boxplot",
+        "violinplot",
+        "stripplot",
+        "swarmplot",
+        "beeswarm",
+        "pointplot",
+        "spider",
+        "doughnut",
+        "graph",
+        "force",
+        "red",
+        "chord-diagram",
+        "cuerdas",
+        "populationpyramid",
+        "population",
+        "piramide",
+        "pirámide",
+        "flow",
+        "diagram",
+        "process",
+        "diagrama",
+        "map",
+        "mapa",
+        "choroplethmap",
+        "symbol",
+        "bubblemap",
+        "mapa-simbolos",
+        "tree",
+        "stat",
+        "stats",
+        "number",
+        "heat"
+      ],
+      "description": "Compare: bar, count. Time: line, area. Relationships: scatter, bubble, regplot, residplot, jointplot, radar. Distributions (seaborn): hist, kde, ecdf, box, violin, strip, swarm, point. Part-to-whole: treemap, sunburst, donut, pie. Other: heatmap, sankey, kpi. seaborn names are accepted (barplot, countplot, histplot, kdeplot, boxplot, violinplot, lmplot…). \"auto\" (default) picks from the data."
+    },
+    "data": {
+      "description": "Array of rows, e.g. [{ \"region\": \"Biobío\", \"sales\": 1240 }]. For kpi it can be omitted in favor of `items`.",
+      "anyOf": [
+        {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        },
+        {
+          "type": "object"
+        }
+      ]
+    },
+    "title": {
+      "type": "string",
+      "description": "The finding as a full sentence, ideally with the key number, e.g. \"Biobío accounts for 32% of sales\"."
+    },
+    "subtitle": {
+      "type": "string",
+      "description": "How to read the chart: measure, unit and period, e.g. \"Sales by region, CLP millions, 2025\"."
+    },
+    "source": {
+      "type": "string",
+      "description": "Data source, shown at the bottom right."
+    },
+    "locale": {
+      "type": "string",
+      "enum": [
+        "es",
+        "en"
+      ],
+      "description": "Language and number format. Default \"es\" (1.234,5); use \"en\" for 1,234.5."
+    },
+    "x": {
+      "type": "string",
+      "description": "x-axis or category field (bar, line, area, scatter, heatmap, box, violin…)."
+    },
+    "y": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ],
+      "description": "Value field. For line/bar a list of fields (wide table) turns each one into a series."
+    },
+    "series": {
+      "type": "string",
+      "description": "Field that splits the data into colored series. Alias: hue."
+    },
+    "hue": {
+      "type": "string",
+      "description": "Alias of series (seaborn naming)."
+    },
+    "value": {
+      "type": "string",
+      "description": "Value field for treemap, sunburst, donut, heatmap, sankey and radar."
+    },
+    "label": {
+      "type": "string",
+      "description": "Name field (treemap, donut, point labels in scatter/regplot)."
+    },
+    "group": {
+      "type": "string",
+      "description": "Level-1 group field for a two-level treemap (shortcut for path)."
+    },
+    "path": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Hierarchy for treemap/sunburst, any depth: [level1, level2, …]."
+    },
+    "size": {
+      "type": "string",
+      "description": "Bubble size field (area-proportional)."
+    },
+    "from": {
+      "type": "string",
+      "description": "Sankey source field."
+    },
+    "to": {
+      "type": "string",
+      "description": "Sankey target field."
+    },
+    "axis": {
+      "type": "string",
+      "description": "radar: field with the axis names (long format)."
+    },
+    "axes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "radar: fields to use as axes (wide format, one row per series)."
+    },
+    "items": {
+      "type": "array",
+      "description": "kpi: the indicators to show.",
+      "items": {
+        "type": "object",
+        "required": [
+          "label",
+          "value"
+        ],
+        "properties": {
+          "label": {
+            "type": "string"
+          },
+          "value": {
+            "type": "number"
+          },
+          "delta": {
+            "type": "number",
+            "description": "Relative change as a fraction (0.12 = +12%)."
+          },
+          "previous": {
+            "type": "number",
+            "description": "Previous value; when given, the change is computed."
+          },
+          "period": {
+            "type": "string",
+            "description": "What it is compared against, e.g. \"vs 2025\"."
+          },
+          "good": {
+            "type": "string",
+            "enum": [
+              "up",
+              "down"
+            ],
+            "description": "Whether going up is good (up) or bad (down, e.g. costs)."
+          },
+          "trend": {
+            "type": "array",
+            "items": {
+              "type": "number"
+            },
+            "description": "Short series for the sparkline."
+          },
+          "target": {
+            "type": "number",
+            "description": "Target: draws a progress meter."
+          },
+          "format": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "geo": {
+      "description": "choropleth/symbolmap: \"chile\" (16 regions, default), \"usa\" (50 states + DC, Albers with Alaska/Hawaii insets; Puerto Rico when it has data), \"world\" (countries), a name registered with registerGeo(), or a GeoJSON FeatureCollection.",
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object"
+        }
+      ]
+    },
+    "key": {
+      "type": "string",
+      "description": "choropleth/symbolmap: data field with the region, state or country name/code to match (US: \"TX\", \"Texas\", \"06\")."
+    },
+    "projection": {
+      "type": "string",
+      "enum": [
+        "mercator",
+        "equalEarth",
+        "albersUsa"
+      ],
+      "description": "choropleth/symbolmap: map projection (picked automatically)."
+    },
+    "values": {
+      "type": "boolean",
+      "description": "choropleth with state codes (usa): false shows only the codes, without values."
+    },
+    "featureKey": {
+      "type": "string",
+      "description": "choropleth: feature property to match against (default tries code, id, ISO-3, name and aliases)."
+    },
+    "midpoint": {
+      "type": "number",
+      "description": "choropleth/heatmap: diverging color scale around this value (e.g. 0 for changes)."
+    },
+    "classes": {
+      "type": "integer",
+      "description": "choropleth: number of color classes (default 5)."
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      },
+      "description": "network: node rows (id, group, size). flowchart: steps (id, label, type: start|end|process|decision|data|note, lane)."
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      },
+      "description": "flowchart: connections (from, to, label). Same as `data`."
+    },
+    "layout": {
+      "type": "string",
+      "enum": [
+        "force",
+        "circle"
+      ],
+      "description": "network layout."
+    },
+    "matrix": {
+      "type": "array",
+      "items": {
+        "type": "array",
+        "items": {
+          "type": "number"
+        }
+      },
+      "description": "chord: square flow matrix (with `names`)."
+    },
+    "names": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "chord: group names for `matrix`."
+    },
+    "directed": {
+      "type": "boolean",
+      "description": "chord: treat flows as directed (default false)."
+    },
+    "direction": {
+      "type": "string",
+      "enum": [
+        "TB",
+        "LR"
+      ],
+      "description": "flowchart: top-to-bottom or left-to-right (automatic by default)."
+    },
+    "age": {
+      "type": "string",
+      "description": "pyramid: age-group field."
+    },
+    "sex": {
+      "type": "string",
+      "description": "pyramid: field with exactly two sides (e.g. sex)."
+    },
+    "percent": {
+      "type": "boolean",
+      "description": "pyramid: show shares of the total population."
+    },
+    "facet": {
+      "type": "string",
+      "description": "One panel per value of this field (small multiples, seaborn col). Shared scales and colors."
+    },
+    "columns": {
+      "type": "integer",
+      "description": "facet: panels per row (seaborn col_wrap). Reduced automatically on narrow screens."
+    },
+    "sharey": {
+      "type": "boolean",
+      "description": "facet: same y scale in every panel (default true)."
+    },
+    "time": {
+      "type": "string",
+      "description": "Time field (d3plus-style): shows one period at a time (the latest by default) and, in the browser, a slider with play. Not used by line/area, which get a range slider."
+    },
+    "timeValue": {
+      "description": "Period to show when `time` is set."
+    },
+    "slider": {
+      "type": "boolean",
+      "description": "Browser: false removes the time slider (the chart shows `timeValue` or the latest period)."
+    },
+    "play": {
+      "type": "boolean",
+      "description": "Browser: false keeps the time slider but hides the play button."
+    },
+    "compare": {
+      "description": "With `time`: period to compute changes against: \"previous\" (default), \"first\", a specific period, or false.",
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "boolean"
+        }
+      ]
+    },
+    "colorBy": {
+      "type": "string",
+      "enum": [
+        "group",
+        "change",
+        "label"
+      ],
+      "description": "treemap: \"change\" colors tiles by % change vs the comparison period (diverging, growth cool / decline warm); \"label\" colors a single-level treemap by item."
+    },
+    "shade": {
+      "type": "boolean",
+      "description": "treemap/sunburst: subtle lightness steps inside each category (default false: one solid color per category)."
+    },
+    "xRange": {
+      "type": "array",
+      "description": "line/area: visible x range [from, to] (what the range slider sets)."
+    },
+    "focus": {
+      "description": "treemap/sunburst: path to drill into, e.g. [\"Mining\"]. network: a node id to center and highlight with its neighbors. In the browser, clicking does it.",
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ]
+    },
+    "depth": {
+      "type": "integer",
+      "description": "treemap/sunburst: how many levels to show."
+    },
+    "xScale": {
+      "type": "string",
+      "enum": [
+        "linear",
+        "log"
+      ]
+    },
+    "yScale": {
+      "type": "string",
+      "enum": [
+        "linear",
+        "log"
+      ]
+    },
+    "xDomain": {
+      "type": "array",
+      "items": {
+        "type": "number"
+      },
+      "description": "Fixed x domain [min, max]."
+    },
+    "yDomain": {
+      "type": "array",
+      "items": {
+        "type": "number"
+      },
+      "description": "Fixed value-axis domain [min, max]."
+    },
+    "zero": {
+      "type": "boolean",
+      "description": "line: force (or prevent) a y axis starting at zero."
+    },
+    "xLabel": {
+      "type": "string",
+      "description": "x-axis title."
+    },
+    "yLabel": {
+      "type": "string",
+      "description": "y-axis title (drawn horizontally above the axis)."
+    },
+    "format": {
+      "description": "Value format: \"number\" | \"compact\" | \"percent\" | \"currency\" | \"integer\", or { type, prefix, suffix, decimals, currency }.",
+      "anyOf": [
+        {
+          "type": "string",
+          "enum": [
+            "number",
+            "compact",
+            "percent",
+            "currency",
+            "integer"
+          ]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string"
+            },
+            "prefix": {
+              "type": "string"
+            },
+            "suffix": {
+              "type": "string"
+            },
+            "decimals": {
+              "type": "integer"
+            },
+            "currency": {
+              "type": "string"
+            }
+          }
+        }
+      ]
+    },
+    "highlight": {
+      "description": "Emphasize one or more categories/series and mute the rest.",
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ]
+    },
+    "dashed": {
+      "description": "Draw some shapes dashed (hatched fill + dashed outline; dashed stroke for lines) to mark estimates, projections or provisional figures. A category/series/region name or a list of them, a data field whose truthy rows are dashed, { field, equals }, or true for all.",
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        {
+          "type": "object",
+          "properties": {
+            "field": {
+              "type": "string"
+            },
+            "equals": {}
+          }
+        }
+      ]
+    },
+    "dashedFrom": {
+      "description": "line/area/bar on a time axis: x value from which marks are dashed (a projection). Lines turn dashed from the last firm point, over a soft labeled band.",
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "number"
+        }
+      ]
+    },
+    "dashedLabel": {
+      "description": "What the dashed shapes mean (\"Projection\", \"Preliminary\"): legend entry, band label and tooltip line. false hides the band label.",
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "boolean"
+        }
+      ]
+    },
+    "labels": {
+      "description": "Value labels: true, false or \"auto\". In scatter/regplot: a number of points or a list of names to label.",
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "string"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ]
+    },
+    "refLines": {
+      "type": "array",
+      "description": "Reference lines (targets, averages).",
+      "items": {
+        "type": "object",
+        "properties": {
+          "y": {
+            "type": "number"
+          },
+          "x": {
+            "type": "number"
+          },
+          "value": {
+            "type": "number"
+          },
+          "label": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "annotations": {
+      "type": "array",
+      "description": "line/area: events on the x axis.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "x": {},
+          "label": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "stack": {
+      "description": "bar/area: true stacks; \"percent\" stacks to 100%.",
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "string",
+          "enum": [
+            "percent"
+          ]
+        }
+      ]
+    },
+    "horizontal": {
+      "type": "boolean",
+      "description": "Force horizontal orientation (otherwise chosen from label length and count)."
+    },
+    "sort": {
+      "type": "string",
+      "enum": [
+        "desc",
+        "asc",
+        "none",
+        "alpha"
+      ],
+      "description": "bar: category order (desc by default unless the categories are time)."
+    },
+    "top": {
+      "type": "integer",
+      "description": "bar: keep the N largest and fold the rest into \"Other\"."
+    },
+    "index": {
+      "type": "boolean",
+      "description": "line: rebase each series to 100 at its first value (compare growth without a dual axis)."
+    },
+    "curve": {
+      "type": "string",
+      "enum": [
+        "linear",
+        "smooth",
+        "step"
+      ]
+    },
+    "aggregate": {
+      "type": "string",
+      "enum": [
+        "sum",
+        "mean",
+        "max",
+        "min",
+        "count",
+        "last",
+        "first"
+      ],
+      "description": "How to combine repeated rows. Default sum."
+    },
+    "ci": {
+      "description": "line/bar/regplot: confidence interval (true = 95, or a number). In line/bar it switches the estimator to the mean.",
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "number"
+        }
+      ]
+    },
+    "errorbar": {
+      "type": "string",
+      "enum": [
+        "ci",
+        "sd",
+        "se",
+        "pi",
+        "none"
+      ],
+      "description": "Error bar or band type."
+    },
+    "estimator": {
+      "type": "string",
+      "enum": [
+        "mean",
+        "median",
+        "sum",
+        "count"
+      ],
+      "description": "How to summarize several observations per category."
+    },
+    "bins": {
+      "type": "integer",
+      "description": "hist: number of bins."
+    },
+    "binWidth": {
+      "type": "number",
+      "description": "hist: bin width."
+    },
+    "stat": {
+      "type": "string",
+      "enum": [
+        "count",
+        "percent",
+        "density",
+        "probability"
+      ],
+      "description": "hist: what the y axis measures."
+    },
+    "kde": {
+      "type": "boolean",
+      "description": "hist: overlay a density curve."
+    },
+    "multiple": {
+      "type": "string",
+      "enum": [
+        "layer",
+        "stack",
+        "dodge",
+        "fill"
+      ],
+      "description": "hist/kde with hue: how groups are combined."
+    },
+    "fill": {
+      "type": "boolean",
+      "description": "kde: fill the area. line: false removes the gradient under a single line."
+    },
+    "order": {
+      "description": "regplot: polynomial degree (number). box/violin/strip/swarm/point: category order (list).",
+      "anyOf": [
+        {
+          "type": "integer"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ]
+    },
+    "lowess": {
+      "type": "boolean",
+      "description": "regplot: local regression instead of a straight line."
+    },
+    "logx": {
+      "type": "boolean",
+      "description": "regplot: fit y ~ log(x) with a log x axis."
+    },
+    "trend": {
+      "type": "boolean",
+      "description": "scatter: add a least-squares line and R²."
+    },
+    "annotate": {
+      "type": "boolean",
+      "description": "regplot: show R² and n."
+    },
+    "kind": {
+      "type": "string",
+      "enum": [
+        "scatter",
+        "reg"
+      ],
+      "description": "jointplot: center plot."
+    },
+    "marginal": {
+      "type": "string",
+      "enum": [
+        "hist",
+        "kde"
+      ],
+      "description": "jointplot: marginal plots."
+    },
+    "inner": {
+      "type": "string",
+      "enum": [
+        "box",
+        "quartiles",
+        "points",
+        "none"
+      ],
+      "description": "violin: what goes inside."
+    },
+    "split": {
+      "type": "boolean",
+      "description": "violin: with two hue levels, one half each."
+    },
+    "points": {
+      "type": "boolean",
+      "description": "box: overlay the observations. line: markers on every point."
+    },
+    "normalize": {
+      "type": "boolean",
+      "description": "radar: scale each axis 0–1 by its own maximum."
+    },
+    "half": {
+      "type": "boolean",
+      "description": "donut: semicircle."
+    },
+    "colors": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Pin colors to entities: { \"Biobío\": \"#3A47B8\" }."
+    },
+    "palette": {
+      "description": "Palette shortcut: a name (\"cdia\", \"okabe-ito\", \"tableau10\", \"udec\") or a list of colors in fixed order.",
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ]
+    },
+    "ramp": {
+      "description": "Sequential ramp: a name (\"indigo\", \"magenta\", \"teal\", \"amber\") or a list of colors from light to dark.",
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ]
+    },
+    "theme": {
+      "description": "Theme: \"papel\" (light, default), \"noche\" (dark), or a JSON object deep-merged over `extends`. Keys: surface, ink, lede, muted, grid, axis, tint, dim, other, categorical (list or palette name), sequential, diverging, status {good, warning, critical}, font {family, mono, import}, type {title, subtitle, label, axis, legend, source, titleWeight}, marks {barRadius, barMax, lineWidth, pointRadius, gap, ring, areaOpacity, bandOpacity, dotOpacity}, axes {inside, grid}, layout {padding}.",
+      "anyOf": [
+        {
+          "type": "string",
+          "enum": [
+            "papel",
+            "noche",
+            "light",
+            "dark"
+          ]
+        },
+        {
+          "type": "object"
+        }
+      ]
+    },
+    "font": {
+      "description": "Typeface for the whole chart: a Google Fonts name (\"Poppins\"), a CSS stack (\"'Inter', sans-serif\") or { family, import }. configure({ font }) sets it for every chart.",
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object"
+        }
+      ]
+    },
+    "textScale": {
+      "type": "number",
+      "description": "Multiplies every text size (1.5, 2…); the layout is recomputed so nothing overlaps. Aliases: fontScale, labelScale. configure({ textScale }) sets it for every chart."
+    },
+    "width": {
+      "type": "number",
+      "description": "Width in px (default 720; render() uses the container width)."
+    },
+    "height": {
+      "type": "number",
+      "description": "Height in px. Automatic for horizontal bars, heatmaps, KPI tiles, and narrow treemaps, sunbursts and radars."
+    }
+  }
+}