Altair Python

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

Read the declarative grammar before choosing mark, grain, encoding type, aggregation, or interaction.

Ordered workflow

1. State the analytical question, one-row data grain, fields, missing-value policy, required ordering, and output host before selecting a mark.
2. Decide whether the displayed grain equals input rows or a derived aggregate, bin, window, fold, lookup, or time unit. Make that transformation explicit.
3. 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.
4. 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.
5. Add composition or interaction only when it serves the question. Name parameters and resolve scales/guides deliberately.
6. Decide where data lives: inline values, URL, named dataset, or a configured transformer. Never disable a row safeguard merely to silence an error.
7. 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

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