Skip to content

Commit d32f662

Browse files
etpinardetpinard
committed
introduce new box attributes for q1/median/q3 signature
- add attribues q1, median, q3, lowerfence, upperfence, notchspan, mean, sd, dx, dy - add info in the module meta description - add info about improved boxmean, boxpoints and notched dflt logic - add TODO comment for potential outlier bounds attributes
1 parent feb4388 commit d32f662

File tree

2 files changed

+152
-18
lines changed

2 files changed

+152
-18
lines changed

‎src/traces/box/attributes.js‎

Lines changed: 128 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,9 @@ module.exports = {
3939
role: 'info',
4040
editType: 'calc+clearAxisTypes',
4141
description: [
42-
'Sets the x coordinate of the box.',
42+
'Sets the x coordinate for single-box traces',
43+
'or the starting coordinate for multi-box traces',
44+
'set using q1/median/q3.',
4345
'See overview for more info.'
4446
].join(' ')
4547
},
@@ -48,11 +50,32 @@ module.exports = {
4850
role: 'info',
4951
editType: 'calc+clearAxisTypes',
5052
description: [
51-
'Sets the y coordinate of the box.',
53+
'Sets the y coordinate for single-box traces',
54+
'or the starting coordinate for multi-box traces',
55+
'set using q1/median/q3.',
5256
'See overview for more info.'
5357
].join(' ')
5458
},
5559

60+
dx: {
61+
valType: 'number',
62+
role: 'info',
63+
editType: 'calc',
64+
description: [
65+
'Sets the x coordinate step for multi-box traces',
66+
'set using q1/median/q3.'
67+
].join(' ')
68+
},
69+
dy: {
70+
valType: 'number',
71+
role: 'info',
72+
editType: 'calc',
73+
description: [
74+
'Sets the y coordinate step for multi-box traces',
75+
'set using q1/median/q3.'
76+
].join(' ')
77+
},
78+
5679
name: {
5780
valType: 'string',
5881
role: 'info',
@@ -66,6 +89,58 @@ module.exports = {
6689
].join(' ')
6790
},
6891

92+
q1: {
93+
valType: 'data_array',
94+
role: 'info',
95+
editType: 'calc+clearAxisTypes',
96+
description: [
97+
'Sets the Quartile 1 values,',
98+
'There should be as many items as the number of boxes desired.',
99+
].join(' ')
100+
},
101+
median: {
102+
valType: 'data_array',
103+
role: 'info',
104+
editType: 'calc+clearAxisTypes',
105+
description: [
106+
'Sets the median values.',
107+
'There should be as many items as the number of boxes desired.',
108+
].join(' ')
109+
},
110+
q3: {
111+
valType: 'data_array',
112+
role: 'info',
113+
editType: 'calc+clearAxisTypes',
114+
description: [
115+
'Sets the Quartile 3 values,',
116+
'There should be as many items as the number of boxes desired.',
117+
].join(' ')
118+
},
119+
lowerfence: {
120+
valType: 'data_array',
121+
role: 'info',
122+
editType: 'calc',
123+
description: [
124+
'Sets the lower fence values,',
125+
'There should be as many items as the number of boxes desired.',
126+
'This attribute has effect only under the q1/median/q3 signature.',
127+
'If `lowerfence` is not provided but a sample (in `y` or `x`) is set,',
128+
'we compute the lower as the last sample point below 1.5 times the IQR.'
129+
].join(' ')
130+
},
131+
upperfence: {
132+
valType: 'data_array',
133+
role: 'info',
134+
editType: 'calc',
135+
description: [
136+
'Sets the upper fence values,',
137+
'There should be as many items as the number of boxes desired.',
138+
'This attribute has effect only under the q1/median/q3 signature.',
139+
'If `upperfence` is not provided but a sample (in `y` or `x`) is set,',
140+
'we compute the lower as the last sample point above 1.5 times the IQR.'
141+
].join(' ')
142+
},
143+
69144
notched: {
70145
valType: 'boolean',
71146
role: 'info',
@@ -76,7 +151,8 @@ module.exports = {
76151
'We compute the confidence interval as median +/- 1.57 * IQR / sqrt(N),',
77152
'where IQR is the interquartile range and N is the sample size.',
78153
'If two boxes\' notches do not overlap there is 95% confidence their medians differ.',
79-
'See https://sites.google.com/site/davidsstatistics/home/notched-box-plots for more info.'
154+
'See https://sites.google.com/site/davidsstatistics/home/notched-box-plots for more info.',
155+
'Defaults to *false* unless `notchwidth` or `notchspan` is set.'
80156
].join(' ')
81157
},
82158
notchwidth: {
@@ -92,6 +168,24 @@ module.exports = {
92168
'For example, with 0, the notches are as wide as the box(es).'
93169
].join(' ')
94170
},
171+
notchspan: {
172+
valType: 'data_array',
173+
role: 'info',
174+
editType: 'calc',
175+
description: [
176+
'Sets the notch span from the boxes\' `median` values,',
177+
'There should be as many items as the number of boxes desired.',
178+
'This attribute has effect only under the q1/median/q3 signature.',
179+
'If `notchspan` is not provided but a sample (in `y` or `x`) is set,',
180+
'we compute it as 1.57 * IQR / sqrt(N),',
181+
'where N is the sample size.'
182+
].join(' ')
183+
},
184+
185+
// TODO
186+
// maybe add
187+
// - loweroutlierbound / upperoutlierbound
188+
// - lowersuspectedoutlierbound / uppersuspectedoutlierbound
95189

