From f204a769430f88ea99e11ed3e0be9b53123d02c8 Mon Sep 17 00:00:00 2001 From: Ben Welsh Date: Mon, 20 Oct 2025 00:18:13 +0000 Subject: [PATCH] refactor: update documentation for various chart examples with improved clarity and structure --- docs/user-guide/charts/column-charts.md | 12 +- docs/user-guide/charts/line-charts.md | 81 ++++----- .../charts/multiple-column-charts.md | 165 ------------------ docs/user-guide/charts/scatter-plots.md | 102 ----------- docs/user-guide/charts/stacked-bar-charts.md | 58 ------ 5 files changed, 48 insertions(+), 370 deletions(-) diff --git a/docs/user-guide/charts/column-charts.md b/docs/user-guide/charts/column-charts.md index 83609c9..80d8a49 100644 --- a/docs/user-guide/charts/column-charts.md +++ b/docs/user-guide/charts/column-charts.md @@ -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)", @@ -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", diff --git a/docs/user-guide/charts/line-charts.md b/docs/user-guide/charts/line-charts.md index aa48ad8..9f1844f 100644 --- a/docs/user-guide/charts/line-charts.md +++ b/docs/user-guide/charts/line-charts.md @@ -1,15 +1,15 @@ # LineChart -## Example +This example, drawn from the Datawrapper documentation, 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. + ```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( @@ -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() ``` -
- ## Reference ```{eval-rst} diff --git a/docs/user-guide/charts/multiple-column-charts.md b/docs/user-guide/charts/multiple-column-charts.md index 273f8db..7a35b6c 100644 --- a/docs/user-guide/charts/multiple-column-charts.md +++ b/docs/user-guide/charts/multiple-column-charts.md @@ -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, China", - "Delhi": "Delhi, India", - "Dhaka": "Dhaka, Bangladesh ", - "Lagos": "Lagos, Nigeria", - "Mumbai (Bombay)": "Mumbai, India", - "New York-Newark": "New York/Newark, U.S.", - "Paris": "Paris, France", - "Tokyo": "Tokyo, Japan", - }, - # 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="2025 population:\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() -``` - - - ## Reference ```{eval-rst} diff --git a/docs/user-guide/charts/scatter-plots.md b/docs/user-guide/charts/scatter-plots.md index 71b369d..8a9e3da 100644 --- a/docs/user-guide/charts/scatter-plots.md +++ b/docs/user-guide/charts/scatter-plots.md @@ -1,107 +1,5 @@ # ScatterPlot -## Example - -This example recreates a scatter plot showing student cities in Germany, with dynamic sizing based on the number of students and color-coded by the share of students in the population. - -```python -import pandas as pd -import datawrapper as dw - -# Load data from GitHub -df = pd.read_csv( - "https://raw.githubusercontent.com/palewire/Datawrapper/main/tests/samples/scatter/german-students.csv" -) - -# Create scatter plot -chart = dw.ScatterPlot( - # Chart title - title="What are the student cities in Germany?", - # Intro text with HTML formatting - intro="There were 2.807.000 students in Germany in 2016. Where were they based, and which cities had the highest share of students? The size of the circle represents the number of students in these cities. The darker the circle, the higher the share of students.", - # Data source attribution - source_name="Eurostat 2016", - source_url="https://ec.europa.eu/eurostat/statistics-explained/index.php?title=Statistics_on_European_cities/de#Bildung_und_Besch.C3.A4ftigung", - # Byline - byline="Lisa Charlotte Muth, Datawrapper", - # Data - data=df, - # X-axis: Number of students - x_column="students", - # Y-axis: Share of students in % - y_column="percent", - # Size: Dynamic sizing based on number of students - size_column="students", - # Color: Color by student percentage category - color_column="color", - # Labels: City names - label_column="city", - # X-axis range - x_axis_min=0, - x_axis_max=200000, - # Y-axis range - y_axis_min=0, - y_axis_max=52, - # X-axis format (abbreviated numbers) - x_grid_format=dw.NumberFormat.ABBREVIATED, - # Y-axis format (integer) - y_grid_format=dw.NumberFormat.INTEGER, - # X-axis grid lines - x_grid_lines=dw.ScatterGridLines.ON, - # Y-axis grid lines - y_grid_lines=dw.ScatterGridLines.ON, - # Color category mapping for student percentage ranges - color_category={ - "less than 5%": "#A8DA9B", - "5-10%": "#96C797", - "10%-20%": "#78AA91", - "more than 20%": "#406274", - }, - # Category order for legend - category_order=["less than 5%", "5-10%", "10%-20%", "more than 20%"], - # Show color legend - show_color_key=True, - # Dynamic point sizing - size_mode="dynamic", - # Maximum point size - max_size=33.85, - # Custom tooltip with HTML table - tooltip_title="{{ city }}", - tooltip_body='\n \n \n \n \n \n \n \n \n\n
Population:   Students:
{{ pop }}{{ students }}
\n
\n{{ percent }}% of the population are students.', - # Enable tooltips - tooltip_enabled=True, - # Plot height (fixed) - plot_height=357, - # Text annotations for axis labels - text_annotations=[ - dw.TextAnnotation( - # Label for Y-axis - text="↑\nhigher share \nof students", - x=146367.9122, - y=41.1759, - align="br", - bold=True, - size=14, - ), - dw.TextAnnotation( - # Label for X-axis - text="more \nstudents\nlive in these \ncities\n→", - x=153803.5969, - y=38.7234, - align="tl", - bold=True, - size=14, - ), - ], -) - -# Create the chart -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 5753d13..002e8e4 100644 --- a/docs/user-guide/charts/stacked-bar-charts.md +++ b/docs/user-guide/charts/stacked-bar-charts.md @@ -1,63 +1,5 @@ # StackedBarChart -## Example - -This example recreates a stacked bar chart showing trust in media reporting on various topics in Germany, with percentages stacked to show the distribution of trust levels. - -```python -import pandas as pd -import datawrapper as dw - -# Load data from GitHub -df = pd.read_csv( - "https://raw.githubusercontent.com/palewire/Datawrapper/main/tests/samples/stacked_bar/media-trust.csv", - sep=";" -) - -# Create stacked bar chart -chart = dw.StackedBarChart( - # Chart title - title="How much do you trust the media reporting on the following topics?", - # Intro text - intro="Survey of 1,002 Germans, conducted in January 2016", - # Data source attribution - source_name="Infratest dimap for NDR", - source_url="https://www.tagesschau.de/inland/deutschlandtrend/", - # Byline - byline="Lisa Charlotte Muth, Datawrapper", - # Data - data=df, - # Stack as percentages - stack_percentages=True, - # Value label format (percentage) - value_labels_format=dw.NumberFormat.PERCENT_INTEGER, - # Color category mapping for trust levels - color_category={ - "Very high trust": "#15607a", - "High trust": "#5b9bae", - "No answer": "#cccccc", - "Low trust": "#d8b365", - "Very low trust": "#8c510a", - }, - # Category order for legend - category_order=[ - "Very high trust", - "High trust", - "No answer", - "Low trust", - "Very low trust", - ], - # Don't sort bars (keep original order) - sort_bars=False, -) - -# Create the chart -chart.create() -``` - - - ## Reference ```{eval-rst}