Skip to main content
v2026.11,986 entries · CC-BY 4.0

Box Plots in MATLAB: boxchart and boxplot Syntax

How to make box plots in MATLAB with boxchart and boxplot, group data, add notches, read outliers, and compare defaults with Octave.

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.

Ask your first question freeSubscribe

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 boxplot in 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, and b = boxchart(___) returns BoxChart objects 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: boxchart discards 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 that boxchart uses a categorical ruler.
  • Outliers hidden behind each other: set 'JitterOutliers','on' in boxchart, or change Symbol and OutlierSize in boxplot.
  • 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 Whisker can 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 ColorGroupLayout will 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

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.

Box plot defaults: MATLAB boxchart, MATLAB boxplot and Octave boxplot
PropertyMATLAB boxchartMATLAB boxplotOctave boxplot
ProductMATLAB (core)Statistics and Machine Learning ToolboxOctave statistics package
IntroducedR2020aNot stated on pageNot stated on page
Table inputboxchart(tbl,yvar), R2025aNot stated on pageNot stated on page
Whisker / outlier ruleOutliers more than 1.5 x IQR from boxWhisker = 1.5 (default)Whisker = 1.5 (default)
Notch defaultoffoff (options: on, marker)Not stated on page
Default outlier markero+r (traditional), o (compact)+ (1.5 to 3 IQR), o (beyond 3 IQR)
Orientation defaultverticalNot stated on pageOrientation option available

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about Box Plots in MATLAB: boxchart and boxplot Syntax

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →