Main Content

violinplot

Violin plot

Since R2024b

collapse all in page

    Syntax

    violinplot(ydata)
    violinplot(xgroupdata,ydata)
    violinplot(___,GroupByColor=cgroupdata)
    violinplot(EvaluationPoints=evalPts,DensityValues=densVals)
    violinplot(tbl,xvar,yvar)
    violinplot(___,Name=Value)
    violinplot(ax,___)
    v = violinplot(___)

    Description

    Vector and Matrix Data

    violinplot(ydata) creates a Violin Plot for each column of the matrix ydata. If ydata is a vector, then violinplot creates a single violin plot.

    example

    violinplot(xgroupdata,ydata) groups the data in ydata according to the unique values in xgroupdata and plots each group of data as a separate violin plot. xgroupdata determines the position of each violin plot along the x-axis.

    example

    violinplot(___,GroupByColor=cgroupdata) uses color to differentiate between violin plots. The function groups the data in ydata according to the unique value combinations in xgroupdata (if specified) and cgroupdata, and plots each group of data as a separate violin plot. The vector cgroupdata then determines the color of each violin plot. ydata must be a vector, and cgroupdata must have the same length as ydata. Specify the color grouping data name-value pair argument after any of the input argument combinations in the previous syntaxes.

    example

    violinplot(EvaluationPoints=evalPts,DensityValues=densVals) creates a violin plot using the values densVals and evaluation points evalPts for the probability density function (pdf).

    example

    Table Data

    violinplot(tbl,xvar,yvar) creates a violin plot of the data in yvar grouped by the data in xvar, where xvar and yvar are variables from the table tbl. To plot one data set, specify one variable for xvar and one variable for yvar. To plot multiple data sets, specify multiple variables for xvar, yvar, or both. If both arguments specify multiple variables, they must specify the same number of variables.

    example

    Additional Options

    violinplot(___,Name=Value) specifies additional options using one or more name-value arguments. For example, you can specify the orientation and which half of the violin to plot.

    example

    violinplot(ax,___) plots into the axes specified by ax instead of into the current axes (gca). The argument ax can precede any of the input argument combinations in the previous syntaxes.

    example

    v = violinplot(___) returns a ViolinPlot object or a vector of ViolinPlot objects. Use v to set properties of the violin plots after creating them. For a list of properties, see ViolinPlot Properties.

    example

    Examples

    collapse all

    Open Live Script

    Create a single violin plot from a vector of patient ages. Use the violin plot to analyze the distribution of ages.

    Load the patients data set. The Age vector contains the ages of 100 patients. Create a violin plot to visualize the distribution of ages.

    load patients
violinplot(Age)
ylabel("Age (years)")

    Figure contains an axes object. The axes object with ylabel Age (years) contains an object of type violinplot.

    The outline of the violin plot is determined by the kernel density estimate (kde) for the probability density function. The kde is bell-shaped with a peak near 40 on the vertical axis. The plot shows that the data in Age is approximately normally distributed and the median patient age is around 40.

    Open Live Script

    Generate a matrix of normally distributed random numbers. Create a violin plot for the data in each column of the matrix.

    ydata = randn(100,3);
violinplot(ydata)

    Figure contains an axes object. The axes object contains 3 objects of type violinplot.

    The three violin plots have group labels 1, 2, and 3. The shapes of the violin plots are slightly different due to randomness in the data. However, each violin plot has the bell shape characteristic of a normal distribution.

    Open Live Script

    Generate a vector of normally distributed random numbers and create a vector of grouping data.

    ydata = randn(100,1);
xgroupdata = categorical(repelem(["group1";"group2";"group3"],[20,50,30]));

    Create a set of violin plots for the data in ydata grouped by the unique values in xgroupdata. Each violin plot in the figure corresponds to a unique value in xgroupdata.

    violinplot(xgroupdata,ydata)

    Figure contains an axes object. The axes object contains an object of type violinplot.

    Open Live Script

    Generate two vectors of normally distributed data and three vectors of grouping data.

    ydata1 = randn(100,1);
