maidr 1.2.2 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +170 -174
  2. package/dist/maidr.js +562 -587
  3. package/dist/maidr.min.js +1 -1
  4. package/package.json +2 -2
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # maidr: Multimodal Access and Interactive Data Representation
2
2
 
3
- maidr is a system for non-visual access and control of statistical plots. It aims to provide an inclusive experience for users with visual impairments by offering multiple modes of interaction: braille, text, and sonification (BTS). This comprehensive approach enhances the accessibility of data visualization and encourages a multi-model exploration on visualization. Check out the current build: [maidr Demo](https://uiuc-ischool-accessible-computing-lab.github.io/maidr/user_study_pilot/intro.html). You may also clone or download the github repo, navigate to the ./user_study_pilot folder, and open any of the html files in your browser.
3
+ maidr is a system for non-visual access and control of statistical plots. It aims to provide an inclusive experience for users with visual impairments by offering multiple modes of interaction: braille, text, and sonification (BTS). This comprehensive approach enhances the accessibility of data visualization and encourages a multi-modal exploration on visualization. Check out the current build: [maidr Demo](https://uiuc-ischool-accessible-computing-lab.github.io/maidr/user_study_pilot/intro.html). You may also clone or download the GitHub repo, navigate to the ./user_study_pilot folder, and open any of the html files in your browser.
4
4
 
5
5
  ## Table of Contents
6
6
 
@@ -19,87 +19,83 @@ To use maidr, follow these steps:
19
19
 
20
20
  2. **Create an HTML file**: Include the main script file `maidr.js` or `maidr.min.js` as well as the stylesheet `styles.css` or `styles.min.css`. Add the SVG of your plot to the main html body, and add an ID attribute of your choice to the SVG. Note that this can be automated with R. Your HTML file should now have the following structure:
21
21
 
22
- ```html
23
- <!DOCTYPE html>
24
- <html lang="en">
25
- <head>
26
- <meta charset="UTF-8" />
27
- <title>maidr Example</title>
28
- <link
29
- rel="stylesheet"
30
- href="https://cdn.jsdelivr.net/npm/maidr/dist/maidr_style.min.css"
31
- />
32
- <script src="https://cdn.jsdelivr.net/npm/maidr/dist/maidr.min.js"></script>
33
- </head>
34
- <body>
35
- <div>
36
- <!-- Your SVG plot is here -->
37
- </div>
38
- </body>
39
- </html>
40
- ```
22
+ ```html
23
+ <!DOCTYPE html>
24
+ <html lang="en">
25
+ <head>
26
+ <meta charset="UTF-8" />
27
+ <title>maidr Example</title>
28
+ <link
29
+ rel="stylesheet"
30
+ href="https://cdn.jsdelivr.net/npm/maidr/dist/maidr_style.min.css"
31
+ />
32
+ <script src="https://cdn.jsdelivr.net/npm/maidr/dist/maidr.min.js"></script>
33
+ </head>
34
+ <body>
35
+ <div>
36
+ <!-- Your SVG plot is here -->
37
+ </div>
38
+ </body>
39
+ </html>
40
+ ```
41
41
 
42
42
  3. Add your data: Include your data as a json schema directly in the HTML file. There should be a single `maidr` object with the following properties, or an array of objects if multiple charts exist on the page. Your json schema may look like so: (values for demonstration purposes)
43
43
 
44
- ```javascript
45
- // a single plot
46
- var maidr = {
47
- type: 'box',
48
- id: 'myboxplot',
49
- title: 'Highway Mileage by Car Class.',
50
- axes: {
51
- y: {
52
- label: 'Car Class',
53
- level: [
54
- '2seater',
55
- 'compact',
56
- 'midsize',
57
- 'minivan',
58
- 'pickup',
59
- 'subcompact',
60
- 'suv',
61
- ],
62
- },
63
- x: { label: 'Highway Milage' },
64
- },
65
- elements: document.querySelector(
66
- '#boxplot1 g[id^="panel"] > g[id^="geom_boxplot.gTree"]'
67
- ),
68
- data: ...
69
- }
70
-
71
- // or, multiple charts
72
- var maidr = [
73
- {
74
- type: 'box',
75
- id: 'myboxplot',
76
- title: 'Highway Mileage by Car Class.',
77
- axes: {
78
- y: {
79
- label: 'Car Class',
80
- level: [
81
- '2seater',
82
- 'compact',
83
- 'midsize',
84
- 'minivan',
85
- 'pickup',
86
- 'subcompact',
87
- 'suv',
88
- ],
89
- },
90
- x: { label: 'Highway Milage' },
91
- },
92
- elements: document.querySelector(
93
- '#boxplot1 g[id^="panel"] > g[id^="geom_boxplot.gTree"]'
94
- ),
95
- data: ...
96
- },
97
- {
98
- type: 'bar',
99
- id: 'mybarplot',
100
- ... // etc
101
- }
102
- ```
44
+ ```javascript
45
+ // a single plot
46
+ let maidr = {
47
+ type: 'box',
48
+ id: 'myboxplot',
49
+ title: 'Highway Mileage by Car Class.',
50
+ axes: {
51
+ y: {
52
+ label: 'Car Class',
53
+ level: [
54
+ '2seater',
55
+ 'compact',
56
+ 'midsize',
57
+ 'minivan',
58
+ 'pickup',
59
+ 'subcompact',
60
+ 'suv',
61
+ ],
62
+ },
63
+ x: { label: 'Highway Milage' },
64
+ },
65
+ selector: '#boxplot1 g[id^="panel"] > g[id^="geom_boxplot.gTree"]',
66
+ data: ...
67
+ }
68
+
69
+ // or, multiple charts
70
+ let maidr = [
71
+ {
72
+ type: 'box',
73
+ id: 'myboxplot',
74
+ title: 'Highway Mileage by Car Class.',
75
+ axes: {
76
+ y: {
77
+ label: 'Car Class',
78
+ level: [
79
+ '2seater',
80
+ 'compact',
81
+ 'midsize',
82
+ 'minivan',
83
+ 'pickup',
84
+ 'subcompact',
85
+ 'suv',
86
+ ],
87
+ },
88
+ x: { label: 'Highway Milage' },
89
+ },
90
+ selector: '#boxplot1 g[id^="panel"] > g[id^="geom_boxplot.gTree"]',
91
+ data: ...
92
+ },
93
+ {
94
+ type: 'bar',
95
+ id: 'mybarplot',
96
+ ... // etc
97
+ }
98
+ ```
103
99
 
104
100
  4. Use the following to define the object properties:
105
101
 
@@ -111,96 +107,96 @@ var maidr = [
111
107
 
112
108
  5. Define your data set using the `maidr.data` property. This comes in different formats depending on plot type:
113
109
 
114
- ```javascript
115
- // barplot maidr.data structure: a simple array of values
116
- var maidr = {
117
- data: [929539693, 898871185, 3811953828, 586098530, 24549948],
118
- };
119
-
120
- // heatmap maidr.data structure: a 2D array of values
121
- var maidr = {
122
- data: [
123
- [124, 0, 0],
124
- [0, 68, 0],
125
- [44, 56, 52],
126
- ],
127
- };
128
-
129
- // boxplot maidr.data structure: an array of objects with properties lower_outlier, min, q1, q2, q3, max, and upper_outlier
130
- var maidr = {
131
- data: [
132
- {
133
- lower_outlier: null,
134
- min: 23,
135
- q1: 24,
136
- q2: 25,
137
- q3: 26,
138
- max: 26,
139
- upper_outlier: null,
140
- },
141
- {
142
- // etc
143
- },
144
- ],
145
- };
146
-
147
- // scatterplot maidr.data: an object containing x and y properties, each with an array of float values
148
- // note that data is an array here as scatterplots are often combine with line plots
149
- var maidr = {
150
- data: [
151
- {
152
- x: [1.8, 1.8, 2, 2, 2.8, 2.8, 3.1, 1.8, 1.8, 2, 2, 2.8, 2.8, 3.1, 3.1],
153
- y: [29, 29, 31, 30, 26, 26, 27, 26, 25, 28, 27, 25, 25, 25, 25, 24],
154
- },
155
- // line data could go here
156
- ],
157
- };
158
-
159
- // smooth line maidr.data: an object containing x and y properties, each with an array of float values
160
- // note that data is an array here as scatterplots are often combine with line plots
161
- var maidr = {
162
- data: [
163
- // scatterplot data could go here
164
- {
165
- x: [1.8, 1.8, 2, 2, 2.8, 2.8, 3.1, 1.8, 1.8, 2, 2, 2.8, 2.8, 3.1, 3.1],
166
- y: [29, 29, 31, 30, 26, 26, 27, 26, 25, 28, 27, 25, 25, 25, 25, 24],
167
- },
168
- ],
169
- };
170
- ```
110
+ ```javascript
111
+ // barplot maidr.data structure: a simple array of values
112
+ var maidr = {
113
+ data: [929539693, 898871185, 3811953828, 586098530, 24549948],
114
+ };
115
+
116
+ // heatmap maidr.data structure: a 2D array of values
117
+ var maidr = {
118
+ data: [
119
+ [124, 0, 0],
120
+ [0, 68, 0],
121
+ [44, 56, 52],
122
+ ],
123
+ };
124
+
125
+ // boxplot maidr.data structure: an array of objects with properties lower_outlier, min, q1, q2, q3, max, and upper_outlier
126
+ var maidr = {
127
+ data: [
128
+ {
129
+ lower_outlier: null,
130
+ min: 23,
131
+ q1: 24,
132
+ q2: 25,
133
+ q3: 26,
134
+ max: 26,
135
+ upper_outlier: null,
136
+ },
137
+ {
138
+ // etc
139
+ },
140
+ ],
141
+ };
142
+
143
+ // scatterplot maidr.data: an object containing x and y properties, each with an array of float values
144
+ // note that data is an array here as scatterplots are often combine with line plots
145
+ var maidr = {
146
+ data: [
147
+ {
148
+ x: [1.8, 1.8, 2, 2, 2.8, 2.8, 3.1, 1.8, 1.8, 2, 2, 2.8, 2.8, 3.1, 3.1],
149
+ y: [29, 29, 31, 30, 26, 26, 27, 26, 25, 28, 27, 25, 25, 25, 25, 24],
150
+ },
151
+ // line data could go here
152
+ ],
153
+ };
154
+
155
+ // smooth line maidr.data: an object containing x and y properties, each with an array of float values
156
+ // note that data is an array here as scatterplots are often combine with line plots
157
+ var maidr = {
158
+ data: [
159
+ // scatterplot data could go here
160
+ {
161
+ x: [1.8, 1.8, 2, 2, 2.8, 2.8, 3.1, 1.8, 1.8, 2, 2, 2.8, 2.8, 3.1, 3.1],
162
+ y: [29, 29, 31, 30, 26, 26, 27, 26, 25, 28, 27, 25, 25, 25, 25, 24],
163
+ },
164
+ ],
165
+ };
166
+ ```
171
167
 
172
168
  6. If multiple plots are overlaid on the same SVG, the `type` and `data` properties can be an array instead of a single value. Be sure the order is matched between them. Final json schema could look like so:
173
169
 
174
- ```javascript
175
- var maidr = {
176
- type: ['point', 'smooth'],
177
- id: 'scatter1',
178
- title: 'Highway Mileage by Engine Displacement.',
179
- name: 'Tutorial 4: Scatterplot',
180
- elements: [
181
- document.querySelectorAll('g[id^="geom_point"] > use'),
182
- document.querySelector(
183
- 'g[id^="geom_smooth.gTree"] > g[id^="GRID.polyline"] > polyline[id^="GRID.polyline"]'
184
- ),
185
- ],
186
- axes: {
187
- x: {
188
- label: 'Engine Displacement',
189
- },
190
- y: {
191
- label: 'Highway Mileage',
192
- },
193
- },
194
- data: [
195
- {
196
- x: [1.8, 1.8, 2, 2, 2.8, 2.8, 3.1, 1.8, 1.8, 2, 2, 2.8, 2.8, 3.1, 3.1, 2.8],
197
- y: [29, 29, 31, 30, 26, 26, 27, 26, 25, 28, 27, 25, 25, 25, 25, 24],
198
- },
199
- {
200
- x: [1.6, 1.6684, 1.7367, 1.8051, 1.8734, 1.9418, 2.0101, 2.0785, 2.1468, 2.2152, 2.2835, 2.3519, 2.4203, 2.4886, 2.557, 2.6253],
201
- y: [33.0929, 32.5108, 31.9422, 31.3885, 30.8509, 30.33, 29.8239, 29.3334, 28.8584, 28.3981, 27.9519, 27.5189, 27.0988, 26.6958, 26.3091, 25.9356]
202
- },
203
- ```
170
+ ```javascript
171
+ var maidr = {
172
+ type: ['point', 'smooth'],
173
+ id: 'scatter1',
174
+ title: 'Highway Mileage by Engine Displacement.',
175
+ name: 'Tutorial 4: Scatterplot',
176
+ selector: [
177
+ 'g[id^="geom_point"] > use',
178
+ 'g[id^="geom_smooth.gTree"] > g[id^="GRID.polyline"] > polyline[id^="GRID.polyline"]',
179
+ ],
180
+ axes: {
181
+ x: {
182
+ label: 'Engine Displacement',
183
+ },
184
+ y: {
185
+ label: 'Highway Mileage',
186
+ },
187
+ },
188
+ data: [
189
+ {
190
+ x: [1.8, 1.8, 2, 2, 2.8, 2.8, 3.1, 1.8, 1.8, 2, 2, 2.8, 2.8, 3.1, 3.1, 2.8],
191
+ y: [29, 29, 31, 30, 26, 26, 27, 26, 25, 28, 27, 25, 25, 25, 25, 24],
192
+ },
193
+ {
194
+ x: [1.6, 1.6684, 1.7367, 1.8051, 1.8734, 1.9418, 2.0101, 2.0785, 2.1468, 2.2152, 2.2835, 2.3519, 2.4203, 2.4886, 2.557, 2.6253],
195
+ y: [33.0929, 32.5108, 31.9422, 31.3885, 30.8509, 30.33, 29.8239, 29.3334, 28.8584, 28.3981, 27.9519, 27.5189, 27.0988, 26.6958, 26.3091, 25.9356]
196
+ }
197
+ ]
198
+ }
199
+ ```
204
200
 
205
201
  For more information and examples, refer to the example HTML files provided in the repository.
206
202
 
@@ -218,7 +214,7 @@ To interact with the charts using maidr, follow these steps:
218
214
  Below is a detailed list of keyboard shortcuts for various functions:
219
215
 
220
216
  | Function | Key (Windows) | Key (Mac) |
221
- | --------------------------------------- | --------------------------- | --------------------------- |
217
+ |-----------------------------------------|-----------------------------|-----------------------------|
222
218
  | Move around plot | Arrow keys | Arrow keys |
223
219
  | Go to the very left, right, up, or down | Control + Arrow key | Command + Arrow key |
224
220
  | Select the first element | Control + Home | Command + Function + Left |
@@ -247,8 +243,8 @@ Note that this control scheme can be used by any plot with multiple types.
247
243
 
248
244
  In the various segmented bar plots (stacked bar, dodged bar, and normalized stacked bar), Up Down Left Right controls function similar to a grid:
249
245
 
250
- - Left and Right arrows move between different bars or points on the x axis.
251
- - Up and Down arrows move between different layers of the same bar or point on the x axis.
246
+ - Left and Right arrows move between different bars or points on the x-axis.
247
+ - Up and Down arrows move between different layers of the same bar or point on the x-axis.
252
248
 
253
249
  Note that there are also pseudo layers at the top of each layer stack: a Summary layer representing a sum of all that bar's values, and a Combined layer that plays a separated or combined run of tones of all the layers. The standard 'S' key that controls sonification now has an extra setting to play either combined tones or separated tones.
254
250
 
@@ -275,7 +271,7 @@ In the Braille representation of a heatmap, values are depicted based on their r
275
271
  - ⠒ represents values from 33% to 66%
276
272
  - ⠉ represents values from 66% to 100%
277
273
  - "⠀" (braille space) represents null or empty values
278
- - "⢳" represents a row seperator
274
+ - "⢳" represents a row separator
279
275
 
280
276
  ### Boxplot
281
277
 
@@ -331,11 +327,11 @@ In the Braille representation of a scatterplot, the encoding is performed only f
331
327
 
332
328
  Stacked bar, dodged bar, and normalized stacked bar all share the same system:
333
329
 
334
- In the braille representation of segmented bar plots, braille depends on where you are. There are typically multiple levels to a segmented bar plot, and as you move (Up and Down arrow keys) between levels, the braille changes to represent your current level. At the top, there is also a Summary pseudo layer of all levels added together, and a Combined pseudo layer of each layer seperately.
330
+ In the braille representation of segmented bar plots, braille depends on where you are. There are typically multiple levels to a segmented bar plot, and as you move (Up and Down arrow keys) between levels, the braille changes to represent your current level. At the top, there is also a Summary pseudo level of all levels added together, and a Combined pseudo level of each level separately.
335
331
 
336
- - Regular layers: Braille appears similar to a bar plot, with braille values corresponding to the magnitude of the layer's value for this point.
337
- - Summary layer: Same as regular layers, but values now reflect the combined magnitude of all layers' values for this point.
338
- - Combined layer: Similar to heatmap, where there are groups of magnitudes for each point separated by a ⢳ character. The first group has braille characters for each layer for the first point, then a seperator, then the second group has braille characters for each layer in the second point, then a seperator, and so on.
332
+ - Regular level: Braille appears similar to a bar plot, with braille values corresponding to the magnitude of the level's value for this point.
333
+ - Summary level: Same as regular level, but values now reflect the combined magnitude of all levels' values for this point.
334
+ - Combined level: Similar to heatmap, where there are groups of magnitudes for each point separated by a ⢳ character. The first group has braille characters for each level for the first point, then a separator, then the second group has braille characters for each level in the second point, then a separator, and so on.
339
335
 
340
336
  ### Lineplot
341
337