0
# Statistical Charts
1

2
Advanced statistical visualizations including histograms, box plots, violin plots, and distribution analysis charts.
3

4
## Capabilities
5

6
### Histograms
7

8
Distribution visualization for continuous data with automatic or manual binning.
9

10
```javascript { .api }
11
/**
12
 * Histogram trace configuration
13
 */
14
interface HistogramTrace {
15
  type: 'histogram';
16
  x?: number[];
17
  y?: number[];
18
  histfunc?: 'count' | 'sum' | 'avg' | 'min' | 'max';
19
  histnorm?: '' | 'percent' | 'probability' | 'density' | 'probability density';
20
  autobinx?: boolean;
21
  autobiny?: boolean;
22
  nbinsx?: number;
23
  nbinsy?: number;
24
  xbins?: Partial<HistogramBins>;
25
  ybins?: Partial<HistogramBins>;
26
  bingroup?: string;
27
  marker?: Partial<HistogramMarker>;
28
  orientation?: 'v' | 'h';
29
  cumulative?: Partial<HistogramCumulative>;
30
  error_x?: Partial<ErrorBars>;
31
  error_y?: Partial<ErrorBars>;
32
}
33

34
interface HistogramBins {
35
  start?: number;
36
  end?: number;
37
  size?: number;
38
}
39

40
interface HistogramMarker {
41
  color?: string | string[];
42
  opacity?: number;
43
  line?: {
44
    color?: string;
45
    width?: number;
46
  };
47
  colorscale?: string;
48
  cauto?: boolean;
49
  cmin?: number;
50
  cmax?: number;
51
}
52

53
interface HistogramCumulative {
54
  enabled?: boolean;
55
  direction?: 'increasing' | 'decreasing';
56
  currentbin?: 'include' | 'exclude' | 'half';
57
}
58
```
59

60
**Usage Examples:**
61

62
```javascript
63
// Basic histogram
64
const data = [1, 2, 2, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 5];
65
Plotly.newPlot('myDiv', [{
66
    x: data,
67
    type: 'histogram',
68
    nbinsx: 10
69
}]);
70

71
// Normalized histogram
72
Plotly.newPlot('myDiv', [{
73
    x: data,
74
    type: 'histogram',
75
    histnorm: 'probability',
76
    marker: {
77
        color: 'lightblue',
78
        line: {
79
            color: 'blue',
80
            width: 1
81
        }
82
    }
83
}]);
84

85
// Custom bin configuration
86
Plotly.newPlot('myDiv', [{
87
    x: data,
88
    type: 'histogram',
89
    xbins: {
90
        start: 0,
91
        end: 6,
92
        size: 0.5
93
    },
94
    marker: {
95
        color: 'rgba(255, 0, 0, 0.7)'
96
    }
97
}]);
98

99
// Cumulative histogram
100
Plotly.newPlot('myDiv', [{
101
    x: data,
102
    type: 'histogram',
103
    cumulative: {
104
        enabled: true,
105
        direction: 'increasing'
106
    }
107
}]);
108

109
// Overlaid histograms
110
const data1 = Array.from({length: 500}, () => Math.random() * 10);
111
const data2 = Array.from({length: 500}, () => Math.random() * 8 + 2);
112

113
Plotly.newPlot('myDiv', [
114
    {
115
        x: data1,
116
        type: 'histogram',
117
        opacity: 0.7,
118
        name: 'Group 1',
119
        marker: { color: 'red' }
120
    },
121
    {
122
        x: data2,
123
        type: 'histogram',
124
        opacity: 0.7,
125
        name: 'Group 2',
126
        marker: { color: 'blue' }
127
    }
128
], {
129
    barmode: 'overlay'
130
});
131
```
132

133
### 2D Histograms
134

135
Two-dimensional histograms for visualizing bivariate distributions.
136

137
```javascript { .api }
138
/**
139
 * 2D histogram trace configuration
140
 */
141
interface Histogram2DTrace {
142
  type: 'histogram2d';
143
  x: number[];
144
  y: number[];
145
  z?: number[];
146
  histfunc?: 'count' | 'sum' | 'avg' | 'min' | 'max';
147
  histnorm?: '' | 'percent' | 'probability' | 'density' | 'probability density';
148
  autobinx?: boolean;
149
  autobiny?: boolean;
150
  nbinsx?: number;
151
  nbinsy?: number;
152
  xbins?: Partial<HistogramBins>;
153
  ybins?: Partial<HistogramBins>;
154
  bingroup?: string;
155
  colorscale?: string;
156
  showscale?: boolean;
157
  colorbar?: Partial<ColorBar>;
158
  zauto?: boolean;
159
  zmin?: number;
160
  zmax?: number;
161
}
162
```
163

