Gramm: grammar of graphics plotting in Matlab
Pierre Morel
1
1 German Primate Center, Göttingen, Germany
DOI: 10.21105/joss.00568
Software
• Review
• Repository
• Archive
Submitted: 31 January 2018
Published: 06 March 2018
Licence
Authors of JOSS papers retain
copyright and release the work un-
der a Creative Commons Attri-
bution 4.0 International License
(CC-BY).
Summary
Gramm is a data visualization toolbox for Matlab (The MathWorks Inc., Natick, USA)
that allows to produce publication-quality plots from grouped data easily and exibly.
Matlab can be used for complex data analysis using a high-level interface: it supports
mixed-type tabular data via tables, provides statistical functions that accept these tables
as arguments, and allows users to adopt a split-apply-combine approach (Wickham 2011)
with rowfun(). However, the standard plotting functionality in Matlab is mostly low-
level, allowing to create axes in gure windows and draw geometric primitives (lines,
points, patches) or simple statistical visualizations (histograms, boxplots) from numerical
array data. Producing complex plots from grouped data thus requires iterating over the
various groups in order to make successive statistical computations and low-level draw
calls, all the while handling axis and color generation in order to visually separate data
by groups. The corresponding code is often long, not easily reusable, and makes exploring
alternative plot designs tedious (Example code Fig. 1A).
Inspired by ggplot2 (Wickham 2009), the R implementation of “grammar of graphics”
principles (Wilkinson 1999), gramm improves Matlab’s plotting functionality, allowing to
generate complex gures using high-level object-oriented code (Example code Figure 1B).
Gramm has been used in several publications in the eld of neuroscience, from human
psychophysics (Morel, Ulbrich, and Gail 2017), to electrophysiology (Morel et al. 2016;
Ferrea et al. 2017), human functional imaging (Wan et al. 2017) and animal training
(Berger et al. 2017).
Gramm use and features
The generation of a gure with gramm includes the following steps, which typically take
few lines of code (Example gramm code Fig. 1B). In a rst line, the user creates an
instance of a gramm object by providing the constructor with the variables necessary
for the plot: x and y values as well as grouping variables. Each grouping variable can
simply be associated with a given plot feature using named arguments: color hue and
lightness, sub-axis rows and columns, marker and line type and size. In the example
Fig 1B, the two grouping variables are associated with sub-axis columns and color hues.
After this initialization, the user can add graphical layers to the gure by making calls to
corresponding methods of the newly created object. geom_ methods are used to add indi-
vidual layers that represent the x/y data directly, such as points, lines, bars, rasters, etc.
stat_ methods are used to add statistical visualization layers, some of which reecting
built-in Matlab statistics functions, others extending Matlab’s capabilities: histograms,
linear or non-linear ts, density estimates, statistical summaries, spline smoothing, violin
plots, ellipse ts, etc. Most geom_ and stat_ methods can take optional arguments for
customization of the layer. At this stage, the user can also call optional set_ methods in
order to ne tune the gure design (colormaps, legends, ordering, titles, etc.). The actual
plotting is made when the user nally calls the draw() method.
Morel, (2018). Gramm: grammar of graphics plotting in Matlab. Journal of Open Source Software, 3(23), 568.
https://doi.org/10.21105/joss.00568
1