Gallery

A visual showcase of charts, maps, and tables styled with Attaviz.

Theme examples

These examples use Altair directly. Attaviz supplies the visual defaults while Altair supplies the chart specification. Native alt.Title(...) sets headings on these custom charts. For templates, pass title and subtitle directly; frame() adds publication footers and accessibility metadata to either kind of chart.

Bar chart

Output

source = data.barley()

alt.Chart(
    source,
    title=alt.Title(
        "Waseca had the highest barley yield",
        subtitle="Mean yield across varieties and years (bushels/acre)",
    ),
).mark_bar().encode(
    x=alt.X("mean(yield):Q", title="Mean yield"),
    y=alt.Y("site:N", title="Site", sort="-x"),
    color=alt.value(attaviz.CATEGORICAL[0]),
).properties(width="container", height=300)

Code

Line chart

Output

source = data.stocks()

alt.Chart(
    source,
    title=alt.Title(
        "Apple's stock price rose the most",
        subtitle="Monthly closing price by company, 2000–2010",
    ),
).mark_line().encode(
    x=alt.X("date:T", title=None),
    y=alt.Y("price:Q", title="Price (USD)"),
    color=alt.Color("symbol:N", title="Symbol"),
).properties(width="container", height=350)

Code

Line chart with hover

Output

source = data.stocks()

lines = (
    alt.Chart(
        source,
        title=alt.Title(
            "Apple's stock price rose the most",
            subtitle="Hover to compare companies at a date, 2000–2010",
        ),
    )
    .mark_line()
    .encode(
        x=alt.X("date:T", title=None),
        y=alt.Y("price:Q", title="Price (USD)"),
        color=alt.Color("symbol:N", title="Symbol"),
    )
    .properties(width="container", height=350)
)

attaviz.add_hover(lines, x="date", format="$.2f")

Code

Scatter plot

Output

source = data.cars()

alt.Chart(
    source,
    title=alt.Title(
        "Cars with more horsepower travel fewer miles per gallon",
        subtitle="Relationship between engine power and mileage by origin",
    ),
).mark_circle(size=80).encode(
    x=alt.X("Horsepower:Q"),
    y=alt.Y("Miles_per_Gallon:Q", title="Miles per gallon"),
    color=alt.Color("Origin:N", title="Origin"),
    tooltip=[
        "Name:N",
        "Horsepower:Q",
        alt.Tooltip("Miles_per_Gallon:Q", title="Miles per gallon"),
    ],
).properties(width="container", height=380)

Code

Area chart

Output

source = data.iowa_electricity()

alt.Chart(
    source,
    title=alt.Title(
        "Renewable electricity in Iowa grew fifteenfold",
        subtitle="Net generation by source (GWh), 2001–2017",
    ),
).mark_area().encode(
    x=alt.X("year:T", title=None),
    y=alt.Y("net_generation:Q", title="Net generation (GWh)"),
    color=alt.Color("source:N", title="Source"),
).properties(width="container", height=350)

Code

Heatmap

Output

source = data.seattle_weather()

alt.Chart(
    source,
    title=alt.Title(
        "Seattle is warmest in July and August",
        subtitle="Average daily maximum temperature (°C) by month",
    ),
).mark_rect().encode(
    x=alt.X("month(date):O", title="Month"),
    y=alt.Y("year(date):O", title="Year", axis=alt.Axis(grid=False)),
    color=alt.Color("mean(temp_max):Q", title="Average maximum temperature (°C)"),
).properties(width="container", height=250)

Code

Histogram

Output

source = data.movies()

alt.Chart(
    source,
    title=alt.Title(
        "Most movies rate between 5 and 8 on IMDb",
        subtitle="Number of movies by IMDb rating",
    ),
).mark_bar().encode(
    x=alt.X("IMDB_Rating:Q", bin=alt.Bin(maxbins=30), title="IMDb rating"),
    y=alt.Y("count()", title="Number of movies"),
    color=alt.value(attaviz.CATEGORICAL[0]),
).properties(width="container", height=300)

Code

Diverging color scale

Output

source = data.us_employment()