164
**Usage Examples:**
165

166
```javascript
167
// Generate bivariate data
168
const n = 1000;
169
const x = Array.from({length: n}, () => Math.random() * 10);
170
const y = Array.from({length: n}, () => Math.random() * 8 + x[i % n] * 0.3);
171

172
// Basic 2D histogram
173
Plotly.newPlot('myDiv', [{
174
    x: x,
175
    y: y,
176
    type: 'histogram2d',
177
    colorscale: 'Hot'
178
}]);
179

180
// 2D histogram with custom bins
181
Plotly.newPlot('myDiv', [{
182
    x: x,
183
    y: y,
184
    type: 'histogram2d',
185
    xbins: { start: 0, end: 10, size: 0.5 },
186
    ybins: { start: 0, end: 12, size: 0.6 },
187
    colorscale: 'Viridis',
188
    showscale: true
189
}]);
190
```
191

192
### Box Plots
193

194
Statistical distribution visualization showing quartiles, outliers, and median.
195

196
```javascript { .api }
197
/**
198
 * Box plot trace configuration
199
 */
200
interface BoxTrace {
201
  type: 'box';
202
  x?: any[];
203
  y?: number[];
204
  q1?: number[];
205
  median?: number[];
206
  q3?: number[];
207
  lowerfence?: number[];
208
  upperfence?: number[];
209
  mean?: number[];
210
  sd?: number[];
211
  notchspan?: number[];
212
  name?: string;
213
  orientation?: 'v' | 'h';
214
  boxpoints?: 'all' | 'outliers' | 'suspectedoutliers' | false;
215
  boxmean?: true | 'sd' | false;
216
  notched?: boolean;
217
  notchwidth?: number;
218
  whiskerwidth?: number;
219
  width?: number;
220
  offset?: number;
221
  offsetgroup?: string;
222
  alignmentgroup?: string;
223
  selected?: Partial<BoxSelected>;
224
  unselected?: Partial<BoxUnselected>;
225
  marker?: Partial<BoxMarker>;
226
  line?: Partial<BoxLine>;
227
  fillcolor?: string;
228
  pointpos?: number;
229
  jitter?: number;
230
}
231

232
interface BoxMarker {
233
  color?: string;
234
  size?: number;
235
  opacity?: number;
236
  outliercolor?: string;
237
  symbol?: string;
238
  line?: {
239
    color?: string;
240
    width?: number;
241
    outliercolor?: string;
242
    outlierwidth?: number;
243
  };
244
}
245

246
interface BoxLine {
247
  color?: string;
248
  width?: number;
249
}
250
```
251

252
**Usage Examples:**
253

254
```javascript
255
// Basic box plot
256
const boxData = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20];
257
Plotly.newPlot('myDiv', [{
258
    y: boxData,
259
    type: 'box',
260
    name: 'Sample Data'
261
}]);
262

263
// Box plot with all points shown
264
Plotly.newPlot('myDiv', [{
265
    y: boxData,
266
    type: 'box',
267
    boxpoints: 'all',
268
    boxmean: true,
269
    name: 'Data with Points'
270
}]);
271

272
// Grouped box plots
273
const group1 = Array.from({length: 50}, () => Math.random() * 10);
274
const group2 = Array.from({length: 50}, () => Math.random() * 8 + 3);
275
const group3 = Array.from({length: 50}, () => Math.random() * 12 + 1);
276

277
Plotly.newPlot('myDiv', [
278
    {
279
        y: group1,
280
        type: 'box',
281
        name: 'Group A',
282
        marker: { color: 'red' }
283
    },
284
    {
285
        y: group2,
286
        type: 'box',
287
        name: 'Group B',
288
        marker: { color: 'blue' }
289
    },
290
    {
291
        y: group3,
292
        type: 'box',
293
        name: 'Group C',
294
        marker: { color: 'green' }
295
    }
296
]);
297

298
// Horizontal box plots
299
Plotly.newPlot('myDiv', [{
300
    x: boxData,
301
    type: 'box',
302
    orientation: 'h',
303
    name: 'Horizontal Box'
304
}]);
305

306
// Box plot with custom statistics
307
Plotly.newPlot('myDiv', [{
308
    type: 'box',
309
    q1: [1, 2, 3],
310
    median: [2, 3, 4],
311
    q3: [3, 4, 5],
312
    lowerfence: [0, 1, 2],
313
    upperfence: [4, 5, 6],
314
    mean: [2.2, 3.1, 4.3],
315
    sd: [0.5, 0.8, 0.6],
316
    y: ['A', 'B', 'C'],
317
    orientation: 'h'
318
}]);
319
```
320

