jswortz/altair

Altair Data Visualization Skill

Use this skill when tasked with generating charts, graphs, and plots using Python. Altair is a declarative statistical visualization library for Python, based on Vega and Vega-Lite. Our environment relies on Altair instead of Matplotlib and Seaborn for all new plots.

Setup

Ensure altair and vl-convert-python are available locally via uv.

import altair as alt
import pandas as pd

Creating Charts

Altair expects data in a Pandas DataFrame, preferably in long format (melted).

Example: Line Chart with Multiple Series

import pandas as pd
import altair as alt

# 1. Prepare Data
df = pd.DataFrame({
    'Epoch': [1, 2, 3],
    'Metric A': [0.5, 0.6, 0.7],
    'Metric B': [0.4, 0.5, 0.9]
})

# 2. Melt Data
df_melt = df.melt('Epoch', var_name='Metric', value_name='Score')

# 3. Create Base Chart
base = alt.Chart(df_melt).encode(
    x=alt.X('Epoch:Q', title='Generation (Epoch)', axis=alt.Axis(tickMinStep=1))
)

# 4. Create Line Marks
lines = base.mark_line(point=True).encode(
    y=alt.Y('Score:Q', title='Evaluation Score', scale=alt.Scale(domain=[0, 1.0])),
    color=alt.Color('Metric:N', scale=alt.Scale(
        domain=['Metric A', 'Metric B'],
        range=['#4A90E2', '#F5A623']
    )),
    tooltip=['Epoch', 'Metric', 'Score']
)

# 5. Add Properties and Config
chart = lines.properties(
    title="Evolution Performance",
    width=700,
    height=400
).configure_title(
    fontSize=14
)

# 6. Save Chart
chart.save("output.png")

Supported Output Formats

• .html (Interactive web page)
• .png (Requires vl-convert-python)
• .svg (Requires vl-convert-python)
• .json (Vega-Lite spec)

Common Scenarios

• Scatter Plot: mark_circle(size=60)
• Bar Chart: mark_bar()
• Area Chart: mark_area()
• Dual Axis: alt.layer(chart1, chart2).resolve_scale(y='independent') Note: To resolve dual axis you simply create 2 independent charts and use alt.layer(c1, c2).resolve_scale(y='independent').
• Horizontal Rule / Threshold:

threshold = alt.Chart(pd.DataFrame({'y': [0.70]})).mark_rule(color='red', strokeDash=[5,5]).encode(y='y:Q')
chart = alt.layer(lines, threshold)

Best Practices

1. Avoid matplotlib or seaborn unless specifically requested. Altair handles complex legends and multi-series plots in a cleaner declarative way.
2. If data is large (>5000 rows), use alt.data_transformers.disable_max_rows() with caution, or aggregate the dataframe using Pandas before passing to Altair.
3. Keep tooltips explicit for better interactivity if saving as HTML.
4. Customize colors with scale=alt.Scale(scheme='set2') (or other vega schemes) or precise hex arrays range=['#ff0000', '#00ff00'].