alt.Chart(
    source,
    title=alt.Title(
        "The United States lost jobs in most months of 2008 and 2009",
        subtitle="Monthly change in nonfarm payrolls (thousands), 2006–2015",
    ),
).mark_bar().encode(
    x=alt.X("month:T", title=None),
    y=alt.Y("nonfarm_change:Q", title="Change (thousands)"),
    color=alt.Color(
        "nonfarm_change:Q",
        scale=alt.Scale(range=attaviz.DIV_DEFAULT, domainMid=0),
        title="Change",
    ),
    tooltip=[
        alt.Tooltip("month:T", title="Month"),
        alt.Tooltip("nonfarm_change:Q", title="Change (thousands)"),
    ],
).properties(width="container", height=300)

Code

Faceted scatter plot

Output

source = data.iris()

alt.Chart(
    source,
).mark_circle(size=60).encode(
    x=alt.X("sepalLength:Q", title="Sepal length"),
    y=alt.Y("petalLength:Q", title="Petal length"),
    color=alt.Color("species:N", title="Species"),
).properties(
    width=200,
    height=200,
).facet(
    column=alt.Column("species:N", title=None),
).properties(
    title=alt.Title(
        "Setosa irises have much shorter petals",
        subtitle="Sepal and petal length (cm) by species",
    )
)

Code

More chart types

Small multiple line charts

Output

countries = ["Afghanistan", "China", "India", "Indonesia", "Nigeria", "United States"]
source = data.gapminder()
source = source[source["country"].isin(countries)]

base = alt.Chart().encode(
    x=alt.X("year:Q", title=None, axis=alt.Axis(format="d", tickCount=3)),
    y=alt.Y("life_expect:Q", title=None, scale=alt.Scale(zero=False)),
    color=alt.value(attaviz.CATEGORICAL[0]),
)
latest = base.transform_filter(alt.datum.year == 2005)

alt.layer(
    base.mark_line(),
    latest.mark_point(filled=True, size=40),
    latest.mark_text(align="left", dx=6).encode(text=alt.Text("life_expect:Q", format=".0f")),
    data=source,
).properties(width=170, height=110).facet(
    facet=alt.Facet("country:N", title=None, sort=countries),
    columns=3,
).properties(
    title=alt.Title(
        "Life expectancy rose across countries",
        subtitle="Life expectancy at birth, 1955–2005",
    )
)

Code

Dumbbell chart

Output

countries = ["Afghanistan", "China", "India", "Indonesia", "Nigeria", "United States"]
points = data.gapminder()
points = points[
    points["country"].isin(countries) & points["year"].isin([1955, 2005])
]
source = points.pivot(index="country", columns="year", values="life_expect").reset_index()
source = source.rename(columns={1955: "start", 2005: "end"})
order = source.assign(change=source["end"] - source["start"]).sort_values(
    "change", ascending=False
)["country"].tolist()

y = alt.Y("country:N", sort=order, title=None)
connector = alt.Chart(source).mark_rule(color=attaviz.REFERENCE, strokeWidth=2).encode(
    x="start:Q", x2="end:Q", y=y
)
dots = alt.Chart(points).mark_circle(size=90, opacity=1).encode(
    x=alt.X("life_expect:Q", title="Life expectancy at birth (years)"),
    y=y,
    color=alt.Color(
        "year:N",
        scale=alt.Scale(range=[attaviz.GREY_300, attaviz.CATEGORICAL[0]]),
        legend=alt.Legend(title=None, labelExpr="upper(datum.label)"),
    ),
    tooltip=["country:N", "year:N", alt.Tooltip("life_expect:Q", format=".1f")],
)

(connector + dots).properties(
    width="container",
    height=260,
    title=alt.Title(
        "Life expectancy increased across countries",
        subtitle="Years at birth, 1955 and 2005, sorted by change",
    ),
)

Code

Stacked area

Output

source = pd.read_csv("data/wdi-indonesia-employment.csv")

