Excel Accessible Chart Examples

Code examples showing how to make the charts in an Excel workbook (.xlsx) accessible with py-maidr: every Excel chart type, from column, line and pie charts to stock charts, histograms, box and whisker charts, waterfalls and treemaps, read from the file without Excel.

Excel Examples

maidr reads the charts of an Excel workbook. Pass an .xlsx or .xlsm file to maidr.read_excel_charts(), and hand any chart it returns to maidr.show(), maidr.render() or maidr.save_html(): the chart can then be read from the keyboard, as sound, as text and in braille. Excel does not need to be installed. For charts drawn in Python, see the Matplotlib / Seaborn, Plotly, Bokeh, plotnine and Altair pages.

Experimental

Excel support is experimental. What it reads, and how, may change without a deprecation period, whichever chart type is read: see Plot Type Stability.

Every chart Excel saves keeps a copy of the values it drew inside the file, and maidr reads that copy, so the reader hears the numbers the chart shows; the cells are read only where a file has no copy, as some programs other than Excel write them. Each chart is then drawn again with matplotlib, in the workbook’s own colors and with its own titles, and the mark being read is outlined on that drawing. The drawing is not Excel’s picture of the chart: fonts and effects differ.

Every chart type Excel draws is read:

Excel chart	read as
Column or bar, one series	bar
Clustered column or bar	dodged bar
Stacked and 100% stacked column or bar	stacked bar; 100% stacked reads each segment’s share
Line, with or without markers	line, one series per line
Pie and doughnut	pie, clockwise from the top
Pie-of-pie and bar-of-pie	a pie with the gathered slice, Other, and beside it a pie or a stacked column of what it gathers
Scatter	point; with lines, line
Bubble	point, with each bubble’s size as its z
Stock: high-low-close and open-high-low-close, with or without volume	candlestick; the volume also as a bar layer of its own
Surface, as its contour view	heat, a row per series
Histogram	histogram, binned as Excel bins it; by category, bar
Pareto	bar, largest first, and the running share as a line on a second axis
Box and whisker	box, with Excel’s quartiles
Combo, including a second value axis	one layer per chart type in one chart
Area, stacked and 100% stacked area	area [experimental], stacked area [experimental]
Stacked and 100% stacked line	stacked area [experimental]
Radar, with markers and filled	radar [experimental]
Waterfall	waterfall [experimental]
Funnel	funnel [experimental]
Treemap	treemap [experimental]
Sunburst	sunburst [experimental]
Map	choropleth [experimental], a list of the regions

3-D charts read as their flat counterparts. A map is read as the list of its regions and their values and drawn as bars: maidr does not draw the shapes of the regions.

An axis Excel draws no title on is named after the header cell above its categories, such as Quarter: you hear it, and the drawing leaves it off as Excel does. A value axis keeps its number format, so a percentage reads as one. Dates read the way the cells show them. A category with no label reads (blank), and a blank value is a gap, never a zero.

The examples read sales.xlsx, a workbook with a sheet of quarterly sales and its charts, and sheets of share prices, test scores, a budget and product sales, each with a chart of its own.

Reading a Workbook

maidr.read_excel_charts() returns the charts sheet by sheet and, on each sheet, top to bottom and left to right, each with the sheet it is on, its name and its title.

import maidr

charts = maidr.read_excel_charts("sales.xlsx")
for chart in charts:
    print(chart.sheet, chart.name, chart.title, sep=" | ")

Sales | Chart 1 | Revenue by region
Sales | Chart 2 | Revenue trend
Sales | Chart 3 | North by quarter
Sales | Chart 4 | North revenue and margin
Sales | Chart 5 | Revenue, stacked
Sales | Chart 6 | Revenue around the year
Prices | Chart 1 | Share price, first week of January
Scores | Chart 1 | Scores, both classes
Scores | Chart 2 | Scores by class
Budget | Chart 1 | Cash flow
Products | Chart 1 | Sales by product

Save every chart of a workbook as its own page with a loop:

for chart in maidr.read_excel_charts("sales.xlsx"):
    maidr.save_html(chart, f"{chart.name}.html")

maidr.read_excel_charts() also takes an open binary file, such as the one a Streamlit or Shiny upload control hands you.

Clustered Column Chart

Each region is a series and each quarter a category: the left and right arrow keys move between quarters, and up and down between the regions.

maidr.show(charts[0])

Line Chart

maidr.show(charts[1])

Pie Chart

maidr.show(charts[2])

Combo Chart on Two Axes

North’s revenue is drawn as columns and its margin as a line on a second value axis. The two are layers of one chart: Page Up and Page Down move between them. The margin is read as a percentage, because its cells are formatted as one.

maidr.show(charts[3])

Stock Chart

An open-high-low-close chart with Excel’s up and down bars reads as candles: left and right move between days, and up and down between the open, high, low and close of a day.

maidr.show(charts[6])

Histogram

A histogram’s file keeps the scores, not the bins, so maidr bins them as Excel does: here ten points wide, as the chart says, each bin including its right end.

maidr.show(charts[7])

Box and Whisker Chart

One box per class. The quartiles are worked out as Excel works them out, and a whisker reaches the furthest score within one and a half interquartile ranges of its box.

maidr.show(charts[8])

Stacked Area Chart [experimental]

maidr.show(charts[4])

Radar Chart [experimental]

Each quarter is a spoke, clockwise from the top, and each region a series: left and right move around the spokes, and up and down between the regions.

maidr.show(charts[5])

Waterfall Chart [experimental]

The opening and closing balances are set as totals in Excel, so each is read from zero; every step between them is read from the running total.

maidr.show(charts[9])

Treemap [experimental]

Each category is a branch and each product a leaf: up and down move between a branch and its products, and left and right between the nodes of a level.

maidr.show(charts[10])