ColumnChart

This example, drawn from the Datawrapper documentation, demonstrates how to customize a column chart with annotations and custom colors.

import pandas as pd
import datawrapper as dw

# Load unemployment data from GitHub
url = "https://raw.githubusercontent.com/chekos/datawrapper/main/tests/samples/column/unemployment.csv"
df = pd.read_csv(url)

chart = dw.ColumnChart(
    # 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/",
    # Data from pandas DataFrame
    data=df,
    # Format labels with one decimal place and a percentage sign
    y_grid_format=dw.NumberFormat.PERCENT_UP_TO_ONE_DECIMAL,
    value_labels_format=dw.NumberFormat.PERCENT_UP_TO_ONE_DECIMAL,
    # Highlight specific columns with custom colors
    base_color="#CCCCCC",
    color_category={
        "2020/04": "rgb(21, 96, 122)",
        "2020/05": "rgb(21, 96, 122)",
        "2020/06": "rgb(21, 96, 122)",
        "2020/07": "rgb(21, 96, 122)",
        "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",
            x1="2020/09/30",
            color="#777777",
            opacity=10,
            type="x",
        )
    ],
    text_annotations=[
        dw.TextAnnotation(
            x="2020/04/01",
            y=14,
            dx=-50,
            dy=50,
            text="In <b>April 2020</b>, the unemployment rate rose to almost <b>15%</b>.",
            align="tr",
            size=14,
            color="rgb(21, 96, 122)",
            connector_line=dw.ConnectorLine(
                color="rgb(21, 96, 122)",
                type=dw.ConnectorLineType.CURVE_RIGHT,
            ),
        )
    ],
)

chart.create()

Reference

Parameter	Default	Description	Type
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
bar_padding	30	The padding between bars as a percentage of the bar width	int
base_color	0	The base color for the chart (palette index or hex string)	str or int
byline	“”	The byline that appears below the chart	str
category_labels	PydanticUndefined	Dictionary mapping category names to their display labels in the color legend	dict[str, str]
category_order	PydanticUndefined	List defining the order in which categories appear in the chart and legend	list[str]
chart_id	None	The chart ID after creation (populated by create() method)	str or None
chart_type	“column-chart”	The type of datawrapper chart to create	Literal[column-chart]
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
exclude_from_color_key	PydanticUndefined	A list of columns to exclude from the color key	list[str]
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
highlighted_series	PydanticUndefined	A list of the highlighted series	list[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
negative_color	None	The negative color to use, if you want one	str or None
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_value_labels	“hover”	Whether or not to show value labels	ValueLabelDisplay (HOVER, ALWAYS, OFF) or str
source_name	“”	The source name that appears below the chart	str
source_url	“”	The source URL that appears below the chart	str
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
transformations	PydanticUndefined		Transform or dict[str, Any]
value_labels_format	“”	How to format the value labels. 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
value_labels_placement	“outside”	Where to place the value labels	ValueLabelPlacement (INSIDE, OUTSIDE, BELOW) or str
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	“outside”	The labeling of the y grid labels	GridLabelPosition (AUTO, INSIDE, OUTSIDE, …) or str