321
### Violin Plots
322

323
Distribution visualization combining box plot and kernel density estimation.
324

325
```javascript { .api }
326
/**
327
 * Violin plot trace configuration
328
 */
329
interface ViolinTrace {
330
  type: 'violin';
331
  x?: any[];
332
  y?: number[];
333
  name?: string;
334
  orientation?: 'v' | 'h';
335
  side?: 'both' | 'positive' | 'negative';
336
  width?: number;
337
  points?: 'all' | 'outliers' | 'suspectedoutliers' | false;
338
  pointpos?: number;
339
  jitter?: number;
340
  box?: Partial<ViolinBox>;
341
  meanline?: Partial<ViolinMeanLine>;
342
  span?: [number, number];
343
  spanmode?: 'soft' | 'hard' | 'manual';
344
  bandwidth?: number;
345
  scalegroup?: string;
346
  scalemode?: 'width' | 'count';
347
  marker?: Partial<ViolinMarker>;
348
  line?: Partial<ViolinLine>;
349
  fillcolor?: string;
350
}
351

352
interface ViolinBox {
353
  visible?: boolean;
354
  width?: number;
355
  fillcolor?: string;
356
  line?: {
357
    color?: string;
358
    width?: number;
359
  };
360
}
361

362
interface ViolinMeanLine {
363
  visible?: boolean;
364
  color?: string;
365
  width?: number;
366
}
367

368
interface ViolinMarker {
369
  color?: string;
370
  size?: number;
371
  opacity?: number;
372
  symbol?: string;
373
  outliercolor?: string;
374
  line?: {
375
    color?: string;
376
    width?: number;
377
    outliercolor?: string;
378
    outlierwidth?: number;
379
  };
380
}
381

382
interface ViolinLine {
383
  color?: string;
384
  width?: number;
385
}
386
```
387

388
**Usage Examples:**
389

390
```javascript
391
// Basic violin plot
392
const violinData = Array.from({length: 100}, () => 
393
    Math.random() * 5 + Math.random() * 3
394
);
395

396
Plotly.newPlot('myDiv', [{
397
    y: violinData,
398
    type: 'violin',
399
    name: 'Distribution'
400
}]);
401

402
// Violin plot with box plot inside
403
Plotly.newPlot('myDiv', [{
404
    y: violinData,
405
    type: 'violin',
406
    box: {
407
        visible: true,
408
        width: 0.5
409
    },
410
    meanline: {
411
        visible: true
412
    },
413
    name: 'Violin with Box'
414
}]);
415

416
// Split violin plots
417
const leftData = Array.from({length: 50}, () => Math.random() * 8);
418
const rightData = Array.from({length: 50}, () => Math.random() * 6 + 2);
419

420
Plotly.newPlot('myDiv', [
421
    {
422
        y: leftData,
423
        type: 'violin',
424
        side: 'negative',
425
        name: 'Left Side',
426
        fillcolor: 'lightblue'
427
    },
428
    {
429
        y: rightData,
430
        type: 'violin',
431
        side: 'positive',
432
        name: 'Right Side',
433
        fillcolor: 'lightcoral'
434
    }
435
]);
436

437
// Violin plot with all points
438
Plotly.newPlot('myDiv', [{
439
    y: violinData,
440
    type: 'violin',
441
    points: 'all',
442
    pointpos: 0,
443
    jitter: 0.3,
444
    marker: {
445
        size: 4,
446
        color: 'red'
447
    }
448
}]);
449
```
450

451
### Strip Charts
452

453
One-dimensional scatter plots for showing individual data points.
454

455
```javascript { .api }
456
/**
457
 * Strip chart using scatter trace with categorical x-axis
458
 */
459
interface StripChart {
460
  type: 'scatter';
461
  x: string[];
462
  y: number[];
463
  mode: 'markers';
464
  marker: {
465
    size?: number;
466
    opacity?: number;
467
    color?: string | string[];
468
  };
469
  transforms?: [{
470
    type: 'groupby';
471
    groups: string[];
472
    styles: any[];
473
  }];
474
}
475
```
476

477
**Usage Examples:**
478

