maidr 3.38.0 → 3.39.0

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.
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
  <br />
5
5
  </div>
6
6
 
7
- # maidr: Multimodal Access and Interactive Data Representation
7
+ # MAIDR: Multimodal Access and Interactive Data Representation
8
8
 
9
9
  - **Note:** `maidr` package has been completely rewritten in TypeScript for better architecture and performance. The previous version is now archived at [xability/maidr-legacy](https://github.com/xability/maidr-legacy).
10
10
 
@@ -14,19 +14,18 @@ braille, text, and sonification (BTS).
14
14
  This comprehensive approach enhances the accessibility of data visualization
15
15
  and encourages a multi-modal exploration on visualization.
16
16
 
17
- <!-- Check out the current build: [maidr Demo](https://xability.github.io/maidr/galleries/index.html). -->
18
-
19
17
  ## Table of Contents
20
18
 
21
19
  1. [Usage](#usage)
22
- 2. [Controls](#controls)
23
- 3. [Braille Generation](#braille-generation)
24
- 4. [API](#api)
25
- 5. [Binders](#binders)
26
- 6. [Papers](#papers)
27
- 7. [License](#license)
28
- 8. [Contact](#contact)
29
- 9. [Acknowledgments](#acknowledgments)
20
+ 2. [Examples](#examples)
21
+ 3. [Controls](#controls)
22
+ 4. [Braille Generation](#braille-generation)
23
+ 5. [API](#api)
24
+ 6. [Binders](#binders)
25
+ 7. [Papers](#papers)
26
+ 8. [License](#license)
27
+ 9. [Contact](#contact)
28
+ 10. [Acknowledgments](#acknowledgments)
30
29
 
31
30
  ## Usage
32
31
 
@@ -42,8 +41,8 @@ To use maidr, follow these steps:
42
41
  <head>
43
42
  <meta charset="UTF-8" />
44
43
  <title>maidr Example</title>
45
- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maidr/dist/maidr_style.min.css" />
46
- <script src="https://cdn.jsdelivr.net/npm/maidr/dist/maidr.min.js"></script>
44
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maidr@latest/dist/maidr_style.css" />
45
+ <script src="https://cdn.jsdelivr.net/npm/maidr@latest/dist/maidr.js"></script>
47
46
  </head>
48
47
  <body>
49
48
  <div>
@@ -55,218 +54,347 @@ To use maidr, follow these steps:
55
54
 
56
55
  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 plots exist on the page. Your JSON schema may look like so: (values for demonstration purposes)
57
56
 
58
- ```javascript
57
+ ```javascript
59
58
  // a single plot
60
- let maidr = {
61
- type: 'box',
62
- id: 'myboxplot',
63
- title: 'Highway Mileage by Car Class.',
64
- axes: {
65
- y: {
66
- label: 'Car Class',
67
- level: [
68
- '2seater',
69
- 'compact',
70
- 'midsize',
71
- 'minivan',
72
- 'pickup',
73
- 'subcompact',
74
- 'suv',
75
- ],
76
- },
77
- x: { label: 'Highway Milage' },
78
- },
79
- selector: '#boxplot1 g[id^="panel"] > g[id^="geom_boxplot.gTree"]',
80
- data: []
81
- };
82
-
83
- // or, multiple plots
84
- maidr = [
85
- {
86
- type: 'box',
87
- id: 'myboxplot',
88
- title: 'Highway Mileage by Car Class.',
89
- axes: {
90
- y: {
91
- label: 'Car Class',
92
- level: [
93
- '2seater',
94
- 'compact',
95
- 'midsize',
96
- 'minivan',
97
- 'pickup',
98
- 'subcompact',
99
- 'suv',
100
- ],
101
- },
102
- x: { label: 'Highway Milage' },
103
- },
104
- selector: '#boxplot1 g[id^="panel"] > g[id^="geom_boxplot.gTree"]',
105
- data: []
106
- },
107
- {
108
- type: 'bar',
109
- id: 'mybarplot',
110
- // etc
111
- }
112
- ];
113
- ```
59
+ <script>
60
+ var maidr = {
61
+ id: "barplot_1",
62
+ subplots: [
63
+ [
64
+ {
65
+ id: "barplot_1", //add the same id to the svg component
66
+ layers: [
67
+ {
68
+ id: "bar_layer1",
69
+ type: "bar",
70
+ title: "Sample Bar plot",
71
+ axes: {
72
+ x: "Category",
73
+ y: "Value"
74
+ },
75
+ data: [
76
+ {
77
+ "x": "A",
78
+ "y": 10
79
+ },
80
+ {
81
+ "x": "B",
82
+ "y": 24
83
+ },
84
+ {
85
+ "x": "C",
86
+ "y": 15
87
+ },
88
+ {
89
+ "x": "D",
90
+ "y": 7
91
+ }
92
+ ]
93
+ }
94
+ ]
95
+ }
96
+ ]
97
+ ]
98
+ }
99
+ </script>
100
+ ```
114
101
 
102
+ Or multiple plots:
103
+ ```javascript
104
+ <script>
105
+ var maidr = {
106
+ "id": "multipanel_plot",
107
+ "subplots": [
108
+ [
109
+ {
110
+ "id": "line1",
111
+ "layers": [
112
+ {
113
+ "id": "line_layer",
114
+ "type": "line",
115
+ "title": "Line Plot: Random Data",
116
+ "axes": {
117
+ "x": "X-axis",
118
+ "y": "Values"
119
+ },
120
+ "data": [
121
+ []
122
+ ],
123
+ }
124
+ ]
125
+ }
126
+ ],
127
+ [
128
+ {
129
+ "id": "bar1",
130
+ "layers": [
131
+ {
132
+ "id": "bar1_layer",
133
+ "type": "bar",
134
+ "title": "Bar Plot: Random Values",
135
+ "axes": {
136
+ "x": "Categories",
137
+ "y": "Values"
138
+ },
139
+ "data": []
140
+ }
141
+ ]
142
+ }
143
+ ],
144
+ [
145
+ {
146
+ "id": "bar2",
147
+ "layers": [
148
+ {
149
+ "id": "bar2_layer",
150
+ "type": "bar",
151
+ "title": "Bar Plot 2: Random Values",
152
+ "axes": {
153
+ "x": "Categories",
154
+ "y": "Values"
155
+ },
156
+ "data": []
157
+ }
158
+ ]
159
+ }
160
+ ]
161
+ ]
162
+ }
163
+ </script>
164
+ ```
115
165
  4. Use the following to define the object properties:
116
166
 
117
- - `type`: the type of plot. Currently supported are 'bar,' 'heat,' 'box,' 'scatter,' and 'line.'
167
+ - `type`: the type of plot. Currently supported are 'bar', 'box', 'candlestick', 'dodged_bar', 'heat', 'hist', 'line', 'stacked_normalized_bar', 'point', 'smooth', 'stacked_bar',
118
168
  - `id`: the id that you added as an attribute of your main SVG.
119
169
  - `title`: the title of the plot. (optional)
120
170
  - `axes`: axes info for your plot. `maidr.axes.x.label` and `maidr.axes.y.label` will provide axes labels, and `maidr.axes.x.level` or `maidr.axes.y.level` (x or y, not both) will provide level or tick mark labels.
121
171
  - `data`: the main data for your plot. See below.
122
172
 
123
173
  5. Define your data set using the `maidr.data` property. This comes in different formats depending on a plot type:
174
+ The data property is defined as a list of objects where each object is a record with fields x and y.
175
+
176
+ ```javascript
124
177
 
125
- ```javascript
126
178
  let maidr;
127
179
 
128
180
  // barplot maidr.data structure: a simple array of values
129
181
  maidr = {
130
- data: [929539693, 898871185, 3811953828, 586098530, 24549948],
131
- };
132
-
133
- // heatmap maidr.data structure: a 2D array of values
134
- maidr = {
135
- data: [
136
- [124, 0, 0],
137
- [0, 68, 0],
138
- [44, 56, 52],
139
- ],
182
+ "data": [
183
+ {
184
+ "x": "A",
185
+ "y": 5.982192824845484
186
+ },
187
+ {
188
+ "x": "B",
189
+ "y": 9.309858198175455
190
+ },
191
+ {
192
+ "x": "C",
193
+ "y": 7.3531284491571505
194
+ },
195
+ ]
140
196
  };
141
197
 
142
- // boxplot maidr.data structure: an array of objects with properties lower_outlier, min, q1, q2, q3, max, and upper_outlier
143
- maidr = {
144
- data: [
145
- {
146
- lower_outlier: null,
147
- min: 23,
148
- q1: 24,
149
- q2: 25,
150
- q3: 26,
151
- max: 26,
152
- upper_outlier: null,
153
- },
154
- {
155
- // etc
156
- },
157
- ],
158
- };
198
+ // boxplot maidr.data structure: an array of objects with properties lower_outlier, min, q1, q2, q3, max, and upper_outlier
199
+ maidr = {
200
+ "data": [
201
+ {
202
+ "lowerOutliers": [
203
+ 40.0,
204
+ 50.0
205
+ ],
206
+ "min": 71.35451232573614,
207
+ "q1": 92.62315416457983,
208
+ "q2": 99.64912548800726,
209
+ "q3": 107.6684972253361,
210
+ "max": 118.19391634772752,
211
+ "upperOutliers": [
212
+ 150.0,
213
+ 160.0
214
+ ],
215
+ "fill": "Group 1"
216
+ },
217
+
218
+ ],
219
+
220
+ "orientation": "vert" //vert for vertical box plots, horz for horizontal bar plots
221
+ }
222
+
223
+ //candlestick
224
+ maidr = {
225
+ "data":[
226
+ {
227
+ 'value': '2023-02-16',
228
+ 'open': 151.61,
229
+ 'high': 151.82,
230
+ 'low': 151.59,
231
+ 'close': 151.8,
232
+ 'volume': 0
233
+ },
234
+ ]
235
+ }
236
+
237
+ //dodged_bar
238
+ maidr = {
239
+ "data":[
240
+ [
241
+ {
242
+ "x":"Adelie",
243
+ "fill":"Below",
244
+ "y":70
245
+ }
246
+ ],
247
+ [ {
248
+ "x":"Adelie",
249
+ "fill":"Above",
250
+ "y":90
251
+ }]
252
+ ]
253
+ }
159
254
 
160
- // scatterplot maidr.data: an object containing x and y properties, each with an array of float values
161
- // note that data is an array here as scatterplots are often combine with line plots
255
+ // heatmap maidr.data structure: a 2D array of values
256
+ maidr = {
257
+ "data": {
258
+ "points": [
259
+ [ 60.5, 86.7, 89.3 ],
260
+ [ 18.6, 67.6, 83.9 ],
261
+ [ 18.5, 65.4, 78.7 ],
262
+ ],
263
+ "x": [
264
+ "CoLA",
265
+ "MNLI",
266
+ "MRPC",
267
+ ],
268
+ "y": [
269
+ "BERT",
270
+ "BiLSTM",
271
+ "BiLSTM+Attn",
272
+ ]
273
+ }
274
+ }
275
+
276
+ //histogram
277
+ maidr = {
278
+ "data":[
279
+ {
280
+ "y": 4.0,
281
+ "x": 1.1475,
282
+ "xMin": 1.0,
283
+ "xMax": 1.295,
284
+ "yMin": 0,
285
+ "yMax": 4.0
286
+ }
287
+ ]
288
+ }
289
+
290
+ //line
291
+ maidr = {
292
+ "data":[
293
+ [
294
+ {
295
+ "x": 1.0,
296
+ "y": 2.0
297
+ },
298
+ {
299
+ "x": 2.0,
300
+ "y": 4.0
301
+ },
302
+ ]
303
+ //add multiple arrays for multiline plots
304
+ ]
305
+ }
306
+
307
+ // scatterplot
162
308
  maidr = {
163
309
  data: [
164
310
  {
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
- // line data could go here
311
+ "x": 1.0,
312
+ "y": 2.0
313
+ },
169
314
  ],
170
315
  };
171
316
 
172
317
  // smooth line maidr.data: an object containing x and y properties, each with an array of float values
173
318
  // note that data is an array here as scatterplots are often combine with line plots
174
319
  maidr = {
175
- data: [
176
- // scatterplot data could go here
177
- {
178
- 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],
179
- y: [29, 29, 31, 30, 26, 26, 27, 26, 25, 28, 27, 25, 25, 25, 25, 24],
180
- },
181
- ],
182
- };
183
- ```
320
+ "data":[
321
+ [
322
+ {
323
+ "x": 4.7,
324
+ "y": 3.12,
325
+ "svg_x": 404.51,
326
+ "svg_y": 390.012
327
+ },
328
+ ]
329
+ ]
330
+ }
331
+
332
+ ```
333
+
334
+ 6. If multiple plots are overlaid on the same SVG, provide the data corresponding to every plot in the layers array.
335
+
336
+ ```javascript
337
+ maidr = {
338
+ "id": "multilayer_plot",
339
+ "subplots": [
340
+ [
341
+ {
342
+ "id": "445f4f08-b8a5-4204-8c55-0851eda7daec",
343
+ "layers": [
344
+ {
345
+ "id": "f548e01f-ed13-469c-9e0a-cea420ec8b3f",
346
+ "type": "bar",
347
+ "title": "",
348
+ "axes": {
349
+ "x": "X values",
350
+ "y": "Bar values"
351
+ },
352
+ "data": [
353
+ {
354
+ "x": "0",
355
+ "y": 3.0
356
+ },
357
+ {
358
+ "x": "1",
359
+ "y": 5.0
360
+ },
361
+ ],
362
+ },
363
+ {
364
+ "id": "f022d8e9-4aff-4ab0-9959-904fd07c9bd2",
365
+ "type": "line",
366
+ "title": "Multilayer Plot Example",
367
+ "axes": {
368
+ "x": "X values",
369
+ "y": "Line values"
370
+ },
371
+ "data": [
372
+ [
373
+ {
374
+ "x": 0.0,
375
+ "y": 10.0,
376
+ "fill": "Line Data"
377
+ },
378
+ {
379
+ "x": 1.0,
380
+ "y": 8.0,
381
+ "fill": "Line Data"
382
+ },
383
+ ]
384
+ ],
385
+ }
386
+ ]
387
+ }
388
+ ]
389
+ ]
390
+ }
391
+ ```
184
392
 
185
- 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. The final JSON schema could look like so:
186
-
187
- ```javascript
188
- const maidr = {
189
- type: ['point', 'smooth'],
190
- id: 'scatter1',
191
- title: 'Highway Mileage by Engine Displacement.',
192
- name: 'Tutorial 4: Scatterplot',
193
- selector: [
194
- 'g[id^="geom_point"] > use',
195
- 'g[id^="geom_smooth.gTree"] > g[id^="GRID.polyline"] > polyline[id^="GRID.polyline"]',
196
- ],
197
- axes: {
198
- x: {
199
- label: 'Engine Displacement',
200
- },
201
- y: {
202
- label: 'Highway Mileage',
203
- },
204
- },
205
- data: [
206
- {
207
- x: [
208
- 1.8,
209
- 1.8,
210
- 2,
211
- 2,
212
- 2.8,
213
- 2.8,
214
- 3.1,
215
- 1.8,
216
- 1.8,
217
- 2,
218
- 2,
219
- 2.8,
220
- 2.8,
221
- 3.1,
222
- 3.1,
223
- 2.8,
224
- ],
225
- y: [29, 29, 31, 30, 26, 26, 27, 26, 25, 28, 27, 25, 25, 25, 25, 24],
226
- },
227
- {
228
- x: [
229
- 1.6,
230
- 1.6684,
231
- 1.7367,
232
- 1.8051,
233
- 1.8734,
234
- 1.9418,
235
- 2.0101,
236
- 2.0785,
237
- 2.1468,
238
- 2.2152,
239
- 2.2835,
240
- 2.3519,
241
- 2.4203,
242
- 2.4886,
243
- 2.557,
244
- 2.6253,
245
- ],
246
- y: [
247
- 33.0929,
248
- 32.5108,
249
- 31.9422,
250
- 31.3885,
251
- 30.8509,
252
- 30.33,
253
- 29.8239,
254
- 29.3334,
255
- 28.8584,
256
- 28.3981,
257
- 27.9519,
258
- 27.5189,
259
- 27.0988,
260
- 26.6958,
261
- 26.3091,
262
- 25.9356,
263
- ],
264
- },
265
- ],
266
- };
267
- ```
268
393
 
269
- For more information and examples, refer to the example HTML files provided in the repository.
394
+ ## Examples
395
+ Example plots are demonstrated [here](https://xabilitylab.ischool.illinois.edu/maidr/).
396
+
397
+ For more information, refer to the example HTML files provided in the directory docs/examples
270
398
 
271
399
  ## Controls
272
400
 
@@ -278,6 +406,7 @@ To interact with the plots using maidr, follow these steps:
278
406
  4. Press **T** to toggle Text mode.
279
407
  5. Press **S** to toggle Sonification (tones) mode.
280
408
  6. Press **R** to toggle Review mode.
409
+ 7. Hover on the datapoint to
281
410
 
282
411
  Below is a detailed list of keyboard shortcuts for various functions:
283
412
 
@@ -296,16 +425,9 @@ Below is a detailed list of keyboard shortcuts for various functions:
296
425
  | Stop Auto-play | Control | Command |
297
426
  | Auto-play speed up | Period | Period |
298
427
  | Auto-play speed down | Comma | Comma |
299
-
300
- <!-- ### Scatter Plot Controls
301
-
302
- In the scatter plot, there are two layers: point mode (layer 1) and line mode (layer 2).
303
- To switch between these layers, use the Page Up and Page Down keys:
304
-
305
- - Press Page Up to move from point mode to line mode
306
- - Press Page Down to move from line mode to point mode
307
-
308
- Note that this control scheme can be used by any plot with multiple types. -->
428
+ | Move to next navigation mode | Shift + Alt + Up/Down | Shift + Alt + Up/Down |
429
+ | Open Settings | Control + , | Command + , |
430
+ | Open Command Pallette | Control + Shift + p | Command + Shift + p |
309
431
 
310
432
  ### Segmented Bar Controls
311
433