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.
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.
| 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 |
| Scatter | point; with lines, line |
| 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 line, radar, bubble, stock, surface and pie-of-pie charts, and the chart types Excel 2016 added (histogram, Pareto, box and whisker, waterfall, funnel, treemap, sunburst and map), are left out with a warning naming the chart and its sheet.
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 one sheet of quarterly sales and five charts.
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.
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, stackedSave every chart of a workbook as its own page with a loop:
maidr.read_excel_charts() also takes an open binary file, such as the one a Streamlit or Shiny upload control hands you.
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.
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.