chart = alt.Chart(source).mark_area().encode(
    x=alt.X("year:O", title=None),
    y=alt.Y("share:Q", stack="normalize", title="Share of employment", axis=alt.Axis(format="%")),
    color=alt.Color(
        "sector:N",
        title=None,
        legend=alt.Legend(labelExpr="upper(datum.label)"),
    ),
    tooltip=[
        "year:O",
        "sector:N",
        alt.Tooltip("share:Q", title="Share", format=".1f"),
    ],
).properties(
    width="container",
    height=280,
    title=alt.Title(
        "Services account for half of Indonesia's employment",
        subtitle="Modeled share of employment by sector, 2000–2024",
    ),
)

attaviz.frame(
    chart,
    description="Stacked area chart of Indonesia's employment by sector from 2000 to 2024; the services share rises from 38% to 50% while agriculture falls from 45% to 28%.",
    source="World Development Indicators",
)

Code

Grouped bar

Output

source = pd.read_csv("data/wdi-electricity-access-2022.csv")

alt.Chart(source).mark_bar().encode(
    x=alt.X("access:Q", title=None, axis=alt.Axis(format="%"), scale=alt.Scale(domain=[0, 1])),
    y=alt.Y("country:N", title=None),
    yOffset=alt.YOffset("area:N", sort=["Urban", "Rural"]),
    color=alt.Color(
        "area:N",
        scale=alt.Scale(
            domain=["Urban", "Rural"],
            range=[attaviz.URBANIZATION["urban"], attaviz.URBANIZATION["rural"]],
        ),
        legend=alt.Legend(title=None, labelExpr="upper(datum.label)"),
    ),
    tooltip=["country:N", "area:N", alt.Tooltip("access:Q", format=".0%")],
).properties(
    width="container",
    height=alt.Step(12),
    title=alt.Title(
        "Rural electricity access still trails in some countries",
        subtitle="Share of population with access to electricity, 2022",
    ),
)

Code

Line chart with uncertainty band

Output

source = pd.read_csv("data/hci-range.csv")

base = alt.Chart(source).encode(
    x=alt.X("year:O", title=None, axis=alt.Axis(labelAngle=0)),
)
band = base.mark_area(color=attaviz.CATEGORICAL[0], opacity=0.2).encode(
    y=alt.Y("lower:Q", title="Human Capital Index", scale=alt.Scale(zero=False)),
    y2="upper:Q",
)
estimate = base.mark_line(color=attaviz.CATEGORICAL_TEXT[0], point=True).encode(
    y="estimate:Q",
    tooltip=["country:N", "year:O", alt.Tooltip("estimate:Q", format=".3f")],
)

chart = (band + estimate).properties(
    width=190,
    height=150,
).facet(
    facet=alt.Facet("country:N", title=None),
    columns=3,
).properties(
    title=alt.Title(
        "Human capital changed unevenly across Southeast Asia",
        subtitle="Human Capital Index estimate and uncertainty range, selected years",
    ),
)

attaviz.frame(
    chart,
    description="Lines with uncertainty bands showing the Human Capital Index for five Southeast Asian countries between 2010 and 2020.",
    source="World Bank Human Capital Index database",
)

Code

Bubble scatter plot

Output

source = pd.read_csv("data/wdi-southeast-asia-2023.csv")

alt.Chart(source).mark_circle(opacity=0.75, stroke="white", strokeWidth=1).encode(
    x=alt.X("gdp_per_capita:Q", title="GDP per capita (USD)", axis=alt.Axis(format="~s")),
    y=alt.Y("life_expectancy:Q", title="Life expectancy (years)", scale=alt.Scale(zero=False)),
    size=alt.Size(
        "population:Q",
        title="Population",
        scale=alt.Scale(range=[80, 1_200]),
        legend=alt.Legend(values=[50e6, 150e6, 250e6], format="~s"),
    ),
    color=alt.Color(
        "income_group:N",
        legend=alt.Legend(title=None, labelExpr="upper(datum.label)"),
    ),
    tooltip=[
        "country:N",
        "income_group:N",
        alt.Tooltip("gdp_per_capita:Q", title="GDP per capita", format=",.0f"),
        alt.Tooltip("life_expectancy:Q", title="Life expectancy", format=".1f"),
        alt.Tooltip("population:Q", title="Population", format=",.0f"),
    ],
).properties(
    width="container",
    height=320,
    title=alt.Title(
        "Higher incomes are associated with longer lives",
        subtitle="Bubble size represents population, 2023",
    ),
)