479
```javascript
480
// Basic strip chart
481
const categories = Array.from({length: 100}, (_, i) => 
482
    ['A', 'B', 'C', 'D'][Math.floor(i / 25)]
483
);
484
const values = Array.from({length: 100}, () => Math.random() * 10);
485

486
Plotly.newPlot('myDiv', [{
487
    x: categories,
488
    y: values,
489
    type: 'scatter',
490
    mode: 'markers',
491
    marker: {
492
        size: 8,
493
        opacity: 0.6
494
    }
495
}]);
496

497
// Strip chart with jitter (simulated)
498
const jitteredX = categories.map(cat => 
499
    cat + (Math.random() - 0.5) * 0.3
500
);
501

502
Plotly.newPlot('myDiv', [{
503
    x: jitteredX,
504
    y: values,
505
    type: 'scatter',
506
    mode: 'markers',
507
    marker: {
508
        size: 6,
509
        opacity: 0.7,
510
        color: values,
511
        colorscale: 'Viridis'
512
    }
513
}]);
514
```
515

516
### Error Bars
517

518
Statistical error visualization for scatter plots and bar charts.
519

520
```javascript { .api }
521
/**
522
 * Error bar configuration
523
 */
524
interface ErrorBars {
525
  visible?: boolean;
526
  type?: 'percent' | 'constant' | 'sqrt' | 'data';
527
  symmetric?: boolean;
528
  array?: number[];
529
  arrayminus?: number[];
530
  value?: number;
531
  valueminus?: number;
532
  traceref?: number;
533
  tracerefminus?: number;
534
  copy_ystyle?: boolean;
535
  copy_zstyle?: boolean;
536
  color?: string;
537
  thickness?: number;
538
  width?: number;
539
}
540
```
541

542
**Usage Examples:**
543

544
```javascript
545
// Scatter plot with error bars
546
const xData = [1, 2, 3, 4, 5];
547
const yData = [2, 4, 3, 6, 5];
548
const yError = [0.5, 0.8, 0.3, 1.0, 0.7];
549

550
Plotly.newPlot('myDiv', [{
551
    x: xData,
552
    y: yData,
553
    type: 'scatter',
554
    mode: 'markers',
555
    error_y: {
556
        type: 'data',
557
        array: yError,
558
        visible: true,
559
        color: 'red',
560
        thickness: 2,
561
        width: 5
562
    },
563
    marker: {
564
        size: 10,
565
        color: 'blue'
566
    }
567
}]);
568

569
// Bar chart with error bars
570
Plotly.newPlot('myDiv', [{
571
    x: ['A', 'B', 'C', 'D'],
572
    y: [20, 14, 23, 25],
573
    type: 'bar',
574
    error_y: {
575
        type: 'percent',
576
        value: 10,
577
        visible: true
578
    }
579
}]);
580

581
// Asymmetric error bars
582
Plotly.newPlot('myDiv', [{
583
    x: xData,
584
    y: yData,
585
    type: 'scatter',
586
    mode: 'markers',
587
    error_y: {
588
        type: 'data',
589
        symmetric: false,
590
        array: [0.8, 1.0, 0.5, 1.2, 0.9],
591
        arrayminus: [0.3, 0.4, 0.2, 0.6, 0.4],
592
        visible: true
593
    }
594
}]);
595
```
596

597
### Distribution Plots Layout
598

599
Layout configurations commonly used with statistical charts.
600

601
```javascript { .api }
602
/**
603
 * Statistical chart layout options
604
 */
605
interface StatisticalLayout {
606
  boxmode?: 'group' | 'overlay';
607
  boxgap?: number;
608
  boxgroupgap?: number;
609
  violinmode?: 'group' | 'overlay';
610
  violingap?: number;
611
  violingroupgap?: number;
612
  barnorm?: '' | 'fraction' | 'percent';
613
  barmode?: 'stack' | 'group' | 'overlay' | 'relative';
614
}
615
```
616

617
**Usage Examples:**
618

619
```javascript
620
// Grouped box plots layout
621
Plotly.newPlot('myDiv', boxTraces, {
622
    boxmode: 'group',
623
    boxgap: 0.3,
624
    boxgroupgap: 0.1,
625
    title: 'Grouped Box Plots'
626
});
627

628
// Overlaid violin plots
629
Plotly.newPlot('myDiv', violinTraces, {
630
    violinmode: 'overlay',
631
    title: 'Overlaid Violin Plots'
632
});
633

634
// Normalized histogram
635
Plotly.newPlot('myDiv', histogramTraces, {
636
    barmode: 'overlay',
637
    barnorm: 'percent',
638
    title: 'Normalized Histograms'
639
});
640
```