ydata2 = randn(100,1)+5;

xgroupdata1 = categorical(repelem(["group1";"group2"],[90,10]));
xgroupdata2 = categorical(repelem(["group1";"group2"],[10,90]));
xgroupdata3 = categorical(repelem(["group3";"group4"],[25,75]));

    The variables ydata1 and ydata2 contain normally distributed data with means of 0 and 5, respectively. xgroupdata1 and xgroupdata2 contain different sequences of the same group labels. xgroupdata3 contains different group labels from those in xgroupdata1 and xgroupdata2.

    Create a table from the sample data and grouping data.

    tbl = table(xgroupdata1,xgroupdata2,xgroupdata3, ...
    ydata1,ydata2,VariableNames=["X1","X2","X3","Y1","Y2"]);

    Create a set of overlaid violin plots using the data in ydata1 grouped by xgroupdata1 and xgroupdata2.

    violinplot(tbl,["X1","X2"],"Y1")

    Figure contains an axes object. The axes object with ylabel Y1 contains 2 objects of type violinplot.

    The figure shows two sets of overlaid violin plots. The blue violin plots represent the data in ydata1 grouped by xgroupdata1, and the orange violin plots represent the same data grouped by xgroupdata2. The overlaid plots show that the different groupings do not significantly change the median values for each group. However, the different groupings have a visible effect on the shape of the violin plots corresponding to each group. This result suggests that the distribution of the data in each group is affected by how the data is grouped.

    Create another set of violin plots using the data in ydata1 grouped by xgroupdata1 and the data in ydata2 grouped by xgroupdata3.

    violinplot(tbl,["X1","X3"],["Y1","Y2"])

    Figure contains an axes object. The axes object contains 2 objects of type violinplot.

    The blue plots corresponding to groups 1 and 2 represent the data in ydata1, and the orange plots corresponding to groups 3 and 4 represent the data in ydata2. The plots show that the median values for the data in groups 3 and 4 are larger than those for groups 1 and 2.

    Open Live Script

    Generate a vector of normally distributed random numbers. Create two vectors for positional and color grouping data.

    ydata = randn(100,1);

xgroupdata = categorical(repelem(["group1";"group2";"group3"],[20;50;30]));
cgroupdata = categorical(repelem(["a";"b";"a";"b";"c";"d";"e"],[10;10;25;25;10;10;10]));

    The variable ydata contains normally distributed data with a mean of 0. xgroupdata contains labels for three different groups. The labels in cgroupdata split the first two groups in xgroupdata into the same two colors, and the third group in xgroupdata into three different colors.

    Plot the data in ydata using xgroupdata as the positional grouping data and cgroupdata as the color grouping data.

    violinplot(xgroupdata,ydata,GroupByColor=cgroupdata)

    Figure contains an axes object. The axes object contains 5 objects of type violinplot.

    The figure shows a set of violin plots for each of the three group labels in xgroupdata. The sets for groups 1 and 2 each contain an orange and a blue violin plot. The set of violin plots for group 3 contains a yellow, a purple, and a green violin plot.

    Open Live Script

    Generate a vector of random numbers. Estimate the pdf for the data by calculating its kernel density estimate (kde).

    ydata = [randn(100,1); 6+2*randn(100,1)];
[f,xf] = kde(ydata,Bandwidth=0.6);

    f contains values for the kde, and xf contains the corresponding evaluation points.

    Create a violin plot using f as the density values and xf as the evaluation points. The shape of the violin plot shows that the data has a bimodal nature.

    violinplot(EvaluationPoints=xf,DensityValues=f)

    Figure contains an axes object. The axes object contains an object of type violinplot.

    Open Live Script

    Create two vectors of randomly generated data. Create two vectors of positional grouping data.

    ydata1 = randn(100,1);
ydata2 = [randn(25,1)+2;randn(75,1)+5];

