Debian Codegraph @

texmf-dist/doc/latex/tikzviolinplots/tikzviolinplots.tex

raw
1 %% tikzviolinplots.tex
2 %% Copyright 2026 Pedro Callil-Soares
3 %
4 % This work may be distributed and/or modified under the
5 % conditions of the LaTeX Project Public License, either version 1.3
6 % of this license or (at your option) any later version.
7 % The latest version of this license is in
8 % http://www.latex-project.org/lppl.txt
9 % and version 1.3 or later is part of all distributions of LaTeX
10 % version 2005/12/01 or later.
11 %
12 % This work has the LPPL maintenance status `maintained'.
13 %
14 % The Current Maintainer of this work is Pedro Callil-Soares.
15 %
16 % This work consists of the files tikzviolinplots.sty and
17 % tikzviolinplots.tex.
18
19 \documentclass{article}
20
21 \usepackage{amsmath}
22 \usepackage{pgfplots}
23 \pgfplotsset{width=\textwidth,compat=1.18}
24 \usepgfplotslibrary{statistics}
25 \usepackage{tikzviolinplots}
26 \usepgfplotslibrary{external}
27 \tikzexternalize
28 \usetikzlibrary{arrows.meta}
29 \usetikzlibrary{decorations.text}
30 \usetikzlibrary{decorations.pathmorphing}
31 \usepackage{minted}
32 \usemintedstyle{gruvbox-light}
33 \usepackage{scontents}
34 \usepackage{wasysym}
35 \usepackage{microtype}
36 \usepackage{subcaption}
37 \usepackage{hyperref}
38
39 \begin{scontents}[write-out=violinandboxplotexample.dat]
40 A B C D
41 0.876 0.574 2.175 1.684
42 1.015 0.822 2.121 2.290
43 0.995 1.266 1.916 2.184
44 1.101 0.740 2.044 2.065
45 1.222 0.636 2.004 2.248
46 0.712 1.753 2.038 2.200
47 1.063 0.873 1.974 1.865
48 0.973 1.020 2.145 1.895
49 1.174 0.763 2.052 2.240
50 1.057 1.293 2.079 2.360
51 1.004 0.853 2.064 1.695
52 0.909 0.694 2.136 1.837
53 1.108 0.849 2.000 1.744
54 1.210 0.468 2.010 1.820
55 0.958 0.767 1.824 2.158
56 1.119 0.940 2.034 1.846
57 1.000 0.962 1.967 2.545
58 0.954 1.551 1.833 1.816
59 0.918 0.755 1.914 2.369
60 1.093 0.973 1.997 1.543
61 \end{scontents}
62
63 \begin{scontents}[write-out=example.dat]
64 A B C D E
65 0.3 -2.1 3.50 2.89 1.00
66 0.41 -1.9 3.55 2.88 1.06
67 0.45 -1.5 3.55 3.13 1.00
68 0.46 -1.3 3.60 2.69 1.20
69 0.46 -1.3 3.60 2.78 1.00
70 0.46 -1.27 3.60 2.83 1.35
71 0.47 -1.26 3.65 3.08 1.00
72 0.47 -1.26 3.65 3.08 1.53
73 0.48 -1.24 3.65 2.73 1.00
74 0.51 -1.2 3.65 3.08 1.73
75 0.57 -1.13 3.65 3.24 1.00
76 2.3 -1.02 3.70 3.10 1.95
77 2.41 -0.9 3.70 2.98 1.00
78 2.46 -0.2 3.70 2.98 2.21
79 2.47 0.0 3.75 3.04 1.00
80 2.48 0.1 3.80 3.24 2.49
81 2.51 0.3 3.85 3.16 1.00
82 2.57 0.5 3.85 3.30 3.04
83 \end{scontents}
84
85 \title{The \texttt{tikzviolinplots} package}
86 \author{Pedro Callil-Soares}
87 \date{March 31, 2026}
88
89 \begin{document}
90
91 \maketitle
92
93 \tableofcontents
94
95 \begin{abstract}
96 The package provides commands for violin plot creation and
97 the kernel density estimations required.
98 \end{abstract}
99
100 \section{Introduction}
101
102 This package, through the use of the package \texttt{pgfplots}, allows the
103 creation of violin plots in \LaTeX. Violin plots are similar to boxplots,
104 but instead of a box signalling the average and quartiles, a kernel density
105 estimator is plotted, as in equation \ref{eq:kde}, in which the function $k$
106 (the kernel) is a probability distribution, the positive number $h$ (the
107 bandwidth) is a smoothing factor and $n$ is the sample size.
108
109 \begin{equation}
110 \label{eq:kde}
111 \textnormal{KDE}(x) = %
112 \cfrac{1}{nh}\sum_{i=1}^nk\left(\cfrac{x-x_i}{h}\right)
113 \end{equation}
114
115 A comparison between the two plots, showcasing its similarities, is
116 shown in figures \ref{fig:example}. The violin plot in figure
117 \ref{graph:violin_example} assumes normal data, and the bandwidth
118 (smoothing factor $h$ in equation \ref{eq:kde}) is defined accordingly.
119
120 % \pgfplotsset{height=1.6\linewidth}
121
122 \begin{figure}[h!]
123 \centering
124 \begin{subfigure}{0.5\textwidth}
125 \centering
126 \begin{tikzpicture}
127 \begin{axis}
128 [
129 boxplot/draw direction=y,
130 height=1.6\linewidth,
131 ymax=3, ymin=0,
132 xmin=0, xmax=5,
133 ymajorgrids=true,
134 xtick={1,2,3,4},
135 xticklabels={$\alpha$,$\beta$,$\gamma$,$\delta$},
136 ylabel={Some property},
137 ]
138 \addplot+[boxplot,
139 blue!100!red,
140 fill=blue!100!red,
141 fill opacity=0.50,
142 no marks]
143 table [y=A] {violinandboxplotexample.dat};
144 \addplot+[boxplot,
145 blue!66!red,
146 fill=blue!66!red,
147 fill opacity=0.50,
148 no marks]
149 table [y=B] {violinandboxplotexample.dat};
150 \addplot+[boxplot,
151 blue!33!red,
152 fill=blue!33!red,
153 fill opacity=0.50,
154 no marks]
155 table [y=C] {violinandboxplotexample.dat};
156 \addplot+[boxplot,
157 blue!0!red,
158 fill=blue!0!red,
159 fill opacity=0.50,
160 no marks]
161 table [y=D] {violinandboxplotexample.dat};
162 \end{axis}
163 \end{tikzpicture}
164 \caption{Box plot}
165 \label{graph:box_example}
166 \end{subfigure}%
167 \hfill%
168 \begin{subfigure}{0.5\textwidth}
169 \centering
170 \begin{tikzpicture}
171 \violinplotsset[
172 averages,
173 data points,
174 scaled,
175 ]{
176 height=1.6\linewidth,
177 xmin=0,xmax=5,
178 ymin=0,ymax=3,
179 % xlabel style={
180 % yshift = {-2*height("a")}
181 % },
182 ymajorgrids=true,
183 ylabel={Same property},
184 }
185 \violinplotwholefile[%
186 primary color=red,
187 secondary color=blue,
188 indexes={A,B,C,D},
189 spacing=1.0,
190 labels={%
191 $\alpha$,
192 $\beta$,
193 $\gamma$,
194 $\delta$,
195 },
196 col sep=tab,
197 dataset size=1pt,
198 dataset mark=*,
199 dataset fill=black!50!white,
200 dataset fill opacity=1.0,
201 average mark=x,
202 average size=5pt,
203 ]{violinandboxplotexample.dat}
204 \end{tikzpicture}
205 \caption{Violin plot}
206 \label{graph:violin_example}
207 \end{subfigure}
208 \caption{Box and violin plot examples}
209 \label{fig:example}
210 \end{figure}
211
212 % \pgfplotsset{height=0.9\linewidth}
213
214 \section{Usage}
215
216 To plot a violin plot with the commands provided, one must, inside
217 a \texttt{tikzpicture} environment, set the general options to all
218 plots and insert each individual dataset.
219
220 To set the general options, the command \texttt{{\textbackslash}violinplotsset}
221 is provided, and may be invoked before plotting the datasets. This should
222 be done with the commands \texttt{{\textbackslash}violinplot},
223 \texttt{{\textbackslash}violinplotwholefile} (which require the definition of
224 the plotting window, at least, with \texttt{{\textbackslash}violinplotsset}),
225 or, inside an \texttt{axis} environment, with the
226 \texttt{{\textbackslash}addviolinplot} command. The latter is recommended (since
227 it has a better performance and allows for better integration with
228 \texttt{pgfplots}).
229
230 \subsection{General options: \texttt{{\textbackslash}violinplotsset}}
231
232 The command \texttt{{\textbackslash}violinplotsset}\footnote{%
233 An alias for the legacy (yet still available)
234 \texttt{{\textbackslash}violinsetoptions} macro.
235 } takes two arguments, an optional argument with package-specific options and a
236 mandatory argument with options to be passed to \texttt{pgfplots}.
237
238 \begin{minted}[escapeinside=||]{latex}
239 \violinplotsset[|\textit{<package-specific options>}|]%
240 {|\textit{<pgfplots general options>}|}
241 \end{minted}
242
243 \subsubsection{Package-specific options}
244
245 There are five options specific to the package: \texttt{scaled},
246 \texttt{data points}, \texttt{averages}, \texttt{no mirror} and
247 \texttt{reverse axis}, controlling how and which information
248 in the datasets should be presented.
249
250 The option \texttt{scaled} controls if all plots in the graph
251 have the same area or same width. If passed, the kernel
252 distribution estimations will be scaled to the same width, as
253 shown in figure \ref{graph:violin_verti}; otherwise, the plots
254 will present the same area, as in figure \ref{graph:violin_horiz}.
255
256 The option \texttt{data points}, if passed, will show, along with
257 the violin plots, the distribution of points in the data set, as shown in
258 figure \ref{graph:violin_verti}.
259
260 If the option \texttt{averages} is passed, the average of the data set
261 elements is shown, as in figure \ref{graph:violin_horiz}.
262
263 The plots are mirrored by default; however, passing the option \texttt{no mirror}
264 will show only half the plot, as shown in figure \ref{graph:violin_horiz}.
265
266 Finally, to ``transpose'' the plots (\textit{i.e.}, show the distributions
267 as functions of the abcissa, as in figure \ref{graph:violin_horiz},
268 and not as functions of ordinate, as in figure \ref{graph:violin_verti}),
269 one might use the option \texttt{reverse axis}.
270
271 \subsubsection{Plot limits and other \texttt{pgfplots} options}
272
273 When using the \texttt{{\textbackslash}violinplot} and
274 \texttt{{\textbackslash}violinplotwholefile} interfaces,
275 the minima and maxima of the plot axes must be set in the second (and first
276 mandatory) argument to the command, and should follow \texttt{pgfplots}
277 syntax. For instance, to set the minimum and maximum of the $x$-axis
278 to $-3$ and 6, and of the $y$-axis to $2.5$ and 7, one might use:
279
280 \begin{minted}[escapeinside=||]{latex}
281 \violinplotsset[|\textit{<package-specific options>}|]%
282 {xmin=-3, xmax=6, ymin=2.5, xmin=7,%
283 |\textit{<pgfplots general options>}|}
284 \end{minted}
285
286 Other \texttt{pgfplots} expressions such as title or axes labels may be set
287 in the same way in this argument.
288
289 \subsection{Options for each dataset: \texttt{{\textbackslash}addviolinplot}}
290
291 If the data sets are not very similar and/or advanced customizations
292 are desired, \texttt{{\textbackslash}addviolinplot} should be used to
293 plot each data set individually.
294 The \texttt{{\textbackslash}addviolinplot} macro works similarly to
295 \texttt{pgfplots}' \texttt{{\textbackslash}addplot}:
296
297 \begin{minted}[escapeinside=||]{latex}
298 \begin{tikzpicture}
299 \violinplotsset[|\textit{<package-specific options>}|]%
300 {|\textit{<pgfplots general options>}|}
301 \begin{axis}[%
302 |\textit{axis options}|
303 ]
304 \addviolinplot[%
305 |\textit{<option>}=\textit{<value>}|
306 ]{|\textit{filename}|}
307 \begin{axis}
308 \end{tikzpicture}
309 \end{minted}
310
311 The filename (mandatory argument) must be a path to a file storing the data as
312 comma-separated columns. The optional argument is a list of options, including:
313
314 \begin{itemize}
315 \item \texttt{col sep}: Column separation character in filename.
316 Defaults to \texttt{comma}, and can accept options
317 \texttt{space}, \texttt{tab}, \texttt{comma},
318 \texttt{colon}, \texttt{semicolon}, \texttt{braces},
319 \texttt{\&} and \texttt{ampersand}.
320 \item \texttt{index}: Necessary option, is the name of the column with
321 the data to be plotted.
322 \item \texttt{frequencies}: If set, is the name of the column with
323 the frequencies of the data to be plotted.
324 \item \texttt{kernel}: The function to be used for the kernel density
325 estimation; available values are \texttt{gaussian} (default),
326 \texttt{logistic}, \texttt{parabolic}, \texttt{uniform}
327 and \texttt{triangular}.
328 \item \texttt{bandwidth}: Smoothing parameter for the kernel density
329 estimation; defaults to $h$ in equation \ref{eq:band},
330 which assumes gaussian distribution.
331 \begin{equation}
332 \label{eq:band}
333 h=\sqrt[5]{\frac{4\times\textnormal{stddev}%
334 \left(x_1,x_2,\ldots,x_n\right)^5}{3n}}
335 \end{equation}
336 \item \texttt{samples}: Number of points in which the kernel density
337 estimation will be calculated and plotted. Defaults
338 to 50.
339 \item \texttt{relative position}: position of the plot in the axis
340 with the labels for each dataset. Defaults to 0.
341 \item \texttt{color}: Color of the plot, border and interior.
342 Defaults to black.
343 \item \texttt{fill opacity}: Interior opacity of the plot, defaults to
344 0.5.
345 \item \texttt{label}: Label of the plot, positioned at the point
346 set by \texttt{relative position}.
347 \item \texttt{data label style}: style options for the data label (that
348 is, \texttt{xticklabel style} if package-specific option
349 \texttt{reverse axis} is not set, or \texttt{yticklabel style}
350 otherwise).
351 \item \texttt{invert}: If \texttt{true}, the plot will be drawn in the
352 opposite side. Useful for comparing two parts of a data set, by
353 plotting each group side by side.
354 \item Options for average and data points:
355 \begin{itemize}
356 \item \texttt{average mark}, \texttt{dataset mark}: Mark used
357 for averages and points of the data set (defaults
358 to ``\texttt{x}'' and ``\texttt{*}'', respectively).
359 \item \texttt{average size}, \texttt{dataset size}: Size
360 of each mark (defaults to 3pt for averages and 1pt
361 for other points).
362 \item \texttt{average color}, \texttt{dataset color}: Color
363 of each mark's border. Defaults to black in both
364 cases.
365 \item \texttt{average opacity}, \texttt{dataset opacity}:
366 Border opacity. Defaults to 1.0 in both cases.
367 \item \texttt{average fill}, \texttt{dataset fill}: Color
368 of each mark's interior. Defaults to black for the
369 points of the data set and white for the averages.
370 \item \texttt{average fill opacity}, \texttt{dataset fill opacity}:
371 Opacity of the marks. Defaults to 0.5 for averages and
372 0.2 for the other points.
373 \item \texttt{dataset jitter}:
374 Amount by which to randomly jitter the marks. May help
375 with distinguishing overlapping points. Defaults to
376 $0.0$ (\textit{i.e.}, no jitter).
377 \end{itemize}
378 \end{itemize}
379
380 These options are kept from plot to plot: that means, for instance, that setting
381 \texttt{invert=true} for a plot requires setting \texttt{invert=false}
382 afterwards to toggle its value for the subsequent plots.
383
384 \subsection{Options for each data set: \texttt{{\textbackslash}violinplot}}
385
386 This is a legacy macro, very similar to the one introduced in a previous
387 section. It is kept for backwards compatibility, and its options are the same as
388 the ones for \texttt{{\textbackslash}addviolinplot}.
389 This command takes one mandatory argument, and a list of options:
390
391 \begin{minted}[escapeinside=||]{latex}
392 \begin{tikzpicture}
393 \violinplotsset[|\textit{<package-specific options>}|]%
394 {|\textit{<pgfplots general options>}|}
395 \violinplot[%
396 |\textit{<option>}=\textit{<value>}|
397 ]{|\textit{filename}|}
398 \end{tikzpicture}
399 \end{minted}
400
401 \subsection{Simplified interface: \texttt{{\textbackslash}violinplotwholefile}}
402
403 If the data sets are similar and no customizations are required, one might
404 use the command \texttt{{\textbackslash}violinplotwholefile}.
405
406 \begin{minted}[escapeinside=||]{latex}
407 \begin{tikzpicture}
408 \violinplotwholefile[%
409 |\textit{<option>}=\textit{<value>}|
410 ]{|\textit{filename}|}
411 \end{tikzpicture}
412 \end{minted}
413
414 This command will calculate and plot all columns named. The available options
415 are:
416
417 \begin{itemize}
418 \item \texttt{primary color}: Primary color utilised. A gradient is built from
419 the secondary color to it. Defaults to black.
420 \item \texttt{secondary color}: Secondary color utilized. A
421 gradient is built from it to the primary color. Defaults
422 to white.
423 \item \texttt{indexes}: List of columns to be plotted.
424 \item \texttt{spacing}: Distance between plots. Defaults to 1.0.
425 \item \texttt{labels}: Labels of the data to be plotted.
426 \end{itemize}
427
428 Besides, the options available to \texttt{{\textbackslash}violinplots} are also
429 available for this command; for instance, one might set the kernel to
430 be utilized as the \texttt{uniform} kernel through the option
431 \texttt{kernel=uniform}. Of course, \texttt{relative position} is not an option
432 here.
433
434 \section{Examples}
435
436 To show the usage of the package, we plotted several data sets, in figures
437 \ref{graph:violin_verti} to \ref{graph:kde_standalone}, using the three
438 available interfaces. Besides, a real-world example, with more complex data, is
439 also plotted (figure \ref{graph:asymmetrical}).
440
441 The data are in the file \texttt{example.dat}, shown below:
442
443 \colorlet{mintedbgcsv}{black!10!white}
444
445 \inputminted[%
446 frame=single,
447 rulecolor=mintedbgcsv,
448 framesep=10pt,
449 bgcolor=mintedbgcsv,
450 obeytabs,
451 tabsize=12,
452 ]{text}{example.dat}
453
454 \subsection{Simplified interface}
455
456 First we will plot this data using the simplified interface, resulting in
457 figure \ref{graph:violin_verti}.
458
459 \begin{figure}[h]
460 \centering
461 \begin{tikzpicture}
462 \violinplotsset[
463 data points,
464 scaled,
465 ]{
466 xmin=0,xmax=6,
467 ymin=-4,ymax=6,
468 title={Plotting Some Data},
469 xlabel={Groups},
470 ylabel={Some property},
471 % xlabel style={
472 % yshift = {-3*height("a")}
473 % },
474 ymajorgrids=true,
475 }
476 \violinplotwholefile[%
477 primary color=orange,
478 secondary color=black,
479 indexes={C,B,A,D,E},
480 spacing=1.0,
481 labels={%
482 $\alpha$,
483 $\beta$,
484 $\gamma$,
485 $\delta$,
486 $\epsilon$
487 },
488 col sep=tab,
489 dataset size=2pt,
490 dataset mark=diamond*,
491 dataset fill=blue!50!white,
492 dataset fill opacity=1.0,
493 data label style={rotate=-45},
494 ]{example.dat}
495 \end{tikzpicture}
496 \caption{Violin plot --- vertical example}
497 \label{graph:violin_verti}
498 \end{figure}
499
500 Code for figure \ref{graph:violin_verti}, using
501 \texttt{{\textbackslash}violinplotwholefile}:
502
503 \colorlet{mintedbgverti}{orange!10!white}
504
505 \begin{minted}[%
506 escapeinside=||,
507 frame=single,
508 rulecolor=mintedbgverti,
509 framesep=10pt,
510 tabsize=4,
511 bgcolor=mintedbgverti]{latex}
512 \begin{tikzpicture}
513 \violinplotsset[
514 data points,
515 scaled,
516 ]{
517 xmin=0,xmax=6,
518 ymin=-4,ymax=6,
519 title={Plotting Some Data},
520 xlabel={Groups},
521 ylabel={Some property},
522 % xlabel style={
523 % yshift = {-3*height("a")}
524 % },
525 ymajorgrids=true,
526 }
527 \violinplotwholefile[%
528 primary color=orange,
529 secondary color=black,
530 indexes={C,B,A,D,E},
531 spacing=1.0,
532 labels={%
533 $\alpha$,
534 $\beta$,
535 $\gamma$,
536 $\delta$,
537 $\epsilon$
538 },
539 col sep=tab,
540 dataset size=2pt,
541 dataset mark=diamond*,
542 dataset fill=blue!50!white,
543 dataset fill opacity=1.0,
544 data label style={rotate=-45},
545 ]{example.dat}
546 \end{tikzpicture}
547 \end{minted}
548
549 \subsection{Complete interface}
550
551 Then the data will be plotted using the complete interface, resulting
552 in figure \ref{graph:violin_horiz}.
553
554 \begin{figure}[h]
555 \centering
556 \begin{tikzpicture}
557 \violinplotsset[
558 no mirror,
559 averages,
560 reverse axis,
561 ]{%
562 xmin=-4,xmax=6,
563 ymin=0.7,ymax=7,
564 title={Plotting Some Data},
565 ylabel={Groups},
566 xlabel={Some property},
567 % ylabel style={
568 % yshift = {2*width("a")}
569 % },
570 xmajorgrids=true,
571 }
572 \violinplot[%
573 index=C,
574 relative position=1,
575 color=blue!0!black,
576 label={$\alpha$},
577 col sep=tab,
578 ]{example.dat}
579 \violinplot[%
580 index=B,
581 relative position=2,
582 color=blue!25!black,
583 label={$\beta$},
584 col sep=tab,
585 ]{example.dat}
586 \violinplot[%
587 index=A,
588 relative position=3,
589 color=blue!50!black,
590 fill opacity=1.0,
591 label={$\gamma$},
592 col sep=tab,
593 kernel=parabolic,
594 samples=100,
595 bandwidth=0.4,
596 average mark=otimes*,
597 average size=2pt,
598 average fill=blue!70!black,
599 average fill opacity=0.7,
600 ]{example.dat}
601 \violinplot[%
602 index=D,
603 relative position=4,
604 color=blue!75!black,
605 label={$\delta$},
606 col sep=tab,
607 ]{example.dat}
608 \violinplot[%
609 index=E,
610 relative position=5,
611 color=blue!100!black,
612 label={$\epsilon$},
613 col sep=tab,
614 ]{example.dat}
615 \end{tikzpicture}
616 \caption{Violin plot --- horizontal example}
617 \label{graph:violin_horiz}
618 \end{figure}
619
620 Code for figure \ref{graph:violin_horiz}, using
621 \texttt{{\textbackslash}violinplot}:
622
623 \colorlet{mintedbghoriz}{blue!10!white}
624
625 \begin{minted}[%
626 escapeinside=||,
627 frame=single,
628 rulecolor=mintedbghoriz,
629 framesep=10pt,
630 tabsize=4,
631 bgcolor=mintedbghoriz]{latex}
632 \begin{tikzpicture}
633 \violinplotsset[
634 no mirror,
635 averages,
636 reverse axis,
637 ]{%
638 xmin=-4,xmax=6,
639 ymin=0.7,ymax=7,
640 title={Plotting Some Data},
641 ylabel={Groups},
642 xlabel={Some property},
643 % ylabel style={
644 % yshift = {2*width("a")}
645 % },
646 xmajorgrids=true,
647 }
648 \violinplot[%
649 index=C,
650 relative position=1,
651 color=blue!0!black,
652 label={$\alpha$},
653 col sep=tab,
654 ]{example.dat}
655 \violinplot[%
656 index=B,
657 relative position=2,
658 color=blue!25!black,
659 label={$\beta$},
660 col sep=tab,
661 ]{example.dat}
662 \violinplot[%
663 index=A,
664 relative position=3,
665 color=blue!50!black,
666 fill opacity=1.0,
667 label={$\gamma$},
668 col sep=tab,
669 kernel=parabolic,
670 samples=100,
671 bandwidth=0.4,
672 average mark=otimes*,
673 average size=2pt,
674 average fill=blue!70!black,
675 average fill opacity=0.7,
676 ]{example.dat}
677 \violinplot[%
678 index=D,
679 relative position=4,
680 color=blue!75!black,
681 label={$\delta$},
682 col sep=tab,
683 ]{example.dat}
684 \violinplot[%
685 index=E,
686 relative position=5,
687 color=blue!100!black,
688 label={$\epsilon$},
689 col sep=tab,
690 ]{example.dat}
691 \end{tikzpicture}
692 \end{minted}
693
694 \subsection{Drawings and annotations}
695
696 As everything happens inside a \texttt{tikzpicture} environment, drawings
697 and annotations are straightforward, as seen in figure \ref{graph:violin_annotations}.
698
699 \begin{figure}[h]
700 \centering
701 \begin{tikzpicture}
702 \violinplotsset[
703 averages,
704 data points,
705 ]{}
706 \begin{axis}[
707 xmin=0,xmax=6,
708 ymin=-2,ymax=5,
709 xlabel = {Bandwidth choice},
710 ylabel = {Some property},
711 title={Problems with Different Distributions},
712 ymajorgrids=true,
713 ]
714 \addviolinplot[%
715 index=A,
716 relative position=1,
717 color=green!33!black,
718 label={Estimated bandwidth},
719 col sep=tab,
720 dataset jitter=0.2,
721 ]{example.dat}
722 \addviolinplot[%
723 index=A,
724 bandwidth=0.1,
725 relative position=4,
726 color=green!12!black,
727 label={Smaller bandwidth},
728 col sep=tab,
729 dataset jitter=0.6,
730 samples=300,
731 ]{example.dat}
732 \draw[-{Stealth}] (axis cs: 1.75,0.45) %
733 .. controls (axis cs:1.75,0.85) and %
734 (axis cs:3.9,0.5) .. (axis cs: 3.9,1.05);
735 \draw[decoration={raise=2pt,text along path, text=%
736 {|\small|Better bandwidth}, text align={center}}, %
737 decorate] %
738 (axis cs: 1.75,0.45) %
739 .. controls (axis cs:1.75,0.85) and %
740 (axis cs:3.9,0.5) .. (axis cs: 3.9,1.05);
741 \draw[-{Stealth}] %
742 (axis cs: 1.5,0.45) .. controls (axis cs:1.5,0.85) %
743 and (axis cs:1.25,1.1) .. (axis cs: 1.25,1.5) .. %
744 controls (axis cs:1.25,1.9) and (axis cs:1.35,1.9) %
745 .. (axis cs:1.35,2.6);
746 \draw[decoration={raise=2pt,text along path, text=%
747 {|\small|Oversmoothed}, text align={center}}, %
748 decorate] %
749 (axis cs: 1.35,2.6) .. controls (axis cs:1.35,1.9) %
750 and (axis cs:1.25,1.9) .. (axis cs: 1.25,1.5) .. %
751 controls (axis cs:1.25,1.1) and (axis cs:1.5,0.85) %
752 .. (axis cs:1.5,0.45);
753 \end{axis}
754 \end{tikzpicture}
755 \caption{Annotations in a plot}
756 \label{graph:violin_annotations}
757 \end{figure}
758
759 Figure \ref{graph:violin_annotations} is compiled from the code excerpt below.
760
761 \colorlet{mintedbgannot}{green!10!white}
762
763 \begin{minted}[%
764 escapeinside=||,
765 frame=single,
766 rulecolor=mintedbgannot,
767 framesep=10pt,
768 tabsize=4,
769 bgcolor=mintedbgannot]{latex}
770 \begin{tikzpicture}
771 \violinplotsset[
772 averages,
773 data points,
774 ]{}
775 \begin{axis}[
776 xmin=0,xmax=6,
777 ymin=-2,ymax=5,
778 xlabel = {Bandwidth choice},
779 ylabel = {Some property},
780 title={Problems with Different Distributions},
781 ymajorgrids=true,
782 ]
783 \addviolinplot[%
784 index=A,
785 relative position=1,
786 color=green!33!black,
787 label={Estimated bandwidth},
788 col sep=tab,
789 dataset jitter=0.2,
790 ]{example.dat}
791 \addviolinplot[%
792 index=A,
793 bandwidth=0.1,
794 relative position=4,
795 color=green!12!black,
796 label={Smaller bandwidth},
797 col sep=tab,
798 dataset jitter=0.6,
799 samples=300,
800 ]{example.dat}
801 \draw[-{Stealth}] (axis cs: 1.75,0.45) %
802 .. controls (axis cs:1.75,0.85) and %
803 (axis cs:3.9,0.5) .. (axis cs: 3.9,1.05);
804 \draw[decoration={raise=2pt,text along path, text=%
805 {|\small| Better bandwidth}, text align={center}}, %
806 decorate] %
807 (axis cs: 1.75,0.45) %
808 .. controls (axis cs:1.75,0.85) and %
809 (axis cs:3.9,0.5) .. (axis cs: 3.9,1.05);
810 \draw[-{Stealth}] %
811 (axis cs: 1.5,0.45) .. %
812 controls (axis cs:1.5,0.85) %
813 and (axis cs:1.25,1.1) .. %
814 (axis cs: 1.25,1.5) .. %
815 controls (axis cs:1.25,1.9) %
816 and (axis cs:1.35,1.9) %
817 .. (axis cs:1.35,2.6);
818 \draw[decoration={raise=2pt,text along path, text=%
819 {|\small|Oversmoothed}, text align={center}}, %
820 decorate] %
821 (axis cs: 1.35,2.6) .. %
822 controls (axis cs:1.35,1.9) %
823 and (axis cs:1.25,1.9) .. %
824 (axis cs: 1.25,1.5) .. %
825 controls (axis cs:1.25,1.1) %
826 and (axis cs:1.5,0.85) %
827 .. (axis cs:1.5,0.45);
828 \end{axis}
829 \end{tikzpicture}
830 \end{minted}
831
832 \subsection{Standalone kernel density estimation}
833
834 Plotting only one dataset and choosing adequate plot limits, one
835 may obtain a simple representation of a kernel density estimation.
836 This can be seen in figure \ref{graph:kde_standalone}, obtained from the
837 code excerpt below.
838
839 \begin{figure}[h]
840 \centering
841 \begin{tikzpicture}
842 \violinplotsset[
843 no mirror,
844 reverse axis,
845 data points,
846 ]{%
847 xmin=3.3,xmax=4,
848 ymin=-1,ymax=12,
849 title={Plotting Some Data},
850 ylabel={$p(x)$},
851 xlabel={$x$},
852 xmajorgrids=true,
853 % ymajorticks=true,
854 ytick={0.0,2.5,5,7.5,10},
855 yticklabels={0.0,2.5,5,7.5,10},
856 }
857 \begin{axis}
858 \addviolinplot[%
859 index=C,
860 relative position=0,
861 color=red!30!black,
862 % label={},
863 col sep=tab,
864 dataset size=5pt,
865 dataset color=red!10!black,
866 dataset mark=*,
867 dataset fill=red!90!black,
868 dataset fill opacity=0.2,
869 ]{example.dat}
870 \end{axis}
871 \end{tikzpicture}
872 \caption{Standalone kernel density estimation example}
873 \label{graph:kde_standalone}
874 \end{figure}
875
876 \colorlet{mintedbgstand}{red!10!white}
877
878 \begin{minted}[%
879 escapeinside=||,
880 frame=single,
881 rulecolor=mintedbgstand,
882 framesep=10pt,
883 tabsize=4,
884 bgcolor=mintedbgstand]{latex}
885 \begin{tikzpicture}
886 \violinplotsset[
887 no mirror,
888 reverse axis,
889 data points,
890 ]{%
891 xmin=3.3,xmax=4,
892 ymin=-1,ymax=12,
893 title={Plotting Some Data},
894 ylabel={$p(x)$},
895 xlabel={$x$},
896 xmajorgrids=true,
897 % ymajorticks=true,
898 ytick={0.0,2.5,5,7.5,10},
899 yticklabels={0.0,2.5,5,7.5,10},
900 }
901 \begin{axis}
902 \addviolinplot[%
903 index=C,
904 relative position=0,
905 color=red!30!black,
906 % label={},
907 col sep=tab,
908 dataset size=5pt,
909 dataset color=red!10!black,
910 dataset mark=*,
911 dataset fill=red!90!black,
912 dataset fill opacity=0.2,
913 ]{example.dat}
914 \end{axis}
915 \end{tikzpicture}
916 \end{minted}
917
918 \subsection{Asymmetrical violin plots --- real world data}
919
920 Using the key \texttt{invert=true} in the options of
921 \texttt{\textbackslash violinplot} one can plot two different sets of data side
922 by side, in an asymmetrical violin plot. This can be seen in figure
923 \ref{graph:asymmetrical}, which exhibits the male and female life expectancy at
924 birth, in 2019, for several countries, segregated by WHO region.\footnote{
925 Available at %
926 \url{https://www.who.int/data/gho/publications/world-health-statistics}.
927 }.
928
929 \colorlet{malecolor}{cyan!60!white}
930 \colorlet{femalecolor}{cyan!60!black}
931
932 \begin{figure}[h]
933 \centering
934 \begin{tikzpicture}
935 \violinplotsset[
936 no mirror,
937 scaled,
938 ]{}
939 \begin{axis}[
940 xmin=0.8,xmax=13.2,
941 ymin=30,ymax=100,
942 title={Life Expectancy Per WHO Region},
943 xlabel={WHO Region},
944 ylabel={Life Expectancy in Years},
945 ymajorgrids=true,
946 xtick={2,4,6,8,10,12},
947 xticklabels={{Africa},
948 {Middle East},
949 {Pacific},
950 {SE. Asia},
951 {Americas},
952 {Europe}},
953 ]
954 \addviolinplot[%
955 index=LifeExpectancyAtBirthFemale,
956 relative position=2,
957 color=femalecolor,
958 col sep=comma,
959 ]{AFR.csv}
960 \addviolinplot[relative position=4]{EMR.csv}
961 \addviolinplot[relative position=6]{WPR.csv}
962 \addviolinplot[relative position=8]{SEAR.csv}
963 \addviolinplot[relative position=10]{AMR.csv}
964 \addviolinplot[relative position=12]{EUR.csv}
965 \addviolinplot[%
966 index=LifeExpectancyAtBirthMale,
967 relative position=2,
968 color=malecolor,
969 invert=true,
970 ]{AFR.csv}
971 \addviolinplot[relative position=4]{EMR.csv}
972 \addviolinplot[relative position=6]{WPR.csv}
973 \addviolinplot[relative position=8]{SEAR.csv}
974 \addviolinplot[relative position=10]{AMR.csv}
975 \addviolinplot[relative position=12]{EUR.csv}
976 \draw(axis cs:2,35) node[anchor=east] {\male};
977 \draw(axis cs:2,35) node[anchor=west] {\female};
978 \draw(axis cs:4,35) node[anchor=east] {\male};
979 \draw(axis cs:4,35) node[anchor=west] {\female};
980 \draw(axis cs:6,35) node[anchor=east] {\male};
981 \draw(axis cs:6,35) node[anchor=west] {\female};
982 \draw(axis cs:8,35) node[anchor=east] {\male};
983 \draw(axis cs:8,35) node[anchor=west] {\female};
984 \draw(axis cs:10,35) node[anchor=east] {\male};
985 \draw(axis cs:10,35) node[anchor=west] {\female};
986 \draw(axis cs:12,35) node[anchor=east] {\male};
987 \draw(axis cs:12,35) node[anchor=west] {\female};
988 \end{axis}
989 \end{tikzpicture}
990 \caption{Example of asymmetrical plot}
991 \label{graph:asymmetrical}
992 \end{figure}
993
994 The code for figure \ref{graph:asymmetrical} is available below:
995
996 \begin{minted}[%
997 escapeinside=||,
998 frame=single,
999 rulecolor=cyan!10!white,
1000 framesep=10pt,
1001 tabsize=4,
1002 bgcolor=cyan!10!white]{latex}
1003 \begin{tikzpicture}
1004 \violinplotsset[
1005 no mirror,
1006 scaled,
1007 ]{}
1008 \begin{axis}[
1009 xmin=0.8,xmax=13.2,
1010 ymin=30,ymax=100,
1011 title={Life Expectancy Per WHO Region},
1012 xlabel={WHO Region},
1013 ylabel={Life Expectancy in Years},
1014 ymajorgrids=true,
1015 xtick={2,4,6,8,10,12},
1016 xticklabels={{Africa},
1017 {Middle East},
1018 {Pacific},
1019 {SE. Asia},
1020 {Americas},
1021 {Europe}},
1022 ]
1023 \addviolinplot[%
1024 index=LifeExpectancyAtBirthFemale,
1025 relative position=2,
1026 color=femalecolor,
1027 col sep=comma,
1028 ]{AFR.csv}
1029 \addviolinplot[relative position=4]{EMR.csv}
1030 \addviolinplot[relative position=6]{WPR.csv}
1031 \addviolinplot[relative position=8]{SEAR.csv}
1032 \addviolinplot[relative position=10]{AMR.csv}
1033 \addviolinplot[relative position=12]{EUR.csv}
1034 \addviolinplot[%
1035 index=LifeExpectancyAtBirthMale,
1036 relative position=2,
1037 color=malecolor,
1038 invert=true,
1039 ]{AFR.csv}
1040 \addviolinplot[relative position=4]{EMR.csv}
1041 \addviolinplot[relative position=6]{WPR.csv}
1042 \addviolinplot[relative position=8]{SEAR.csv}
1043 \addviolinplot[relative position=10]{AMR.csv}
1044 \addviolinplot[relative position=12]{EUR.csv}
1045 \draw(axis cs:2,35) node[anchor=east] {\male};
1046 \draw(axis cs:2,35) node[anchor=west] {\female};
1047 \draw(axis cs:4,35) node[anchor=east] {\male};
1048 \draw(axis cs:4,35) node[anchor=west] {\female};
1049 \draw(axis cs:6,35) node[anchor=east] {\male};
1050 \draw(axis cs:6,35) node[anchor=west] {\female};
1051 \draw(axis cs:8,35) node[anchor=east] {\male};
1052 \draw(axis cs:8,35) node[anchor=west] {\female};
1053 \draw(axis cs:10,35) node[anchor=east] {\male};
1054 \draw(axis cs:10,35) node[anchor=west] {\female};
1055 \draw(axis cs:12,35) node[anchor=east] {\male};
1056 \draw(axis cs:12,35) node[anchor=west] {\female};
1057 \end{axis}
1058 \end{tikzpicture}
1059 \end{minted}
1060
1061 \section{Limitations}
1062
1063 As the math is handled through \TeX, generating the kernel distribution
1064 estimations is a slow process; therefore, if possible, the number of samples
1065 should not be very large. Also, each value should not, itself, be too large,
1066 to avoid ``dimension too large'' errors. In this case, the data should be scaled
1067 and the tick labels manually corrected.
1068
1069 \subsection{\texttt{{\textbackslash}violinplot} and
1070 \texttt{{\textbackslash}violinplotwholefile} limitations}
1071
1072 As each violin plot is rendered in a different \texttt{axis} environment,
1073 the positions of the axes' labels are not, usually, correct. One should
1074 set it manually. In the examples, this was accomplished setting the
1075 vertical/horizontal shift to twice the height of a letter, in the direction
1076 opposite to the appropriate axis. This approach also leads to another problem:
1077 using the keys ``height'' or ``width'' won't rescale the plot; one might use,
1078 before and after the code for the figure, \texttt{\textbackslash pgfplotsset},
1079 as shown below:
1080
1081 \colorlet{mintedbgtempplotsset}{red!50!blue}
1082 \colorlet{mintedbgplotsset}{mintedbgtempplotsset!10!white}
1083
1084 \begin{minted}[%
1085 escapeinside=||,
1086 frame=single,
1087 rulecolor=mintedbgplotsset,
1088 framesep=10pt,
1089 tabsize=4,
1090 bgcolor=mintedbgplotsset]{latex}
1091 \pgfplotsset{height=1.75\linewidth}
1092 \begin{tikzpicture}
1093 \violinplotsset[
1094 |\textit{options for \texttt{tikzviolinplots}}|
1095 ]{
1096 |\textit{\texttt{pgfplots} options}|
1097 }
1098 \violinplot[%
1099 |\textit{options for data points}|
1100 ]{|\textit{filename}|}
1101 |...|
1102 \end{tikzpicture}
1103 \pgfplotsset{height=0.9\linewidth}
1104 \end{minted}
1105
1106 For the same reason, the options \texttt{xmin}, \texttt{ymin}, \texttt{xmax}
1107 and \texttt{ymax} are required; no automatic placement is performed.
1108
1109 \section{Acknowledgements}
1110
1111 The author thanks Falko Galperin for the implementation of the jitter option.
1112 The author thanks Simon Brandt for the inclusion of the \texttt{addviolinplot}
1113 macro (which is the recommended interface) and for several improvements to the
1114 codebase.
1115
1116 \end{document}