96190
boxpoints: {
97191
valType: 'enumerated',
@@ -107,8 +201,9 @@ module.exports = {
107201
'If *all*, all sample points are shown',
108202
'If *false*, only the box(es) are shown with no sample points',
109203
'Defaults to *suspectedoutliers* when `marker.outliercolor` or',
110-
'`marker.line.outliercolor` is set,',
111-
'otherwise defaults to *outliers*.'
204+
'`marker.line.outliercolor` is set.,',
205+
'Defaults to *all* under the q1/median/q3 signature.',
206+
'Otherwise defaults to *outliers*.',
112207
].join(' ')
113208
},
114209
jitter: {
@@ -141,13 +236,39 @@ module.exports = {
141236
boxmean: {
142237
valType: 'enumerated',
143238
values: [true, 'sd', false],
144-
dflt: false,
145239
role: 'style',
146240
editType: 'calc',
147241
description: [
148242
'If *true*, the mean of the box(es)\' underlying distribution is',
149243
'drawn as a dashed line inside the box(es).',
150-
'If *sd* the standard deviation is also drawn.'
244+
'If *sd* the standard deviation is also drawn.',
245+
'Defaults to *true* when `mean` is set',
246+
'Defaults to *sd* when `sd` is set',
247+
'Otherwise defaults to *false*.'
248+
].join(' ')
249+
},
250+
mean: {
251+
valType: 'data_array',
252+
role: 'info',
253+
editType: 'calc',
254+
description: [
255+
'Sets the mean values,',
256+
'There should be as many items as the number of boxes desired.',
257+
'This attribute has effect only under the q1/median/q3 signature.',
258+
'If `mean` is not provided but a sample (in `y` or `x`) is set,',
259+
'we compute the mean for each box using the sample values.'
260+
].join(' ')
261+
},
262+
sd: {
263+
valType: 'data_array',
264+
role: 'info',
265+
editType: 'calc',
266+
description: [
267+
'Sets the standard deviation values,',
268+
'There should be as many items as the number of boxes desired.',
269+
'This attribute has effect only under the q1/median/q3 signature.',
270+
'If `sd` is not provided but a sample (in `y` or `x`) is set,',
271+
'we compute the standard deviation for each box using the sample values.'
151272
].join(' ')
152273
},
153274

‎src/traces/box/index.js‎

Lines changed: 24 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -29,18 +29,31 @@ module.exports = {
2929
categories: ['cartesian', 'svg', 'symbols', 'oriented', 'box-violin', 'showLegend', 'boxLayout', 'zoomScale'],
3030
meta: {
3131
description: [
32-
'In vertical (horizontal) box plots,',
33-
'statistics are computed using `y` (`x`) values.',
34-
'By supplying an `x` (`y`) array, one box per distinct x (y) value',
35-
'is drawn',
36-
'If no `x` (`y`) {array} is provided, a single box is drawn.',
37-
'That box position is then positioned with',
38-
'with `name` or with `x0` (`y0`) if provided.',
3932
'Each box spans from quartile 1 (Q1) to quartile 3 (Q3).',
40-
'The second quartile (Q2) is marked by a line inside the box.',
41-
'By default, the whiskers correspond to the box\' edges',
42-
'+/- 1.5 times the interquartile range (IQR: Q3-Q1),',
43-
'see *boxpoints* for other options.'
33+
'The second quartile (Q2, i.e. the median) is marked by a line inside the box.',
34+
'The fences grow outward from the boxes\' edges,',
35+
'by default they span +/- 1.5 times the interquartile range (IQR: Q3-Q1),',
36+
'The sample mean and standard deviation as well as notches and',
37+
'the sample, outlier and suspected outliers points can be optionally',
38+
'added to the box plot',
39+
40+
'The values and positions corresponding to each boxes can be input',
41+
'using two signatures.',
42+
43+
'The first signature expects users to supply the sample values in the `y`',
44+
'data array for vertical boxes (`x` for horizontal boxes).',
45+
'By supplying an `x` (`y`) array, one box per distinct x (y) value is drawn',
46+
'If no `x` (`y`) {array} is provided, a single box is drawn.',
47+
'In this case, the box is positioned with the trace `name` or with `x0` (`y0`) if provided.',
48+
49+
'The second signature expects users to supply the boxes corresponding Q1, median and Q3',
50+
'statistics in the `q1`, `median` and `q3` data arrays respectively.',
51+
'Other box features relying on statistics namely `lowerfence`, `upperfence`, `notchspan`',
52+
'can be set directly by the users.',
53+
'To have plotly compute them or to show sample points besides the boxes,',
54+
'users can set the `y` data array for vertical boxes (`x` for horizontal boxes)',
55+
'to a 2D array with the outer length corresponding',
56+
'to the number of boxes in the traces and the inner length corresponding the sample size.'
4457
].join(' ')
4558
}
4659
};

0 commit comments

Comments
 (0)