Code

Slope chart

Output

source = pd.read_csv("data/wdi-electricity-access-2010-2023.csv")

base = alt.Chart(source).encode(
    x=alt.X("year:O", title=None, axis=alt.Axis(labelAngle=0, ticks=False)),
    y=alt.Y("access:Q", title="Population with electricity access", axis=alt.Axis(format="%"), scale=alt.Scale(zero=False)),
    color=alt.Color("country:N", legend=None),
)
lines = base.mark_line(strokeWidth=2)
points = base.mark_circle(size=70)
labels = base.transform_filter(alt.datum.year == 2010).mark_text(align="right", dx=-8).encode(
    text="country:N"
)

chart = (lines + points + labels).properties(
    width="container",
    height=300,
    title=alt.Title(
        "Cambodia made the largest gain in electricity access",
        subtitle="Share of population with access, 2010 and 2023",
    ),
)

attaviz.frame(
    chart,
    description="Slope chart of electricity access in five Southeast Asian countries from 2010 to 2023; Cambodia rose from 31% to 95%.",
    source="World Development Indicators",
)

Code

Formatting and captions

These examples use Attaviz helpers for captions, publication frames, and number formats.

Title, subtitle, and source

Set the title and subtitle on the chart, then apply frame() last. It adds the note, source, and byline below the chart, and stores the required description as accessibility metadata.

Output

source = data.barley().groupby("site", as_index=False)["yield"].mean()

chart = attaviz.bar(
    source,
    category="site",
    value="yield",
    title="Waseca had the highest barley yield",
    subtitle="Mean yield across varieties and years (bushels/acre)",
    width=600,
    height=300,
)

attaviz.frame(
    chart,
    description="Horizontal bars comparing mean barley yield at six sites; Waseca is highest.",
    source="Minnesota agricultural experiment stations, 1931–1932",
    note="Yields are averaged across varieties and years.",
    byline="Attaviz",
)

Code

Formatted axis labels

Output

source = data.gapminder().query("year == 2005").nlargest(5, "pop")

alt.Chart(
    source,
    title=alt.Title(
        "China and India have the largest populations",
        subtitle="Population, 2005, axis formatted with d3_number_format",
    ),
).mark_bar().encode(
    x=alt.X(
        "pop:Q",
        title="Population",
        axis=alt.Axis(format=attaviz.d3_number_format(decimals=0)),
    ),
    y=alt.Y("country:N", sort="-x", title=None),
    color=alt.value(attaviz.CATEGORICAL[0]),
).properties(width="container", height=250)

Code

Auto-scaled with vega_scale_labelExpr

Output

source = data.gapminder().query("year == 2005").nlargest(5, "pop")

alt.Chart(
    source,
    title=alt.Title(
        "China and India have the largest populations",
        subtitle="Population, 2005, axis auto-scaled to K/M/B per tick",
    ),
).mark_bar().encode(
    x=alt.X(
        "pop:Q",
        title="Population",
        axis=alt.Axis(labelExpr=attaviz.vega_scale_labelExpr()),
    ),
    y=alt.Y("country:N", sort="-x", title=None),
    color=alt.value(attaviz.CATEGORICAL[0]),
    tooltip=alt.Tooltip("pop:Q", format=attaviz.d3_number_format(decimals=0))
).properties(width="container", height=250)

Code

Chart templates

These examples use Attaviz chart templates and composition helpers to handle common editorial decisions.

Bar chart with highlight and publication frame

Output

source = pd.read_csv("data/wdi-southeast-asia-2023.csv")

chart = attaviz.bar(
    source,
    category="country",
    value="gdp",
    title="Indonesia has Southeast Asia's largest economy",
    subtitle="Current-price GDP, 2023",
    highlight="Indonesia",
    value_format="currency",
    currency="USD",
)

attaviz.frame(
    chart,
    description="Horizontal bars comparing GDP in five Southeast Asian economies; Indonesia is highlighted.",
    source="World Development Indicators",
    source_url="https://databank.worldbank.org/source/world-development-indicators",
)

