Data Storytelling with Altair and pynarrative: Turning Data into Insight

Author(s): S Aishwarya

Originally published on Towards AI.

Strong data storytelling goes beyond simply visualizing numbers it uncovers the meaning behind the patterns, bringing clarity to what would otherwise be just a spreadsheet of values.

While visualization libraries like matplotlib, Plotly, and Seaborn can produce beautiful charts, they often lack one crucial feature: narrative. They leave it up to the viewer to interpret the story behind the lines and bars.

That’s where Altair and the pynarrative library shine. Together, they help us not only visualize data — but actually explain it.

🔍What is Altair?

Altair is a Python library for declarative data visualization that allows users to create clean, concise, and interactive charts based on the Vega-Lite grammar of graphics.

You only need to provide:

• your data (typically a pandas DataFrame or Vega datasets)
• chart type (e.g., bar, line, scatter)
• encoding (x/y axes, color, size, etc.)
• optional interactivity, filtering, and tooltips

Altair then renders the visualization using a JSON specification — ready for use in dashboards, notebooks, web applications, or reports.

The Altair library directly integrates with pandas (for data handling) and Vega-Lite (for rendering and interactivity), making it easy for Python users to create powerful data stories without writing complex plotting code.

🔍 What is pynarrative?

pynarrative is a Python library designed to automatically craft clear, insightful narrative summaries from pandas DataFrames and Altair charts.

With just a few inputs:

• A dataset (often a time series or structured data in a DataFrame)
• A visualization (created using Altair)
• Axis labels, optional context, and your intended message

pynarrative generates a well-structured textual explanation — ideal for embedding in dashboards, reports, presentations, or interactive data stories.

Built to work seamlessly with pandas (for data handling) and Altair (for visual rendering), pynarrative helps bridge the gap between raw data and human-readable insights — turning visualizations into compelling narratives with minimal effort.

Data Description:

We’re using the cars dataset, which contains information about different car models. The main features we’ll focus on are:

• Horsepower: The power of the car’s engine.
• Miles_per_Gallon (MPG): How fuel-efficient the car is.
• Origin: Where the car was made (USA, Europe, or Japan).
• Name: The model name of the car.

These features help us explore the relationship between a car’s power and fuel efficiency, and how that varies by origin.

Data Cleaning & Preparation

We’ll begin by automatically loading the dataset using Seaborn, then clean it for our visualizations.

import pandas as pd
import seaborn as sns
import altair as alt
import pynarrative as pn

df = sns.load_dataset('mpg')

print(df[['name', 'mpg', 'horsepower', 'origin']].head())

Output:

Cleaning Steps:

1. Convert horsepower to numeric to handle any potential issues.
2. Drop rows with missing values in critical fields.

df['horsepower'] = pd.to_numeric(df['horsepower'], errors='coerce')

df_clean = df.dropna(subset=['horsepower', 'mpg', 'origin'])

print(df_clean[['name', 'mpg', 'horsepower', 'origin']].head())

Output:

Story 1: Power vs. Fuel Efficiency

Let’s explore the relationship between a car’s engine power (horsepower) and its fuel efficiency (miles per gallon).

By color-coding the data points based on the car’s region of origin, we gain insight into how different countries approach automotive design.

chart = pn.Story(df_clean).mark_circle(size=60).encode(
 x='horsepower:Q',
 y='mpg:Q',
 color='origin:N',
 tooltip=['name', 'horsepower', 'mpg', 'origin']
).add_title(
 "Horsepower vs MPG by Origin",
 "Higher horsepower often leads to lower fuel efficiency",
 title_color="#1a1a1a",
 subtitle_color="#4a4a4a"
).add_context(
 text=[
 "Cars with more horsepower generally consume more fuel.",
 "Japanese and European models show a clear emphasis on fuel efficiency.",
 "This trend reveals differing consumer needs and manufacturer strategies."
 ],
 position="bottom",
 dx=0,
 color="black"
).render()

chart

Output:

This visualization reveals that American cars tend to have higher horsepower but lower fuel economy, whereas Japanese and European cars show more balance.

Story 2: Regional Efficiency Trends Over Time

Let’s observe how fuel efficiency (MPG) has changed over time across different regions.

# Estimate year from model_year column
df_clean['year'] = df_clean['model_year'] + 1900
# Compute average MPG by region and year
regional_avg = df_clean.groupby(['year', 'origin'])['mpg'].mean().reset_index()
chart = pn.Story(regional_avg).mark_line(point=True).encode(
 x=alt.X('year:O', axis=alt.Axis(title='Year')),
 y=alt.Y('mpg:Q', title='Average MPG'),
 color='origin:N'
).add_title(
 "Average Fuel Efficiency by Region Over Time",
 "Trends in MPG from 1970s to 1980s",
 title_color="#1a1a1a",
 subtitle_color="#4a4a4a"
).add_context(
 text=[
 "Japanese cars consistently lead in fuel efficiency.",
 "U.S. manufacturers ramped up efficiency post-1975.",
 "European models maintain a steady middle ground."
 ],
 position="bottom",
 dx=0,
 color="black"
).render()
chart

Output:

We see how regulatory changes and fuel crises influenced fuel efficiency, especially in the U.S.

Story 3: Impact of the 1973 Oil Crisis

Let’s annotate our chart with the 1973 Oil Crisis, a pivotal moment for car design.

chart = pn.Story(regional_avg).mark_line().encode(
 x='year:O',
 y='mpg:Q',
 color='origin:N'
).add_title(
 "Impact of the 1973 Oil Crisis on MPG",
 "Shift in design philosophy after fuel shortages",
 title_color="#1a1a1a",
 subtitle_color="#4a4a4a"
).add_context(
 text=[
 "The 1973 Oil Crisis increased focus on fuel efficiency worldwide.",
 "U.S. automakers shifted designs to improve MPG post-crisis.",
 "Japanese models were already MPG leaders at the time."
 ],
 position="bottom",
 dx=0,
 color="black"
).add_annotation(
 1973, 15.5, "1973 Oil Crisis",
 arrow_direction='up',
 arrow_dx=0,
 arrow_dy=-1,
 arrow_color='red',
 arrow_size=50,
 label_color='black',
 label_size=14,
 show_point=True
).render()

chart

Output:

This annotated visualization adds historical context, showing how global events shape industry trends.

In Summary…

Using pynarrative and Altair, we seamlessly transformed car performance data into engaging visual stories by:

• Highlighting the inverse relationship between horsepower and fuel efficiency
• Exploring how regional design philosophies shape fuel economy over time
• Annotating major historical events like the 1973 Oil Crisis to show their industry impact

All of this was done using a single, intuitive interface combining pandas, Altair, and pynarrative. Once this storytelling pipeline is in place, it can be adapted to any dataset rendered through Altair from automotive to healthcare and beyond.

This approach is quicker, more scalable, and more intuitive than conventional manual charting methods. Whether you’re building technical reports, dynamic dashboards, or insight-driven narratives, this serves as a reliable foundation for effective data storytelling.

I would love to read your comments!

Join thousands of data leaders on the AI newsletter. Join over 80,000 subscribers and keep up to date with the latest developments in AI. From research to projects and ideas. If you are building an AI startup, an AI-related product, or a service, we invite you to consider becoming a sponsor.

Published via Towards AI