xgroupdata1 = repelem([1;2],[50;50]);
xgroupdata2 = repelem([1;2],[25;75]);;

    The variables ydata1 and ydata2 contain the randomly generated data. xgroupdata1 and xgroupdata2 contain different sequences of the same two group labels.

    Compare the data in ydata1 grouped by the labels in xgroupdata1 with the data in ydata2 grouped by the labels in xgroupdata2. For each group, create a horizontal violin plot with the data in ydata1 represented in the top half and the data in ydata2 represented in the bottom half.

    violinplot(xgroupdata1,ydata1,Orientation="horizontal",DensityDirection="positive")
hold on
violinplot(xgroupdata2,ydata2,Orientation="horizontal",DensityDirection="negative")
legend("ydata1","ydata2")

    Figure contains an axes object. The axes object contains 2 objects of type violinplot. These objects represent ydata1, ydata2.

    The violin plots show that, for each group, the data for ydata1 and ydata2 is approximately normally distributed and the data for ydata1 has a smaller mean than the data for ydata2. Moreover, the data for ydata2 has a larger mean in group 2 than it does in group 1.

    Open Live Script

    Create violin plots from patient data to compare the blood pressure of smokers and nonsmokers. The plots show that smokers have higher systolic and diastolic blood pressure than nonsmokers.

    Load the patients data set. Convert Smoker to a categorical variable with the descriptive category names Smoker and Nonsmoker rather than 1 and 0.

    load patients
Smoker = categorical(Smoker,logical([1 0]),["Smoker","Nonsmoker"]);

    Create a 1-by-2 tiled chart layout using the tiledlayout function. Create the first set of axes ax1 by calling the nexttile function. In the first set of axes, display two violin plots representing the systolic blood pressure values, one for smokers and the other for nonsmokers. Create the second set of axes ax2 within the tiled chart layout by calling the nexttile function. In the second set of axes, do the same for diastolic blood pressure.

    tiledlayout(1,2)

% Left axes
ax1 = nexttile;
violinplot(ax1,Systolic,GroupByColor=Smoker)
ylabel(ax1,'Systolic Blood Pressure')
legend("Smoker","Nonsmoker")

% Right axes
ax2 = nexttile;
violinplot(ax2,Diastolic,GroupByColor=Smoker)
ylabel(ax2,"Diastolic Blood Pressure")
legend("Smoker","Nonsmoker")

    Figure contains 2 axes objects. Axes object 1 with ylabel Systolic Blood Pressure contains 2 objects of type violinplot. These objects represent Smoker, Nonsmoker. Axes object 2 with ylabel Diastolic Blood Pressure contains 2 objects of type violinplot. These objects represent Smoker, Nonsmoker.

    Open Live Script

    Load the patients data set, and convert the Smoker variable to categorical.

    load patients
Smoker = categorical(Smoker,logical([1 0]),["Smoker","Nonsmoker"]);

    The variables Diastolic and Smoker contain data for patient diastolic blood pressure and smoker status.

    Create a set of violin plots for the data in Diastolic grouped by Smoker. 

    v = violinplot(Diastolic,GroupByColor=Smoker)
    v = 
  1x2 ViolinPlot array:

    ViolinPlot    ViolinPlot

    v is an array containing two ViolinPlot objects. You can modify the violin plots by specifying the properties of the ViolinPlot objects in v. For more information, see ViolinPlot Properties.

    Update the colors of the violin plots so that the plot for smokers is pink and the plot for nonsmokers is green.

    v(1).FaceColor = [1 0 1]; % Pink
