AreaChart

This example, drawn from Datawrapper’s official documentation, demonstrates how to create a stacked area chart. The chart includes text and range annotations to highlight significant events. It also customizes the color scheme for different regions and formats the axes and value labels for better readability.

import pandas as pd
import datawrapper as dw

# Load migration data from GitHub
df = pd.read_csv(
    "https://raw.githubusercontent.com/chekos/Datawrapper/main/tests/samples/area/migration.csv"
)

chart = dw.AreaChart(
    # The headline of the chart
    title="Migration to the US by world region, 1820-2009",
    # Introductory text explaining the data
    intro="The numbers are recorded by decade. For example, the numbers recorded for 1905 tell us the number of immigrants between 1900 and 1910.",
    # Data source attribution below the chart
    source_name="Department of Homeland Security",
    # URL to the original data source, linked in the chart's source attribution
    source_url="http://metrocosm.com/wp-content/uploads/2016/05/usa-immigration-data.xlsx",
    # Attribute of the author below the chart
    byline="Mirko Lorenz",
    # The DataFrame containing the source data
    data=df,
    # Transpose the data with a transformation
    transformations=dict(transpose=True),
    # Format x-axis labels as full years (e.g., "2020").
    # Alternatively, you could provide "YYYY" if you'd rather not use the DateFormat enum.
    x_grid_format=dw.DateFormat.YEAR_FULL,
    # Format y-axis labels with abbreviated numbers (e.g., "1.2m")
    # Alternatively, you could provide "0.[00]a" if you'd rather not use the NumberFormat enum.
    y_grid_format=dw.NumberFormat.ABBREVIATED_TWO_DECIMALS,
    # Align the y-axis labels to the right
    y_grid_label_align="right",
    # We always want the decimals for the tooltip number, but otherwise the same
    tooltip_number_format="0.00a",
    # Whether to stack the areas on top of each other
    stack_areas=True,
    # Use smooth curves between data points
    interpolation=dw.LineInterpolation.CURVED,
    # Set fixed plot height in pixels
    plot_height_fixed=388,
    # Map each region/country to a specific color
    color_category={
        "Austria-Hungary": "#1d81a2",
        "Germany": "#004765",
        "Ireland": "#3a96b8",
        "Italy": "#48adc0",
        "Norway and Sweden": "#2b8589",
        "Russia": "#329a9b",
        "United Kingdom": "#257085",
        "Rest of Europe": "#005d71",
        "Europe": "#00658d",
        "China": "#b4241c",
        "India": "#cd3d2e",
        "Philippines": "#dc464b",
        "Rest of Asia": "#E65340",
        "Asia": "#e65341",
        "Canada and Newfoundland": "#ffa126",
        "Mexico": "#ffca76",
        "Caribbean": "#ffe59c",
        "Central America": "#ffdc6b",
        "South America": "#ffbb7f",
        "Rest of America": "#fffbb1",
        "Africa": "#009a69",
        "Oceania": "#003f65",
        "Not Specified": "#181818",
    },
    # Text annotations to label regions and events
    text_annotations=[
        dw.TextAnnotation(
            text="E U R O P E",
            x="1896/07/27 16:00",
            y=1329923.3141,
            align="mc",
            color="#fefefe",
            bold=True,
            size=20,
            outline=False,
        ),
        dw.TextAnnotation(
            text="A S I A ",
            x="2000M5",
            y=2500000,
            align="mr",
            color="#121212",
            bold=True,
            size=14,
            outline=False,
        ),
        dw.TextAnnotation(
            text="A M E -\nR I C A",
            x="1994/08/01 20:41",
            y=6134172.0713,
            align="mc",
            color="#222222",
            bold=True,
            size=10,
            outline=False,
        ),
        dw.TextAnnotation(
            text="Germany",
            x="1851/01/04 01:21",
            y=439746.2628,
            align="ml",
            color="#d2d2d2",
            italic=True,
            size=11,
            outline=False,
        ),
        dw.TextAnnotation(
            text="World <br/>War I",
            x="1914M07",
            y=8000000.000000002,
            align="tl",
            dx=3,
            color="#575757",
            italic=True,
            size=11,
            outline=False,
        ),
        dw.TextAnnotation(
            text="World <br/>War II",
            x="1939M09",
            y=3000000.000000002,
            align="tl",
            dx=3,
            color="#575757",
            italic=True,
            size=11,
            outline=False,
        ),
    ],
    range_annotations=[
        # World War I period (1914-1918)
        dw.RangeAnnotation(
            x0="1914M07",
            x1="1918M11",
            color="#333333",
            opacity=14,
        ),
        # World War II period (1939-1945)
        dw.RangeAnnotation(
            x0="1939M09",
            x1="1945M09",
            color="#333333",
            opacity=10,
        ),
    ],
)

# Create the chart in Datawrapper
chart.create()

Reference

