From 1706d451e0766ee7c506249572e5770e976aa14e Mon Sep 17 00:00:00 2001 From: Matt Stiles Date: Thu, 23 Oct 2025 14:52:53 -0700 Subject: [PATCH] Add documentation examples for ScatterPlot, MultipleColumnChart, and StackedBarChart - Add life expectancy vs GDP example for ScatterPlot - Add population growth example for MultipleColumnChart - Add media trust example for StackedBarChart - All examples drawn from Datawrapper's official docs - Includes embedded iframes and working Python code (tested locally) Closes #458 --- .../charts/multiple-column-charts.md | 81 ++++++++++++ docs/user-guide/charts/scatter-plots.md | 125 ++++++++++++++++++ docs/user-guide/charts/stacked-bar-charts.md | 54 ++++++++ 3 files changed, 260 insertions(+) diff --git a/docs/user-guide/charts/multiple-column-charts.md b/docs/user-guide/charts/multiple-column-charts.md index 7a35b6c..25445b7 100644 --- a/docs/user-guide/charts/multiple-column-charts.md +++ b/docs/user-guide/charts/multiple-column-charts.md @@ -1,5 +1,86 @@ # MultipleColumnChart +This example, drawn from [Datawrapper's official documentation](https://www.datawrapper.de/charts/multiple-columns), demonstrates how to create small multiple column charts showing population growth in major cities from 1950 to 2035. The chart features custom panel titles with country information, highlighted data for 2025, a range annotation to mark the projection period and a 4-column grid layout. + + + +```python +import pandas as pd +import datawrapper as dw + +# Load population data from GitHub +df = pd.read_csv( + "https://raw.githubusercontent.com/chekos/Datawrapper/main/tests/samples/multiple_column/population.csv", + sep="\t" +) + +chart = dw.MultipleColumnChart( + # Chart title + 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 from pandas DataFrame + data=df, + # Layout configuration - 4 columns on desktop, 2 on mobile + grid_layout="fixedCount", + grid_column=4, + grid_column_mobile=2, + grid_row_height=140, + # Sort panels by end value (2035 population) in descending order + sort=True, + sort_by="end", + sort_reverse=False, + # Set custom column color with highlighted year for 2025 + base_color="#c9a291", + color_category={ + "2025": "#c71e1d" + }, + # Format y-axis with abbreviated numbers + y_grid_format=dw.NumberFormat.ABBREVIATED_ONE_DECIMAL, + y_grid_labels="inside", + y_grid_label_align="left", + # Custom panel titles with city and country information + panels=[ + {"column": "Delhi", "title": "Delhi, India"}, + {"column": "Dhaka", "title": "Dhaka, Bangladesh "}, + {"column": "Lagos", "title": "Lagos, Nigeria"}, + {"column": "Paris", "title": "Paris, France"}, + {"column": "Tokyo", "title": "Tokyo, Japan"}, + {"column": "Beijing", "title": "Beijing, China"}, + {"column": "Mumbai (Bombay)", "title": "Mumbai, India"}, + {"column": "New York-Newark", "title": "New York/Newark, U.S."}, + ], + # Add text annotation to label the projection period + text_annotations=[ + { + "text": "2025", + "x": "2023/01/01", + "y": 30000000, + "align": "tc", + "color": "#b73229", + "size": 14, + "bold": True, + }, + ], + # Add range annotation to highlight projection period + range_annotations=[ + { + "x0": "2018/01/01", + "x1": "2037/07/02", + "y0": 0, + "y1": 50000000, + "display": "range", + "color": "#888", + "opacity": 18, + }, + ], +) + +# Create the chart in Datawrapper +chart.create() +``` + ## Reference ```{eval-rst} diff --git a/docs/user-guide/charts/scatter-plots.md b/docs/user-guide/charts/scatter-plots.md index 8a9e3da..dc19258 100644 --- a/docs/user-guide/charts/scatter-plots.md +++ b/docs/user-guide/charts/scatter-plots.md @@ -1,5 +1,130 @@ # ScatterPlot +This example, drawn from [Datawrapper's official documentation](https://www.datawrapper.de/charts/scatter-plot), demonstrates how to create a scatter plot showing the relationship between GDP per capita and life expectancy over time. The chart uses bubble size to represent population and features text annotations to label specific countries and years. + + + +```python +import pandas as pd +import datawrapper as dw + +# Load life expectancy data from GitHub +df = pd.read_csv( + "https://raw.githubusercontent.com/chekos/Datawrapper/main/tests/samples/scatter/life-expectancy.csv", + sep="\t" +) + +chart = dw.ScatterPlot( + # Chart title + title="Every country has a higher life expectancy now than in 1800", + # Introductory text explaining the visualization + intro="Gross domestic product per person adjusted for differences in purchasing power (in international 2011 dollars) vs life expectacy of newborns, for selected countries in 1800 and 2015. The size of the circle shows the population of the countries.", + # Data source attribution + source_name="Gapminder", + source_url="https://www.gapminder.org/data/", + # Author credit + byline="Lisa Charlotte Muth, Datawrapper", + # Data from pandas DataFrame + data=df, + # Define which columns to use for each dimension + x_column="GPD", + y_column="Health", + size_column="population", + label_column="country", + # Use logarithmic scale for x-axis (GDP) + x_log=True, + # Set custom range for axes + x_range=[200, ""], + y_range=[0, 94], + # Format axis labels + x_format="0a", # Abbreviated format (e.g., "10k") + y_format="0a", + # Configure bubble size + size="dynamic", + max_size=60, + # Set opacity for better visibility of overlapping bubbles + opacity=0.6, + # Set base color for all points + base_color="#15607a", + # Set fixed plot height + plot_height_fixed=581, + # Disable automatic labeling (we'll add custom text annotations) + auto_labels=False, + # Custom tooltip format + tooltip_title='{{ country }} in {{ FORMAT(year, "YYYY") }}', + tooltip_body=""" + + + + + + + + +
Life expectancy:   GDP per capita:
{{ health }} years{{ FORMAT(gdp, "0,0") }} Int'l$
""", + # Add text annotations to label years and key countries + text_annotations=[ + { + "text": "1800", + "x": 156700, + "y": 45, + "align": "tr", + "dx": -14, + "dy": 13, + "bold": True, + "size": 18, + }, + { + "text": "2015", + "x": 156700, + "y": 92, + "align": "tr", + "dx": -14, + "dy": 13, + "bold": True, + "size": 18, + }, + { + "text": "China", + "x": "13398.7010", + "y": "76.1317", + "align": "mc", + "color": "#000000", + "size": 13, + }, + { + "text": "India", + "x": "5997.2352", + "y": "67.2308", + "align": "mc", + "color": "#000000", + "size": 13, + }, + { + "text": "Somalia", + "x": 620, + "y": 55.5, + "align": "tl", + "dx": 10, + "dy": -1, + "color": "#000000", + "size": 13, + }, + { + "text": "US", + "x": "53787.2503", + "y": "79.0931", + "align": "mc", + "color": "#000000", + "size": 13, + }, + ], +) + +# Create the chart in Datawrapper +chart.create() +``` + ## Reference ```{eval-rst} diff --git a/docs/user-guide/charts/stacked-bar-charts.md b/docs/user-guide/charts/stacked-bar-charts.md index 002e8e4..023e012 100644 --- a/docs/user-guide/charts/stacked-bar-charts.md +++ b/docs/user-guide/charts/stacked-bar-charts.md @@ -1,5 +1,59 @@ # StackedBarChart +This example, drawn from [Datawrapper's official documentation](https://www.datawrapper.de/charts/stacked-bars), demonstrates how to create a diverging stacked bar chart showing trust levels in media reporting across different topics. The chart displays percentages with a [custom color scheme](https://colorbrewer2.org/#type=diverging&scheme=PRGn&n=5) to differentiate between trust levels, sorted by low trust values. It also includes value formatting. + + + +```python +import pandas as pd +import datawrapper as dw + +# Load media trust data from GitHub +df = pd.read_csv( + "https://raw.githubusercontent.com/chekos/Datawrapper/main/tests/samples/stacked_bar/media-trust.csv", + sep=";" +) + +chart = dw.StackedBarChart( + # Chart title + title="Trust in Media Reporting", + # Introductory text explaining the context + intro="Trust in Media Reporting regarding widely reported topics of 2015", + # Data source attribution + source_name="Infratest dimap", + source_url="http://www.infratest-dimap.de/umfragen-analysen/bundesweit/umfragen/aktuell/wenig-vertrauen-in-medienberichterstattung/", + # Data from pandas DataFrame + data=df, + # Display values as percentages + stack_percentages=True, + # Format value labels as percentages + value_label_format="0%", + # Use diverging mode for better visual separation + value_label_mode="diverging", + # Sort bars by the "Low trust" column in descending order + sort_bars=True, + sort_by="Low trust", + reverse_order=True, + # Enable the color legend + show_color_key=True, + # Use thick bars for better visibility + thick_bars=True, + # Use block labels for category names + block_labels=True, + # Custom color mapping for each trust level + color_category={ + "Very high trust": "#15607a", + "High trust": "#719aae", + "No answer": "#e8e8e8", + "Low trust": "#ff6954", + "Very low trust": "#c71e1d", + }, +) + +# Create the chart in Datawrapper +chart.create() +``` + ## Reference ```{eval-rst}