Reference — curated charts (format=data)

When a single number or a small series is more useful than SQL, read a curated chart in data mode. Prefer query_sql for anything aggregational.

Contents

• The format=data contract
• The curated allow-list (subject-scoped)
• PNG rendering
• How to read

The format=data contract

Every figure-backed chart endpoint accepts ?format=data, returning the raw numbers behind the chart ({series | rows | header/cells | value, meta}) instead of a Plotly {data, layout} figure. Reason over the data shape; never parse the figure. Series are point-capped (PARLEML_AGENT_MAX_POINTS, default 2000).

The curated allow-list (subject-scoped)

The only family.kind pairs get_chart_data(family, kind, subject_id, params?, render?) accepts (mirror of parleml_mcp/chart_kinds.py). Family names match the help families of get_chart_data(family) exactly. eda.* charts are dataset-scoped (subject_id = a dataset id); every other family is experiment-scoped.

family.kind	Scope	Path (?format=data)
forecast.forecast	experiment	/api/experiments/{id}/forecast/plot/forecast
forecast.actual_vs_predicted	experiment	/api/experiments/{id}/forecast/plot/actual_vs_predicted
forecast.residuals	experiment	/api/experiments/{id}/forecast/plot/residuals
anomaly.score_distribution	experiment	/api/experiments/{id}/unsupervised/plot/score_distribution
anomaly.anomaly_map	experiment	/api/experiments/{id}/unsupervised/plot/anomaly_map
anomaly.top_k_table	experiment	/api/experiments/{id}/unsupervised/plot/top_k_table
clustering.cluster_map	experiment	/api/experiments/{id}/unsupervised/plot/cluster_map
clustering.cluster_sizes	experiment	/api/experiments/{id}/unsupervised/plot/cluster_sizes
clustering.silhouette	experiment	/api/experiments/{id}/unsupervised/plot/silhouette
mli.model_importance	experiment	/api/experiments/{id}/mli/model-importance
mli.pdp	experiment	/api/experiments/{id}/mli/pdp
mli.calibration	experiment	/api/experiments/{id}/mli/calibration-comparison
association.network	experiment	/api/experiments/{id}/association/network (natively data)
eda.correlation	dataset	/api/datasets/{id}/eda/plot/correlation
eda.target_correlation	dataset	/api/datasets/{id}/eda/plot/target_correlation
eda.missingness	dataset	/api/datasets/{id}/eda/plot/missingness
eda.outliers	dataset	/api/datasets/{id}/eda/plot/outliers
eda.distribution_alerts	dataset	/api/datasets/{id}/eda/plot/distribution_alerts
eda.category_variability	dataset	/api/datasets/{id}/eda/plot/category_variability

Accepted params per family

params is forwarded verbatim as query parameters. The backend ignores keys it does not declare, so a misspelled name is a silent no-op that returns the unfiltered chart — check this table rather than guessing.

Family	Accepted params
forecast.*	series (unique_id to focus), metric, interval_level (1-99, default 95), max_ids (1-20, default 6), max_lag (2-120, default 36), ds (timestamp, Shapley waterfall)
anomaly.* / clustering.*	feature_x, feature_y (scatter plots), feature (score-vs-feature)
eda.*	cat_col, num_col
mli.* / association.network	none — natively data-shaped

Association rules/itemsets/holdings are SQL-first — query the *__assoc_* tables (see schema-association); the one chart-shaped association read is the item network above. The per-rule opportunity audience is get_insight(id, "association_audience", params={"rule_id": …}).

PNG rendering

get_chart_data(..., render="png") returns the server-rendered chart as an image (900×540) — useful when the host displays images inline. It applies only to figure-backed kinds: a natively-data kind (mli.*, association.network) rejects render="png" with an error ("omit render"). For a figure-backed kind where rendering is unavailable (no kaleido in the serving environment), the tool falls back to the data payload with a png_unavailable note. Either way the numbers stay the canonical layer.

How to read

1. get_chart_data(family) — kind omitted — is help mode: it explains what each chart of the family means (how to read it) and marks each entry fetchable. get_chart_data("all") is the compact index of every family (ids and labels, no prose). Help mode takes family alone — no subject_id, params or render. It does not list params — a help entry is {id, label, markdown, fetchable}; the accepted params per family are in the table above. The help namespaces and the registry are drift-tested to match, but help advertises more kinds than the curated registry exposes, so an id from help is fetchable only when it says fetchable: true — the allow-list above is authoritative.
2. get_chart_data(family, kind, subject_id, params?, render?) returns the numbers (dataset id for eda.*, experiment id otherwise).
3. For deep/interactive visuals, point the user at the parleml UI (follow the ui_url links tools return) rather than dumping large payloads.