Code

Line chart with annotation and reference line

Output

source = data.stocks().query("symbol in ['AAPL', 'MSFT', 'GOOG']")

chart = attaviz.line(
    source,
    x="date",
    y="price",
    series="symbol",
    title="Technology stocks followed different paths",
    subtitle="Monthly closing price, 2000–2010",
    highlight="AAPL",
    width="responsive",
)

chart = attaviz.add_reference_line(
    chart,
    value=500,
    axis="y",
    label="500",
)

attaviz.add_annotation(
    chart,
    x=pd.Timestamp("2007-12-01"),
    y=198.08,
    text="Apple approached 200",
    position="above",
)

Code

Scatter plot with highlight and reference range

Output

source = data.cars().dropna(subset=["Horsepower", "Miles_per_Gallon", "Name"])

chart = attaviz.scatter(
    source,
    x="Horsepower",
    y="Miles_per_Gallon",
    label="Name",
    series="Origin",
    highlight="honda civic",
    title="More powerful cars tend to use more fuel",
    subtitle="Horsepower and fuel economy",
)

attaviz.add_reference_range(
    chart,
    start=25,
    end=35,
    axis="y",
    label="25–35 mpg",
)

Code

Maps

Use choropleth() for area maps. For other map types, such as point maps, use Altair with the theme enabled.

Choropleth map

Output

import geopandas as gpd

countries = gpd.read_file("data/southeast-asia.geojson")

chart = attaviz.choropleth(
    countries,
    value="gdp_per_capita",
    label="country",
    value_label="GDP per capita (USD)",
    meaning="higher_is_better",
    classification="custom",
    breaks=[3_000, 5_000, 10_000, 20_000],
    value_format=",.0f",
    highlight="Indonesia",
    tooltip=["population"],
    title="Income levels vary widely across Southeast Asia",
    subtitle="GDP per capita, 2019 estimates",
    projection="mercator",
    width=700,
    height=450,
)

attaviz.frame(
    chart,
    description="A choropleth of 2019 GDP per capita estimates across eleven Southeast Asian economies; Indonesia is highlighted.",
    source="Natural Earth",
    source_url="https://www.naturalearthdata.com/",
    note="GDP per capita is calculated from Natural Earth's population and GDP estimates. Boundaries follow Natural Earth's de facto representation.",
)

Code

Continuous choropleth with missing data and annotation

Output

continuous_countries = countries.copy()
continuous_countries.loc[
    continuous_countries["country"] == "Myanmar", "gdp_per_capita"
] = None

chart = attaviz.choropleth(
    continuous_countries,
    value="gdp_per_capita",
    label="country",
    value_label="GDP per capita (USD)",
    value_format=",.0f",
    title="Missing values remain visible",
    subtitle="Continuous scale with Myanmar shown as no data",
    projection="mercator",
    width=700,
    height=450,
)

attaviz.add_map_annotation(
    chart,
    longitude=106.8,
    latitude=-6.2,
    text="Jakarta",
)

Code

Quantile change choropleth

Output

change_countries = countries.assign(
    relative_income_change=(
        countries["gdp_per_capita"] / countries["gdp_per_capita"].median() - 1
    )
)

attaviz.choropleth(
    change_countries,
    value="relative_income_change",
    label="country",
    value_label="Difference from regional median",
    meaning="change",
    classification="quantile",
    classes=3,
    value_format="percent",
    title="Income differs across the region",
    subtitle="Difference from the regional median, grouped into three quantiles",
    projection="mercator",
    width=700,
    height=450,
)

Code

Point map

Output

capitals = pd.DataFrame(
    {
        "city": ["Bangkok", "Hanoi", "Jakarta", "Kuala Lumpur", "Manila", "Phnom Penh"],
        "country": ["Thailand", "Viet Nam", "Indonesia", "Malaysia", "Philippines", "Cambodia"],
        "longitude": [100.5018, 105.8342, 106.8456, 101.6869, 120.9842, 104.9282],
        "latitude": [13.7563, 21.0278, -6.2088, 3.1390, 14.5995, 11.5564],
    }
)

