Skip to content

refactor: update documentation for various chart examples with improv… #457

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
palewire merged 1 commit into from
Oct 20, 2025
Merged

refactor: update documentation for various chart examples with improv… #457

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions docs/user-guide/charts/column-charts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,19 @@ url = "https://raw.githubusercontent.com/chekos/datawrapper/main/tests/samples/c
df = pd.read_csv(url)

chart = dw.ColumnChart(
# Chart title with HTML line break
# Chart headline
title="U.S. unemployment rate",
# Introductory text
intro="January 2016-September 2020",
# Data source attribution
source_name="U.S. Bureau of Labor Statistics",
source_url="https://www.bls.gov/",
# Introductory text
intro="January 2016-September 2020",
# Data from pandas DataFrame
data=df,
# Format Y-axis grid labels with one decimal place and a percentage sign
# Format labels with one decimal place and a percentage sign
y_grid_format=dw.NumberFormat.PERCENT_UP_TO_ONE_DECIMAL,
# Format value labels with one decimal place
value_labels_format=dw.NumberFormat.PERCENT_UP_TO_ONE_DECIMAL,
# Highlight specific column in red
# Highlight specific columns with custom colors
base_color="#CCCCCC",
color_category={
"2020/04": "rgb(21, 96, 122)",
Expand All @@ -36,6 +35,7 @@ chart = dw.ColumnChart(
"2020/08": "rgb(21, 96, 122)",
"2020/09": "rgb(21, 96, 122)",
},
# Annotations to highlight the COVID-19 period
range_annotations=[
dw.RangeAnnotation(
x0="2020/01/01",
Expand Down
81 changes: 42 additions & 39 deletions docs/user-guide/charts/line-charts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# LineChart

## Example
This example, drawn from <a href="https://www.datawrapper.de/charts/lines">the Datawrapper documentation</a>, demonstrates how to create a line chart with a shaded confidence interval around the line.

This example demonstrates how to create a line chart showing global land temperature in July from 1753-2015, with confidence intervals displayed as a shaded area.
<iframe title="Global land temperature in July, 1753-2015" aria-label="Line chart" id="datawrapper-chart-9Qlvu" src="https://datawrapper.dwcdn.net/9Qlvu/1/" scrolling="no" frameborder="0" style="width: 0; min-width: 100% !important; border: none;" height="400" data-external="1"></iframe><script type="text/javascript">window.addEventListener("message",function(a){if(void 0!==a.data["datawrapper-height"]){var e=document.querySelectorAll("iframe");for(var t in a.data["datawrapper-height"])for(var r,i=0;r=e[i];i++)if(r.contentWindow===a.source){var d=a.data["datawrapper-height"][t]+"px";r.style.height=d}}});</script>

```python
import pandas as pd
import datawrapper as dw

# Load temperature data from GitHub
url = "https://raw.githubusercontent.com/palewire/datawrapper-api-classes/main/tests/samples/line/land-temps.csv"
url = "https://raw.githubusercontent.com/chekos/datawrapper/main/tests/samples/line/land-temps.csv"
df = pd.read_csv(url)

chart = dw.LineChart(
Expand All @@ -18,56 +18,59 @@ chart = dw.LineChart(
# Data source attribution
source_name="Berkeley Earth",
source_url="http://berkeleyearth.org/data/",
# Introductory text
intro="Average land temperature in July, in degrees Celsius",
# Chart byline
byline="John Burn-Murdoch",
# Data from pandas DataFrame
data=df,
# Hide X-axis grid lines
x_grid_display="off",
# Show Y-axis grid lines
y_grid_display="on",
# Format Y-axis grid labels with one decimal place
y_grid_format=dw.NumberFormat.ONE_DECIMAL,
# Use monotone interpolation for smooth curves
interpolation=dw.LineInterpolation.MONOTONE,
# Configure the main temperature line
# Set the suffix on our values
transformations=dw.Transform(
column_format=[
dw.ColumnFormat(
column="LandAverageTemperature",
number_append=" °C",
)
]
),
y_grid_format="0",
# Set the range
# Format Y-axis grid labels with no decimal places
custom_range_y=[8, 21],
# And now the tooltip...
tooltip_number_format="00.00",
tooltip_x_format="YYYY",
# Configure the main temperature line's color
color_category={
"LandAverageTemperature": "#1d81a2",
},
lines=[
# Style the main line
dw.Line(
# Column to plot
column="LandAverageTemperature",
# Line color
color="#c71e1d",
# Line width
width=dw.LineWidth.MEDIUM,
# Show symbol on last data point
symbols=dw.LineSymbol(
display=dw.SymbolDisplay.LAST,
size=5
),
# Show value label on last data point
value_labels=dw.LineValueLabel(
last=True
)
)
width=dw.LineWidth.THIN,
interpolation=dw.LineInterpolation.CURVED,
),
# Hide the other two
dw.Line(
column="lower",
width=dw.LineWidth.INVISIBLE,
),
dw.Line(
column="upper",
width=dw.LineWidth.INVISIBLE,
),
],
# Add shaded confidence interval area
area_fills=[
{
"from": "lower",
"to": "upper",
"color": "#cccccc",
"opacity": 0.5
}
dw.AreaFill(
from_column="lower",
to_column="upper",
color="#cccccc",
opacity=0.45,
)
],
)

chart.create()
```

<div style="min-height:433px" id="datawrapper-vis-BsBaq"><script type="text/javascript" defer src="https://datawrapper.dwcdn.net/BsBaq/embed.js" charset="utf-8" data-target="#datawrapper-vis-BsBaq"></script><noscript><img src="https://datawrapper.dwcdn.net/BsBaq/full.png" alt="" /></noscript></div>

## Reference

```{eval-rst}
Expand Down
165 changes: 0 additions & 165 deletions docs/user-guide/charts/multiple-column-charts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,170 +1,5 @@
# MultipleColumnChart

## Example

This example demonstrates how to create a multiple column chart showing the population of the world's largest cities from 1950 to 2035. The chart uses 8 panels (one for each city) with custom HTML-styled titles, highlights the year 2025 in red, and includes text and range annotations.

```python
import pandas as pd
import datawrapper as dw

# Load data from GitHub
url = "https://raw.githubusercontent.com/palewire/datawrapper-api-classes/main/tests/samples/multiple_column/population.csv"
df = pd.read_csv(url)

chart = dw.MultipleColumnChart(
# Chart metadata
title="Population of the world's largest cities, 1950 to 2035",
# Data source attribution
source_name="Our World in Data",
source_url="https://ourworldindata.org/urbanization",
# Data
data=df,
# Grid layout - 4 columns
grid_column=4,
# Fixed row height
grid_row_height=140,
# Y-axis format - abbreviated numbers (e.g., "10M")
y_grid_format=dw.NumberFormat.ABBREVIATED_ONE_DECIMAL,
# Y-axis labels inside the plot area
y_grid_labels="inside",
# X-axis and Y-axis grid lines off
x_grid_display="off",
y_grid_display="off",
# Base color for columns
base_color="#c9a291",
# Highlight 2025 in red
column_color={"2025": "#c71e1d"},
# Category labels for legend
category_labels={"2025": "...for 2025"},
# Exclude all other years from the legend
exclude_from_color_key=[
"1950", "1955", "1960", "1965", "1970", "1975", "1980", "1985",
"1990", "1995", "2000", "2005", "2010", "2015", "2020", "2030", "2035"
],
# Hide the color key
show_color_key=False,
# Panel titles with HTML styling
panel_titles={
"Beijing": "Beijing, <span style=\"color:gray; font-weight: normal;\">China</span>",
"Delhi": "Delhi, <span style=\"color:gray; font-weight: normal;\">India</span>",
"Dhaka": "Dhaka, <span style=\"color:gray; font-weight: normal;\"> Bangladesh </span>",
"Lagos": "Lagos, <span style=\"color:gray; font-weight: normal;\">Nigeria</span>",
"Mumbai (Bombay)": "Mumbai, <span style=\"color:gray; font-weight: normal;\">India</span>",
"New York-Newark": "New York/Newark, <span style=\"color:gray; font-weight: normal;\">U.S.</span>",
"Paris": "Paris, <span style=\"color:gray; font-weight: normal;\">France</span>",
"Tokyo": "Tokyo, <span style=\"color:gray; font-weight: normal;\">Japan</span>",
},
# Text annotations
text_annotations=[
# Projection label for Mumbai
dw.TextAnnotation(
text="Projection",
x="2018/04/30 15:23",
y=36224085.8571,
plot="Mumbai (Bombay)",
dx=-21,
dy=-8,
align="tr",
size=13,
color="#858585",
connector_line=dw.ConnectorLine(
type=dw.ConnectorLineType.STRAIGHT,
stroke=dw.StrokeWidth.THIN
)
),
# Paris 2035 label
dw.TextAnnotation(
text="Paris 2035",
x="1947/07/03 01:00",
y=16409201.2857,
plot="Delhi",
align="tl",
size=13,
color="#858585"
),
# Delhi 2025 population callout
dw.TextAnnotation(
text="<b style=\"color:#b73229\">2025 population:</b>\n34.7M",
x="2023/07/14 22:34",
y=33128010.1429,
plot="Delhi",
dx=-21,
dy=-29,
align="tr",
size=13,
color="#494949",
bg=True,
connector_line=dw.ConnectorLine(
type=dw.ConnectorLineType.STRAIGHT,
stroke=dw.StrokeWidth.THIN,
inherit_color=False
)
),
# Paris growth note
dw.TextAnnotation(
text="Paris grew the most between 1851 to 1856 (by over 20%).",
x="1947/10/03 18:05",
y=43097373.9429,
plot="Paris",
align="tl",
size=13,
color="#494949",
bg=True
),
# Lagos projection note (hidden on mobile/desktop, shown as fallback)
dw.TextAnnotation(
text="Lagos is expected to double in size by 2035 compared to 2015.",
x="1947/07/03 01:00",
y=43096075.7522,
plot="Lagos",
align="tl",
size=13,
color="#494949",
bg=True,
show_mobile=False,
show_desktop=False
),
],
# Range annotations
range_annotations=[
# Horizontal line in Paris panel
dw.RangeAnnotation(
x0="2009/01/23 14:50",
x1="2009/01/23 14:50",
y0=11765087.7143,
y1=13622733.1429,
plot="Paris",
range_type="y",
display="line",
color="#888",
opacity=76,
stroke_type="dotted",
stroke_width=2,
show_in_all_plots=True
),
# Shaded projection period in Mumbai panel
dw.RangeAnnotation(
x0="2018/01/01 13:22",
x1="2037/07/02 01:00",
y0=26626251.1429,
y1=27245466.2857,
plot="Mumbai (Bombay)",
range_type="x",
display="range",
color="#888",
opacity=18,
show_in_all_plots=True
),
],
)

chart.create()
```

<iframe title="Population of the world's largest cities, 1950 to 2035" aria-label="Multiple Columns" id="datawrapper-chart-ZEBmw" src="https://datawrapper.dwcdn.net/ZEBmw/1/" scrolling="no" frameborder="0" style="width: 0; min-width: 100% !important; border: none;" height="460" data-external="1"></iframe><script type="text/javascript">!function(){"use strict";window.addEventListener("message",(function(a){if(void 0!==a.data["datawrapper-height"]){var e=document.querySelectorAll("iframe");for(var t in a.data["datawrapper-height"])for(var r=0;r<e.length;r++)if(e[r].contentWindow===a.source){var i=a.data["datawrapper-height"][t]+"px";e[r].style.height=i}}}))}();
</script>

## Reference

```{eval-rst}
Expand Down
Loading