Written and maintained by CASRAI Editorial Board
Published
On this page
To make a box plot in MATLAB, call boxchart(ydata), which draws one box per column of a matrix (or one box for a vector) in core MATLAB, introduced in R2020a. The older boxplot(x) function does the same job but belongs to the Statistics and Machine Learning Toolbox. Both draw the median, the 25th and 75th percentiles, whiskers and outliers; they differ in defaults, grouping syntax and how much formatting they expose. This guide covers both, with a third column for the GNU Octave boxplot, and shows how to read what the plot reports.
Ask CASRAI · free to tryQuestion about this guide? Ask CASRAI answers with linked sources. 2 free questions a day, no account.
What box plots are used for in research
A box plot summarises a distribution by its quartiles instead of its mean and standard deviation, so it is the standard first look at group differences, skew and outliers before choosing a test. MathWorks describes box plots as a way to compare the central tendency of groups, and notes that comparing box plot medians is like a visual hypothesis test, analogous to the t test used for means. A median line sitting off-centre inside the box suggests a skewed distribution (see box plot skewness for how to read that). If you need the arithmetic behind the box, the boxplot IQR guide shows how the quartiles and the interquartile range are found.
Install or access
The two functions sit in different products, which decides which one you can call on a given machine:
- boxchart is part of MATLAB itself. It was introduced in R2020a, so releases earlier than that do not have it. Table input (
boxchart(tbl,yvar)) and the whisker and colour-group customisation arguments arrived in R2025a. - boxplot is documented under the Statistics and Machine Learning Toolbox, so it needs that toolbox in your MATLAB installation.
- Octave has its own
boxplotin its statistics package, documented at gnu-octave.github.io/statistics.
Obtain MATLAB and its toolboxes only through MathWorks or your institution’s campus licence; this page does not cover licensing or cost. In MATLAB, ver lists the installed products, which tells you whether the Statistics and Machine Learning Toolbox is present.
Step-by-step: make a box plot with boxchart
1. One box from a vector
The MathWorks example loads the built-in patients data set and plots one box for the Age variable:
load patients
boxchart(Age)
ylabel('Age (years)')
With a vector, boxchart(ydata) draws a single box. With a matrix, it draws one box per column, so a samples-by-groups matrix gives you side-by-side boxes with no further work.
2. Grouped boxes with a grouping variable
Use boxchart(xgroupdata,ydata) when your data are in one long vector and a second vector says which group each value belongs to. The documented example groups patient weight by hospital location and turns the notches on:
load patients
boxchart(categorical(Location),Weight,'Notch','on')
ylabel('Weight (lbs)')
The group variable becomes the x-axis, and because boxchart uses categorical rulers the category names label the axis directly. To split each position by a second variable, add 'GroupByColor',cgroupdata; the returned handle then contains one BoxChart object for each unique value in cgroupdata. From R2025a, 'ColorGroupLayout' accepts "grouped" (the default) or "overlaid".
3. Table input (R2025a and later)
If your data are in a table, pass the table and the variable names: boxchart(tbl,yvar) or boxchart(tbl,xvar,yvar). This form is only available from R2025a; on earlier releases extract the columns and use the vector syntax above.
4. Options you will use most
'Notch','on'draws notches around each median (default'off').'Orientation','horizontal'turns the plot sideways (default'vertical').'MarkerStyle'sets the outlier marker (default'o');'none'hides it.'JitterOutliers','on'spreads outlier markers so overlapping points are visible (default'off').'BoxFaceColor'sets the fill using an RGB triplet, hex code or colour name.boxchart(ax,___)draws into a specific axes, andb = boxchart(___)returnsBoxChartobjects whose properties you can change with dot notation after the plot exists.
Axis labels, titles and legends are ordinary MATLAB graphics calls; see the MATLAB plot label guide for xlabel, ylabel and title.
Step-by-step: make a box plot with boxplot
The Statistics and Machine Learning Toolbox function takes a vector (one box), a matrix (one box per column) or a data vector plus a grouping variable: boxplot(x) and boxplot(x,g). The documented example simulates two normal samples and compares them with notches, custom labels and a shorter whisker:
rng default
x1 = normrnd(5,1,100,1);
x2 = normrnd(6,1,100,1);
boxplot([x1,x2],'Notch','on','Labels',{'mu = 5','mu = 6'},'Whisker',1)
Name-Value arguments worth knowing:
'Whisker'defaults to 1.5. A point is an outlier if it is greater than q3 + w(q3 – q1) or less than q1 – w(q3 – q1), where w is the whisker value; setting w to 0 makes every point outside q1 and q3 an outlier.'Notch'accepts'off'(default),'on'or'marker'.'Labels'names the boxes.'PlotStyle'is'traditional'(default) or'compact'.'Symbol'sets the outlier marker:'+r'by default in the traditional style,'o'in the compact style, and an empty string hides outliers. Default'OutlierSize'is 6 for traditional and 4 for compact.boxplot(ax,___)targets a specific axes.
MathWorks suggests boxchart as an alternative to boxplot for new work because it supports categorical rulers, legends and hold on, and its notches are easier to see, while also noting that boxchart does not have all the functionality of boxplot. If you rely on a feature that only boxplot has, keep using it.
Octave: boxplot in the statistics package
GNU Octave users call boxplot from the statistics package. Its documented forms include s = boxplot(data), boxplot(data,group) and a positional form boxplot(data,notched,symbol,orientation,whisker,...), where data is a matrix or a cell vector. The whisker default is 1.5, and the default outlier symbol is '+' for points between 1.5 and 3 IQR from the box and 'o' beyond 3 IQR. The optional output s is a seven-row matrix holding the minimum, Q1, median, Q3, maximum and the lower and upper confidence limits of the median, and the documentation states that its quartiles match prctile(data,[25 75]). That matrix is a convenient way to report the plotted statistics in a methods section.
Output and how to read it
The same elements appear in every function above, using the definitions on the MathWorks pages:
- Box: spans the 0.25 and 0.75 quantiles, so its height is the interquartile range (IQR).
- Median: the line inside the box.
- Whiskers: extend to the most extreme values that are not outliers (the adjacent values).
- Outliers: values more than 1.5 × IQR above the top or below the bottom of the box, drawn as individual markers.
- Notch: an interval around the median, computed as median ± 1.57 × IQR / √n, where n is the number of non-NaN points. If the notches of two boxes do not overlap, the medians differ at the 5% significance level, assuming normality.
For boxplot, MathWorks adds that the default whisker setting corresponds to roughly ±2.7 standard deviations and about 99.3% coverage for normally distributed data, so a few outlier markers in a large sample are expected and are not by themselves evidence of bad data. The Statistics and Machine Learning Toolbox documentation also says notch-based comparison is reasonably robust for non-normal data even though the notch width formula assumes normality. If you want to decide what to do with flagged points, read how to find an outlier in statistics before removing anything.
The data table below compares the defaults of the three functions side by side, which is the quickest way to see why the same data can produce slightly different-looking plots.
Troubleshooting
- Undefined function boxchart: your release is older than R2020a. Use
boxplot(if the Statistics and Machine Learning Toolbox is installed) or upgrade. - Undefined function boxplot: the Statistics and Machine Learning Toolbox is not installed or licensed. Use
boxchart, which is in core MATLAB. - Table syntax errors:
boxchart(tbl,yvar)needs R2025a or later; on older releases pass the columns directly. - Missing values:
boxchartdiscards NaN entries before computing the statistics. A data tip may still count them, but they do not affect the quartiles or the notch, where n excludes NaN values. - Groups appear in the wrong order or as numbers: convert the grouping vector with
categorical(), as in the documented Location example, so thatboxchartuses a categorical ruler. - Outliers hidden behind each other: set
'JitterOutliers','on'inboxchart, or changeSymbolandOutlierSizeinboxplot. - Different quartiles in different software: packages use different quantile definitions. Check the documentation of each tool before comparing numeric quartiles; for the same data, our R box plot guide and Matplotlib box plot guide show the equivalent calls and their defaults.
Free alternatives
If you do not have a MATLAB licence, the options below draw the same plot. Each row is limited to what the cited documentation states.
| Tool | Function | Whisker default (documented) | Where to read more |
|---|---|---|---|
| GNU Octave (statistics package) | boxplot(data) |
1.5 | Octave statistics package documentation |
| R | boxplot() |
Covered in the linked guide | Box plots in R |
| Python (Matplotlib) | ax.boxplot |
Covered in the linked guide | Box plot in Matplotlib |
For a broader list of no-cost tools, see free statistical software for research. If you are new to the environment itself, what MATLAB is used for gives the research context.
Common mistakes to check
- Reporting a box plot without stating the whisker rule. The 1.5 default is a convention, and
Whiskercan change it, so state any non-default value. - Reading notch overlap as a formal test. The MathWorks documentation frames notches as a visual comparison that assumes normality for the notch width.
- Mixing releases. Code using table input or
ColorGroupLayoutwill fail for collaborators on releases before R2025a. - Showing only boxes for small groups. A box summarises quartiles, so with very few points consider overlaying the raw data or error bars; see MATLAB errorbar for the latter.
FAQ
What is the difference between boxchart and boxplot in MATLAB?
boxchart is in core MATLAB (R2020a and later) and returns BoxChart objects; boxplot is in the Statistics and Machine Learning Toolbox and exposes options such as PlotStyle and Whisker. MathWorks recommends boxchart as the alternative but notes it lacks some boxplot functionality.
How do I make grouped box plots in MATLAB?
Pass a grouping vector as the first argument: boxchart(xgroupdata,ydata), or boxplot(x,g) with the toolbox. Add 'GroupByColor' in boxchart for a second grouping variable.
How do I add notches to a MATLAB box plot?
Use 'Notch','on' in either function. Non-overlapping notches indicate medians that differ at the 5% level, assuming normality.
How do I show or hide outliers?
In boxchart, set 'MarkerStyle','none'. In boxplot, set 'Symbol',''.
Does boxchart ignore NaN values?
Yes. MathWorks states that boxchart discards entries with NaN values before computing the statistics.
Can I make a horizontal box plot?
Yes. In boxchart, use 'Orientation','horizontal'; the default is 'vertical'.
Sources
- MathWorks, boxchart documentation (read 2026-11-12).
- MathWorks, boxplot documentation, Statistics and Machine Learning Toolbox (read 2026-11-12).
- MathWorks, Box plots (read 2026-11-12).
- GNU Octave statistics package, boxplot (read 2026-11-12).
Data: Box plot defaults: MATLAB boxchart, MATLAB boxplot and Octave boxplot
Side-by-side comparison of documented defaults and availability for the three box plot functions, compiled from each vendor or project documentation page.
| Property | MATLAB boxchart | MATLAB boxplot | Octave boxplot |
|---|---|---|---|
| Product | MATLAB (core) | Statistics and Machine Learning Toolbox | Octave statistics package |
| Introduced | R2020a | Not stated on page | Not stated on page |
| Table input | boxchart(tbl,yvar), R2025a | Not stated on page | Not stated on page |
| Whisker / outlier rule | Outliers more than 1.5 x IQR from box | Whisker = 1.5 (default) | Whisker = 1.5 (default) |
| Notch default | off | off (options: on, marker) | Not stated on page |
| Default outlier marker | o | +r (traditional), o (compact) | + (1.5 to 3 IQR), o (beyond 3 IQR) |
| Orientation default | vertical | Not stated on page | Orientation option available |
Sources
- MathWorks boxchart documentation (accessed 2026-11-12)
- MathWorks boxplot documentation (Statistics and Machine Learning Toolbox) (accessed 2026-11-12)
- GNU Octave statistics package: boxplot (accessed 2026-11-12)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