base = alt.Chart(countries).mark_geoshape(
    fill=attaviz.NO_DATA,
    stroke="white",
    strokeWidth=0.5,
    tooltip=None,
)

points = alt.Chart(capitals).mark_circle(
    size=45,
    color=attaviz.CATEGORICAL[0],
).encode(
    longitude="longitude:Q",
    latitude="latitude:Q",
    tooltip=[
        alt.Tooltip("city:N", title="City"),
        alt.Tooltip("country:N", title="Country"),
    ],
)

(base + points).project(type="mercator").properties(
    width=600,
    height=360,
    title=alt.Title(
        "Selected Southeast Asian capitals",
        subtitle="Capital-city locations over local gallery boundaries",
    ),
)

Code

Tables

Install attaviz[tables] to use the table helper. It returns a native Great Tables object with Attaviz styling; use Great Tables methods for column labels and formatting.

Counts and percentages

Format counts with thousands separators and fractions as percentages. Missing values display as N/A.

Output

participation = pd.DataFrame(
    {
        "country": ["Indonesia", "Malaysia", "Philippines"],
        "participants": [12345, 8900, 6750],
        "completion": [0.876, 0.923, None],
    }
)

participation_table = (
    attaviz.table(
        participation,
        title="Program participation by country",
        subtitle="Illustrative counts and completion rates",
        source="Source: illustrative data. N/A indicates unavailable data.",
    )
    .cols_label(country="Country", participants="Participants", completion="Completion")
    .fmt_integer(columns="participants")
    .fmt_percent(columns="completion", decimals=1)
)

participation_table

Program participation by country
Illustrative counts and completion rates
Country	Participants	Completion
Indonesia	12,345	87.6%
Malaysia	8,900	92.3%
Philippines	6,750	N/A
Source: illustrative data. N/A indicates unavailable data.

Code

Grouped columns and a footnote

Build on the table above using Great Tables’ native methods. Group the numeric columns under a shared heading and attach a definition to the completion column.

Output

from great_tables import loc

(
    participation_table
    .tab_spanner(label="Program results", columns=["participants", "completion"])
    .tab_footnote(
        "Completion is the share of participants who finished the program.",
        locations=loc.column_labels(columns="completion"),
    )
)

Program participation by country
Illustrative counts and completion rates
Country	Program results
	Participants	Completion1
Indonesia	12,345	87.6%
Malaysia	8,900	92.3%
Philippines	6,750	N/A
Source: illustrative data. N/A indicates unavailable data.
1 Completion is the share of participants who finished the program.

Code

Wide table with subtle row striping

Keep related numeric measures together and use a light alternating background to help readers track rows across the table. Full labels wrap when needed.

Output

wide_participation = participation.assign(
    eligible=[18000, 12000, 9500],
    funding=[1250000, 920000, 740000],
    duration_months=[12, 18, 12],
)[["country", "eligible", "participants", "completion", "duration_months", "funding"]]

(
    attaviz.table(
        wide_participation,
        title="Program coverage and results",
        subtitle="Illustrative participation, completion, duration, and funding",
        source="Source: illustrative data. N/A indicates unavailable data.",
    )
    .cols_label(
        country="Country",
        eligible="Eligible people",
        participants="Participants",
        completion="Completion (%)",
        duration_months="Duration (months)",
        funding="Funding (USD)",
    )
    .fmt_integer(columns=["eligible", "participants", "duration_months"])
    .fmt_percent(columns="completion", decimals=1)
    .fmt_currency(columns="funding", currency="USD", decimals=0)
    .opt_row_striping()
    .tab_options(table_body_hlines_style="none")
)

Program coverage and results
Illustrative participation, completion, duration, and funding
Country	Eligible people	Participants	Completion (%)	Duration (months)	Funding (USD)
Indonesia	18,000	12,345	87.6%	12	$1,250,000
Malaysia	12,000	8,900	92.3%	18	$920,000
Philippines	9,500	6,750	N/A	12	$740,000
Source: illustrative data. N/A indicates unavailable data.

Code