Altair Python
Build the smallest valid declarative specification that answers the stated
question. A chart maps data fields to visual channels; it is not a sequence of
drawing commands and does not contain rendered pixels.
Boundary
Use this skill when a project imports Altair or explicitly requests Altair or a
Vega-Lite specification. Do not introduce it into Plotly/Matplotlib-only code,
Streamlit application-state work, or a pure dataframe transformation. Preserve
the required artifact boundary: Python chart object, JSON spec, HTML, or image.
Know the objects
| Object |
Runtime meaning |
Use |
Chart |
Declarative unit specification over a data source |
Add one mark, encodings, transforms, parameters, and properties. |
| Mark |
Geometric representation such as point, line, bar, area, rect, rule, or text |
Choose from the analytical task and data grain. |
| Encoding channel |
Mapping from field/value/datum/expression to x, y, color, size, shape, tooltip, facet, etc. |
Declare field type, aggregation, scale, axis, legend, sort. |
| Transform |
Vega-Lite data operation inside the specification |
Filter, calculate, aggregate, bin, time unit, window, lookup, fold, and related view-local work. |
| Parameter/selection |
Named interactive value or selected data subset |
Drive filters, conditions, domains, or bound controls. |
| Compound chart |
Layer, facet, repeat, horizontal/vertical concat |
Compose related views with explicit shared/independent guides. |
| Serialized spec |
Validated Vega-Lite JSON-compatible tree |
Test, inspect, embed, save, or hand to a renderer. |
Read the declarative grammar before choosing mark,
grain, encoding type, aggregation, or interaction.
Ordered workflow
- State the analytical question, one-row data grain, fields, missing-value
policy, required ordering, and output host before selecting a mark.
- Decide whether the displayed grain equals input rows or a derived aggregate,
bin, window, fold, lookup, or time unit. Make that transformation explicit.
- Choose the mark from the relationship: position for quantitative comparison,
line only for meaningful ordered continuity, bar for discrete magnitude,
rect for two-dimensional bins, rule/text only as annotation.
- Encode fields with explicit semantic types when inference could be wrong:
quantitative, temporal, ordinal, nominal, or geographic. Configure sort,
scale, axis, legend, and tooltip from the contract.
- Add composition or interaction only when it serves the question. Name
parameters and resolve scales/guides deliberately.
- Decide where data lives: inline values, URL, named dataset, or a configured
transformer. Never disable a row safeguard merely to silence an error.
- Validate/inspect the serialized spec and test semantic nodes. Render in the
real host only when visual integration is part of completion.
Intent to specification
| Question |
Typical grammar |
Invariant |
| Relationship between two measures |
point with quantitative x/y |
One mark per intended observation; reveal overplotting when material. |
| Trend across ordered time |
line with temporal x and quantitative y |
Time is sorted; missing intervals/series do not imply false continuity. |
| Compare categories |
bar/tick with nominal/ordinal category and quantitative value |
Aggregation and category order are explicit; zero baseline policy is defensible. |
| Distribution |
binned bar, tick, boxplot, density, or ECDF-style transform |
Bin/statistic and units are visible. |
| Two-dimensional magnitude |
rect/heatmap with x/y bins and color |
Color type/domain and missing bins are defined. |
| Same measure across groups |
facet/repeat small multiples |
Comparable scales are shared unless independent scales are an explicit need. |
| Overlay observations and summary |
layer charts over common data/encodings |
Layer order and scale resolution preserve meaning. |
| Interactive subset |
parameter/selection plus conditional encoding or filter |
Empty-selection and initial-state behavior are defined. |
Canonical anchor
import altair as alt
def sales_chart(data):
return (
alt.Chart(data)
.mark_line(point=True)
.encode(
x=alt.X("date:T", title="Date"),
y=alt.Y("revenue:Q", title="Revenue"),
color=alt.Color("region:N", title="Region"),
tooltip=[
alt.Tooltip("date:T"),
alt.Tooltip("region:N"),
alt.Tooltip("revenue:Q", format=",.2f"),
],
)
.properties(title="Revenue by region")
)
The return value remains a chart/specification. Do not call display/save inside
a reusable chart builder unless that side effect is its public contract.
Data and transform boundary
- Transform in Python when the result is shared outside the chart, requires
domain validation, or is easier to unit-test as data.
- Transform in Vega-Lite when it is view-local, must react to a parameter, or
should remain coupled to the visualization grammar.
- Do not both pre-aggregate and declare the same aggregation in an encoding.
- Explicitly retain group keys through aggregate/window operations.
- Treat Altair data transformers as serialization/loading policy, not
Vega-Lite transforms. Sampling changes the analytical result and requires an
explicit statistical decision.
- For large data, aggregate/filter upstream or use an intentional external-data
path. Never globally disable maximum-row protection as a default fix.
Read data and transform rules.
Composition and interaction
Layer when views share coordinates; facet/repeat when subsets need comparable
panels; concatenate when views have distinct coordinates. For compound views,
state whether x/y scales, legends, and axes are shared or independent. Define a
parameter once at the correct scope, then use it through a filter, condition,
or domain. Do not add .interactive() as a substitute for a specified
selection behavior.
Read composition, export, and testing.
Verification
Inspect the installed version of Altair and the target renderer before using a
drift-sensitive parameter/transform/export signature. This foundry had no
Altair installation during authoring, so examples are primary-source-grounded
but not locally rendered.
Completion requires: correct input and displayed grain; explicit field types,
aggregation, sort, and scale semantics; stable null/empty behavior; no duplicate
aggregation; intentional data transport; valid serialized specification;
semantic tests for marks/encodings/transforms/parameters; and a host render or
clearly reported missing render evidence when appearance matters.
References
- Declarative grammar and encoding
- Data and transform boundary
- Composition, export, and testing
1---2name: altair-python3description: Use for writing, reviewing, debugging, or testing declarative statistical visualizations in Python with Altair and Vega-Lite, including Chart marks, typed encodings, transforms, parameters/selections, layers, facets, scale resolution, data transformers, and specification export. Do not use for Plotly figures, imperative Matplotlib drawing, dashboard state, or data-cleaning work without an Altair output.4argument-hint: "[Altair chart task, data contract, spec, interaction, or failure]"5metadata:6 source: https://skillmd.com/skills/schattenspiegel/altair-python7---89# Altair Python1011Build the smallest valid declarative specification that answers the stated12question. A chart maps data fields to visual channels; it is not a sequence of13drawing commands and does not contain rendered pixels.1415## Boundary1617Use this skill when a project imports Altair or explicitly requests Altair or a18Vega-Lite specification. Do not introduce it into Plotly/Matplotlib-only code,19Streamlit application-state work, or a pure dataframe transformation. Preserve20the required artifact boundary: Python chart object, JSON spec, HTML, or image.2122## Know the objects2324| Object | Runtime meaning | Use |25|---|---|---|26| `Chart` | Declarative unit specification over a data source | Add one mark, encodings, transforms, parameters, and properties. |27| Mark | Geometric representation such as point, line, bar, area, rect, rule, or text | Choose from the analytical task and data grain. |28| Encoding channel | Mapping from field/value/datum/expression to x, y, color, size, shape, tooltip, facet, etc. | Declare field type, aggregation, scale, axis, legend, sort. |29| Transform | Vega-Lite data operation inside the specification | Filter, calculate, aggregate, bin, time unit, window, lookup, fold, and related view-local work. |30| Parameter/selection | Named interactive value or selected data subset | Drive filters, conditions, domains, or bound controls. |31| Compound chart | Layer, facet, repeat, horizontal/vertical concat | Compose related views with explicit shared/independent guides. |32| Serialized spec | Validated Vega-Lite JSON-compatible tree | Test, inspect, embed, save, or hand to a renderer. |3334Read [the declarative grammar](references/grammar.md) before choosing mark,35grain, encoding type, aggregation, or interaction.3637## Ordered workflow38391. State the analytical question, one-row data grain, fields, missing-value40 policy, required ordering, and output host before selecting a mark.412. Decide whether the displayed grain equals input rows or a derived aggregate,42 bin, window, fold, lookup, or time unit. Make that transformation explicit.433. Choose the mark from the relationship: position for quantitative comparison,44 line only for meaningful ordered continuity, bar for discrete magnitude,45 rect for two-dimensional bins, rule/text only as annotation.464. Encode fields with explicit semantic types when inference could be wrong:47 quantitative, temporal, ordinal, nominal, or geographic. Configure sort,48 scale, axis, legend, and tooltip from the contract.495. Add composition or interaction only when it serves the question. Name50 parameters and resolve scales/guides deliberately.516. Decide where data lives: inline values, URL, named dataset, or a configured52 transformer. Never disable a row safeguard merely to silence an error.537. Validate/inspect the serialized spec and test semantic nodes. Render in the54 real host only when visual integration is part of completion.5556## Intent to specification5758| Question | Typical grammar | Invariant |59|---|---|---|60| Relationship between two measures | point with quantitative x/y | One mark per intended observation; reveal overplotting when material. |61| Trend across ordered time | line with temporal x and quantitative y | Time is sorted; missing intervals/series do not imply false continuity. |62| Compare categories | bar/tick with nominal/ordinal category and quantitative value | Aggregation and category order are explicit; zero baseline policy is defensible. |63| Distribution | binned bar, tick, boxplot, density, or ECDF-style transform | Bin/statistic and units are visible. |64| Two-dimensional magnitude | rect/heatmap with x/y bins and color | Color type/domain and missing bins are defined. |65| Same measure across groups | facet/repeat small multiples | Comparable scales are shared unless independent scales are an explicit need. |66| Overlay observations and summary | layer charts over common data/encodings | Layer order and scale resolution preserve meaning. |67| Interactive subset | parameter/selection plus conditional encoding or filter | Empty-selection and initial-state behavior are defined. |6869## Canonical anchor7071```python72import altair as alt737475def sales_chart(data):76 return (77 alt.Chart(data)78 .mark_line(point=True)79 .encode(80 x=alt.X("date:T", title="Date"),81 y=alt.Y("revenue:Q", title="Revenue"),82 color=alt.Color("region:N", title="Region"),83 tooltip=[84 alt.Tooltip("date:T"),85 alt.Tooltip("region:N"),86 alt.Tooltip("revenue:Q", format=",.2f"),87 ],88 )89 .properties(title="Revenue by region")90 )91```9293The return value remains a chart/specification. Do not call display/save inside94a reusable chart builder unless that side effect is its public contract.9596## Data and transform boundary9798- Transform in Python when the result is shared outside the chart, requires99 domain validation, or is easier to unit-test as data.100- Transform in Vega-Lite when it is view-local, must react to a parameter, or101 should remain coupled to the visualization grammar.102- Do not both pre-aggregate and declare the same aggregation in an encoding.103- Explicitly retain group keys through aggregate/window operations.104- Treat Altair data transformers as serialization/loading policy, not105 Vega-Lite transforms. Sampling changes the analytical result and requires an106 explicit statistical decision.107- For large data, aggregate/filter upstream or use an intentional external-data108 path. Never globally disable maximum-row protection as a default fix.109110Read [data and transform rules](references/data-transforms.md).111112## Composition and interaction113114Layer when views share coordinates; facet/repeat when subsets need comparable115panels; concatenate when views have distinct coordinates. For compound views,116state whether x/y scales, legends, and axes are shared or independent. Define a117parameter once at the correct scope, then use it through a filter, condition,118or domain. Do not add `.interactive()` as a substitute for a specified119selection behavior.120121Read [composition, export, and testing](references/composition-testing.md).122123## Verification124125Inspect the installed version of Altair and the target renderer before using a126drift-sensitive parameter/transform/export signature. This foundry had no127Altair installation during authoring, so examples are primary-source-grounded128but not locally rendered.129130Completion requires: correct input and displayed grain; explicit field types,131aggregation, sort, and scale semantics; stable null/empty behavior; no duplicate132aggregation; intentional data transport; valid serialized specification;133semantic tests for marks/encodings/transforms/parameters; and a host render or134clearly reported missing render evidence when appearance matters.135136## References137138- [Declarative grammar and encoding](references/grammar.md)139- [Data and transform boundary](references/data-transforms.md)140- [Composition, export, and testing](references/composition-testing.md)