Parameter	Default	Description	Type
area_opacity	0.8	The opacity of the areas	float
area_separator_color	“#4682b4”	The color of the separator lines between areas	str or int
area_separator_lines	False	Whether or not to show separator lines between areas	bool
aria_description	“”	The alternative text for screen readers	str
auto_dark_mode	False	Whether the chart should automatically flip to dark mode when the user’s system is in dark mode	bool
base_color	0	The base color for layers (palette index or hex string)	str or int
byline	“”	The byline that appears below the chart	str
chart_id	None	The chart ID after creation (populated by create() method)	str or None
chart_type	“d3-area”	The type of datawrapper chart to create	Literal[d3-area]
color_category	PydanticUndefined	A mapping of layer names to colors	dict[str, str]
custom	PydanticUndefined	A dictionary of custom tags to attach to the chart	dict[str, Any]
custom_range_x	None	Custom range for X-axis as [min, max]. Overrides automatic range calculation.	list[Any] or tuple[Any, Any] or None
custom_range_y	None	Custom range for Y-axis as [min, max]. Overrides automatic range calculation.	list[Any] or tuple[Any, Any] or None
custom_ticks_x	None	Custom tick mark positions for X-axis. List of values where ticks should appear.	list[Any] or None
custom_ticks_y	None	Custom tick mark positions for Y-axis. List of values where ticks should appear.	list[Any] or None
dark_mode_invert	True	Whether to invert colors in dark mode	bool
data	PydanticUndefined	The data to use for the chart	DataFrame or list[dict]
download_image	False	Whether to allow PNG download	bool
download_pdf	False	Whether to allow PDF download	bool
download_svg	False	Whether to allow SVG download	bool
embed	False	Whether to allow embedding	bool
force_attribution	False	Whether to attribute the chart to datawrapper	bool
forkable	True	Whether to allow other users to fork this visualization	bool
get_the_data	False	Whether to allow data downloads	bool
hide_title	False	Whether or not to hide the title	bool
interpolation	“linear”	The interpolation method to use when drawing lines	LineInterpolation (LINEAR, STEP, STEP_AFTER, …) or str
intro	“”	The intro text that appears above the chart	str
language	“en-US”	The locale of the chart, which defines decimal and thousand separators as well as translations of month and weekday names.	str
logo	False	Whether to show a logo	bool
logo_id	“”	The id of the logo to show	str
notes	“”	The footnotes that appear below the chart	str
plot_height_fixed	300	The fixed height of the plot	int or float
plot_height_mode	“fixed”	How to set the plot height	PlotHeightMode (FIXED, RATIO) or str
plot_height_ratio	0.5	The ratio of the plot height	float
range_annotations	PydanticUndefined	A list of range annotations to display on the chart	Sequence[UnionType[RangeAnnotation, dict[Any, Any]]]
share_buttons	False	Whether to show social media share buttons	bool
share_url	“”	What URL to share	str
show_color_key	False	Whether or not to show the color key above the chart	bool
show_tooltips	True	Whether or not to show tooltips on hover	bool
sort_areas	“keep”	How to sort area layers	Literal[keep, asc, desc]
source_name	“”	The source name that appears below the chart	str
source_url	“”	The source URL that appears below the chart	str
stack_areas	False	Whether or not to stack areas	bool
stack_to_100	False	Whether or not to stack areas to 100%	bool
text_annotations	PydanticUndefined	A list of text annotations to display on the chart	Sequence[UnionType[TextAnnotation, dict[Any, Any]]]
theme	“datawrapper”	The theme of the chart	str
title	“”	The headline that appears above the chart	str
tooltip_number_format	“”	The format of the number tooltip. Use DateFormat for temporal data, NumberFormat for numeric data, or provide custom format strings.	DateFormat (AUTO, YEAR_FULL, YEAR_TWO_DIGIT, …) or NumberFormat (AUTO, THOUSANDS_WITH_OPTIONAL_DECIMALS, INTEGER, …) or str
tooltip_x_format	“”	The format for the x-axis tooltips. Use DateFormat for temporal data, NumberFormat for numeric data, or provide custom format strings.	DateFormat (AUTO, YEAR_FULL, YEAR_TWO_DIGIT, …) or NumberFormat (AUTO, THOUSANDS_WITH_OPTIONAL_DECIMALS, INTEGER, …) or str
transformations	PydanticUndefined		Transform or dict[str, Any]
x_grid	“off”	X-axis grid display setting. Controls vertical grid lines.	GridDisplay (OFF, ON, TICKS, …) or str or bool or None
x_grid_format	None	Format string for X-axis grid labels. Supports date and number formats.	DateFormat (AUTO, YEAR_FULL, YEAR_TWO_DIGIT, …) or NumberFormat (AUTO, THOUSANDS_WITH_OPTIONAL_DECIMALS, INTEGER, …) or str or None
y_grid	“on”	Y-axis grid display setting. Controls horizontal grid lines.	GridDisplay (OFF, ON, TICKS, …) or str or bool or None
y_grid_format	None	Format string for Y-axis grid labels. Supports number formats.	NumberFormat (AUTO, THOUSANDS_WITH_OPTIONAL_DECIMALS, INTEGER, …) or str or None
y_grid_label_align	“left”	Which side to put the y-axis labels on	GridLabelAlign (LEFT, RIGHT) or str
y_grid_labels	“auto”	The labeling of the y grid labels	GridLabelPosition (AUTO, INSIDE, OUTSIDE, …) or str