v(2).FaceColor = [0 1 0]; % Green
legend("Smoker","Nonsmoker")

    Figure contains an axes object. The axes object contains 2 objects of type violinplot. These objects represent Smoker, Nonsmoker.

    Input Arguments

    collapse all

    Sample data, specified as a numeric vector or matrix.

    • If ydata is a matrix, then violinplot creates a violin plot for each column of ydata.

    • If ydata is a vector and you do not specify xgroupdata or cgroupdata, then violinplot creates a single violin plot.

    • If ydata is a vector and you specify xgroupdata or cgroupdata, then violinplot creates a violin plot for each unique value combination in xgroupdata and cgroupdata.

    Data Types: single | double

    Positional grouping data, specified as a numeric or categorical vector.

    If ydata is a vector, xgroupdata must be a vector of the same length. If ydata is a matrix, xgroupdata must be a matrix of the same size, or a vector of length equal to the number of rows or columns in ydata.

    violinplot groups the data in ydata according to the unique value combinations in xgroupdata and cgroupdata, and creates a violin plot for each group. By default, violinplot vertically orients the violin plots and displays the xgroupdata values along the x-axis. You can change the violin plot orientation by using the Orientation property.

    Data Types: single | double | categorical

    Color grouping data, specified as a numeric vector, categorical vector, logical vector, string array, character vector, or cell array of character vectors. cgroupdata must have the same length as the vector ydata; you cannot specify cgroupdata when ydata is a matrix.

    violinplot groups the data in ydata according to the unique value combinations in xgroupdata and cgroupdata. The function creates a violin plot for each group of data and assigns the same color to groups with the same cgroupdata value.

    Data Types: single | double | categorical | logical | string | char | cell

    Source table containing the data to plot, specified as a table or timetable.

    Table variables containing the positional grouping data, specified as one or more table variable indices.

    Specifying Table Indices

    Use any of the following indexing schemes to specify the intended variable or variables.

    Indexing SchemeExamples

    Variable names:

    • A string, character vector, or cell array.

    • A pattern object.

    • "A" or 'A' — A variable named A

    • ["A","B"] or {'A','B'} — Two variables named A and B

    • "Var"+digitsPattern(1) — Variables named "Var" followed by a single digit

    Variable index:

    • An index number that refers to the location of a variable in the table.

    • A vector of numbers.

    • A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 or false values.

    • 3 — The third variable from the table

    • [2 3] — The second and third variables from the table

    • [false false true] — The third variable

    Variable type:

    • A vartype subscript that selects variables of a specified type.

    • vartype("categorical") — All the variables containing categorical values

    Plotting Your Data

    The table variables you specify can contain numeric or categorical values.

    To plot one set of violin plots, specify one variable for xvar and one variable for yvar. For example, create a table with one categorical grouping variable and two variables containing normally distributed random values. Plot the data in Y1 grouped by the data in X.

    X = categorical(repelem(["a1";"b1"],50));
Y1 = randn(100,1);
Y2 = 5*randn(100,1)+10;
tbl = table(X,Y1,Y2);

violinplot(tbl,"X","Y1")

    To plot multiple data sets together, specify multiple variables for xvar, yvar, or both. If you specify multiple variables for both arguments, the number of variables for each argument must be the same.

    For example, create a set of violin plots from the data in Y1 using X as the grouping variable, and a set using Y2 as the data.

    violinplot(tbl,"X",["Y1","Y2"])

    You can also use different indexing schemes for xvar and yvar. For example, specify xvar as a variable name and yvar as an index number.

    violinplot(tbl,"X",3)

    Table variables containing the sample data, specified as one or more table variable indices.

    Specifying Table Indices

    Use any of the following indexing schemes to specify the intended variable or variables.

    Indexing SchemeExamples

    Variable names:

    • A string, character vector, or cell array.

    • A pattern object.

    • "A" or 'A' — A variable named A

    • ["A","B"] or {'A','B'} — Two variables named A and B

    • "Var"+digitsPattern(1) — Variables named "Var" followed by a single digit

    Variable index:

    • An index number that refers to the location of a variable in the table.

    • A vector of numbers.

    • A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 or false values.

    • 3 — The third variable from the table

    • [2 3] — The second and third variables from the table

    • [false false true] — The third variable

    Variable type:

    • A vartype subscript that selects variables of a specified type.

    • vartype("categorical") — All the variables containing categorical values

    Plotting Your Data

    The table variables you specify must contain numeric values.

    To plot one set of violin plots, specify one variable for xvar and one variable for yvar. For example, create a table with two categorical grouping variables and one variable containing normally distributed random values. Plot the data in Y grouped by the data in X1.

    X1 = categorical(repelem(["a1";"b1"],50));
