Web-accessibility engine for rendering accessible, interactive charts optimized for screen reader users.
Resides in the ./src/ directory. This engine is built from source code using npm or yarn. The build outputs to ./build/ as bundled *.js file.
This repository requires the yarn package manager.
Then install the package dependencies and build the Chart Reader engine:
yarn installyarn run buildbuilds to./build/as bundled*.jsfile.
Chart Reader is created with open source libraries, using d3 for data binding and a modified version of susielu/react-annotation for annotation layout.
Chart Reader is an accessibility engine that renders an SVG chart to a web page using three inputs:
- a data file in CSV format
- an insights list in JSON format
- a Chart Reader configuration in JSON format
The data file and insights list describe the content of the accessible chart, while the Chart Reader configuration declares how the chart renders the accessible experience.
The documentation uses a multi-series line chart about "Potholes Reported in Seattle and Atlanta" as an example.
For the input CSV data file, Chart Reader supports the following data fields: number, string, datetime, date, time.
The engine expects data to be complete and tidy: it does not support missing values.
The insights JSON structure is inspired by the d3-annotation spec. Four fields are necessary for Chart Reader to include insights:
-
title- textual description to be read first. Thetitleshould summarize the insight as a headline. -
label- textual description read second. Details the insight content. Each insight should follow a similar format and structure to other insights of the sametype
{
"note": {
"title": [
"Most Potholes Reported in New York, 2018"
],
"label": [
"In the winter of 2018, New York sees its largest number of ",
"potholes reported, reaching a peak of close to 3500 potholes in March. "
]
},
}target- the data targeted by the insight, specified by the axis and values under selection.
{
"target": {
"axis": "x",
"values": ["2020-03-01", "2020-04-10"],
"series": ["Seattle"]
},
}a. axis - the axis to make the target selection along. Restricted to x and y literals.
b. values - an array that selects the target values. Should be start and end values of a range for linear data (e.g., number, datetime, date, time). Should be unique list of values in the case string data.
c. series - an array that selects which series to include. Only for multi-series charts.
type- describes how the insight should be grouped (e.g., "Summary", "Trends", "Landmarks", "Statistics"). Insighttypesarestringsto be set ad-hoc by including new types in the file: Chart Reader will group any insights together with the same type.
{
"type": "landmarks",
}dxanddy- optional fields that relatively place the visual text of the insight with respect to thetarget.
{
"dx": 30,
"dy": -60,
}Chart Reader supports four chart types: single-series line, multi-series line, stacked bar, and grouped bar. The configuration is a JSON object that declares the encodings of the chart. The configuration is flexible in how it encodes data, which data types are suppported, and how values can be read by the Screen Reader.
The configuration requires description, insights, and data objects that describe the makeup of the chart.
description- describes thetitleused to first announce the chart, and thecaptionused to describe the syntactic aspects of the chart. Note that the summary insight goes into more detail about describing the chart's content.
{
"description": {
"title": "Potholes Reported in Seattle and New York City",
"caption": "Line chart displaying potholes reported each month in Seattle and New York City (NYC) from January 2017 to March 2022."
},
}insights- aurlpointing towards the JSON file containing the Insights List described above.
{
"annotations": {
"url": "./assets/chart/seattle_and_nyc_pothole_insights.json"
},
}data- describes the input data in a digestible format for Chart Reader. This JSON Object includes theurlto the CSV data file and how to parse the datafields. Eachfieldincludes an object describing thenameof a column in the CSV data file, the datatype, and theformat. Theformatis only required fordatetime,date, ortimedata and follows d3 time format.
{
"data": {
"url": "./assets/chart/seattle_and_nyc_potholes.csv",
"fields": [
{
"name": "date",
"type": "date",
"format": "%Y-%m-%d"
},
{
"name": "seattle",
"type": "number"
},
{
"name": "nyc",
"type": "number"
}
]
},
}The configuration also includes encoding attributes for x, y, and z axes, respectively. The x and y objects are required for all chart types, while the z object is only required for multi-series charts.
x,y,z- describes the encoding of the along that axis. The object includes thenameof the column in the CSV data file, thetypeof data, thelabel_axisto be read by the Screen Reader, thelabel_groupto be read by the Screen Reader, theaggregatefunction to be applied to the data, and theperiodto describe equally spaced temporal data, andintervalto be used toaggregatealong the axis. Theperiodis only required fordatetime,date, ortimedata.
{
"x": {
"name": "date",
"type": "date",
"label_axis": "Time (in months)",
"label_group": "average potholes",
"aggregate": ["mean"],
"period": "Month",
"interval": "Year",
},
"z": {
"name": "city",
"type": "string",
"label_axis": "City",
"map": {
"sea": "Seattle",
"nyc": "New York City"
}
}
}name- the name of the column in the CSV data file.type- the type of data. Supported types arenumber,string,datetime,date, andtime.label_axis- the label to be read by the Screen Reader for the axis and displayed as text.label_group- the label to be read by the Screen Reader for the aggregated group.aggregate- the function to be applied to the data binned by theinterval. Supported functions aremean,median,min,max,sum,count,consecutive_time.period- the period to describe equally spaced temporal data. Supported periods areMonth,Year,Week,Day,Hour,Minute,Second.interval- the interval to be used toaggregatealong the axis. Supported intervals areMonth,Year,Week,Day,Hour,Minute,Secondfortimedata. Should be a larger interval than theperiod. Fornumberdata, the provided number is usedaggregateby binning.map- a mapping of thestringdata to be read by the Screen Reader. The keys are the values in the CSV data file, and the values are the text to be read by the Screen Reader. only required forstringdata.
This project welcomes contributions and suggestions.
Pull requests to this repo will be reviewed, at a minimum, by one member of the Chart Reader research team.
Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.