X2 = categorical(repelem(["a2";"b2";"c2"],[33,33,34]));
Y = randn(100,1);
tbl = table(X1,X2,Y);

violinplot(tbl,"X1","Y")

    To plot multiple data sets together, specify multiple variables for xvar, yvar, or both. If you specify multiple variables for both arguments, the number of variables for each argument must be the same.

    For example, create a set of violin plots from the data in Y using X1 as the grouping variable, and a set using X2 as the grouping variable.

    violinplot(tbl,["X1","X2"],"Y")

    You can also use different indexing schemes for xvar and yvar. For example, specify xvar as a variable name and yvar as an index number.

    violinplot(tbl,"X1",3)

    Evaluation points for the probability density function (pdf), specified as one of these values:

    • numeric vector — Create a single violin plot using the evaluation points in evalPts and the pdf values in densVals.

    • numeric matrix — Create multiple violin plots. Each violin plot represents the evaluation points in a column of evalPts and the pdf values in the corresponding column of densVals.

    If you specify evalPts, you must also specify densVals, and they must be the same size.

    Data Types: single | double

    Values for the pdf, specified as one of these values:

    • numeric vector — Create a single violin plot using the evaluation points in evalPts and the pdf values in densVals.

    • numeric matrix — Create multiple violin plots. Each violin plot represents the evaluation points in a column of evalPts and the pdf values in the corresponding column of densVals.

    If you specify densVals, you must also specify evalPts, and they must be the same size.

    Data Types: single | double

    Target axes, specified as an Axes object. If you do not specify the axes, then violinplot uses the current axes (gca).

    Name-Value Arguments

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: violinplot(ydata,Orientation="horizontal",DensityDirection="negative") uses the data in ydata to plot the bottom half of a horizontal violin plot.

    Note

    The ViolinPlot properties listed here are only a subset. For a complete list, see ViolinPlot Properties.

    Maximum violin plot width, specified as a positive scalar. DensityWidth has the same units as the positional grouping data specified by xgroupdata or xvar.

    Example: DensityWidth=0.5

    Data Types: single | double

    Plot a full or half violin, specified as one of the values in this table.

    ValueDescription
    "both"Plot both halves of the violin.
    "positive"

    Plot the positive half of the violin, which depends on the Orientation name-value argument:

    • "vertical" — Plot only the right half of the violin.

    • "horizontal" — Plot only the top half of the violin.

    "negative"

    Plot the negative half of the violin, which depends on the Orientation name-value argument:

    • "vertical" — Plot only the left half of the violin.

    • "horizontal" — Plot only the bottom half of the violin.

    Example: DensityDirection="negative"

    Data Types: string | char

    Method for normalizing the violin plots, specified as one of the values in this table.

    ValueDescription
    "area"The violin plots have equal areas.
    "width"The violin plots have widths equal to DensityWidth.
    "count"The violin plots have widths proportional to the number of data points in each group.

    Example: DensityScale="count"

    Data Types: string | char

    Orientation of the violin plots, specified as "vertical" or "horizontal". By default, the violin plots are vertically oriented so that the violin plots align with the y-axis. Regardless of the orientation, violinplot stores the sample data in the YData property of the ViolinPlot object.

    Example: Orientation="horizontal"

    Data Types: string | char

    Output Arguments

    collapse all

    Violin plots, returned as a ViolinPlot object or a vector of ViolinPlot objects.

    • If you specify ydata as a matrix, violinplot returns one object per column.

    • If you specify tbl, violinplot returns one object per index in xvar or yvar, whichever has the most elements.

    • If you specify cgroupdata, violinplot returns one object per group.

    Use v to set properties of the violin plots after creating them. For a list of properties, see ViolinPlot Properties.

    More About

    collapse all

    Violin Plot

    A violin plot provides a visual representation of the empirical distribution for a data sample. The shape of a violin plot is determined by the kernel density estimate (kde) for the probability density function (pdf) reflected about the vertical axis.

    Version History

    Introduced in R2024b

    See Also

    Functions

    Properties