Gramm is a complete data visualization toolbox for Matlab. It provides an easy to use and high-level interface to produce publication-quality plots of complex data with varied statistical visualizations. Gramm is inspired by R's ggplot2 library.
Gramm is a powerful plotting toolbox which allows to quickly create complex, publication-quality figures in Matlab, and is inspired by R's ggplot2 library by Hadley Wickham. As a reference to this inspiration, gramm stands for GRAMmar of graphics for Matlab.
Gramm is a data visualization toolbox for Matlab that allows to produce publication-quality plots from grouped data easily and flexibly. 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 figure 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.
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 figures using high-level object-oriented code. Gramm has been used in several publications in the field of neuroscience, from human psychophysics (Morel et al. 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 has been published in the Journal of Open Source Software. If you use gramm plots in a publication you can thus cite it using the following:
Morel, (2018). Gramm: grammar of graphics plotting in Matlab. Journal of Open Source Software, 3(23), 568, https://doi.org/10.21105/joss.00568
Tested under Matlab 2014b+ versions. With pre-2014b versions, gramm forces
'painters', renderer to avoid some graphic bugs, which deactivates transparencies (use non-transparent geoms, for example
statsummary('geom','lines')). The statistics toolbox is required for some methods:
statdensity(). The curve fitting toolbox is required for
examples.m, exported for preview in html/examples.html
doc grammto find links to the documentation of each method.
The typical workflow to generate a figure with gramm is the following:
For example, with gramm, 7 lines of code are enough to create the figure below from the
carbig dataset. Here the figure represents the evolution of fuel economy of new cars in time, with number of cylinders indicated by color, and regions of origin separated across subplot columns:
load carbig.mat %Load example dataset about cars origin_region=num2cell(org,2); %Convert origin data to a cellstr
% Create a gramm object, provide x (year of production) and y (fuel economy) data, % color grouping data (number of cylinders) and select a subset of the data g=gramm('x',Model_Year,'y',MPG,'color',Cylinders,'subset',Cylinders
=3 & Cylinders=5) % Subdivide the data in subplots horizontally by region of origin g.facet_grid(,origin_region) % Plot raw data as points g.geom_point() % Plot linear fits of the data with associated confidence intervals g.stat_glm() % Set appropriate names for legends g.set_names('column','Origin','x','Year of production','y','Fuel economy (MPG)','color','# Cylinders') %Set figure title g.set_title('Fuel economy of new cars between 1970 and 1982') % Do the actual drawing g.draw()
To export figures in a vector-based format, use the SVG or PDF option rather than EPS. SVG can be read by all vector editing softwares and causes less problems than EPS both for export and import (transparency support, text without cuts, etc.). gramm has a convenient
export() method that can be called after
draw() and maintains correct dimensions/aspect ratio. The
'alpha' option for
geompoint() is not supported by Matlab for exports.
Accepts grouping data as arrays or cellstr.
Multiple ways of separating groups of data:
facetwrap()). Multiple options for consistent axis limits across facets, rows, columns, etc. (using
Multiple ways of directly plotting the data:
geompoint()) and jittered scatter plot (
Multiple ways of plotting statistics on the data:
stat_qq()) of x data distribution against theoretical distribution or y data distribution.
stat_glm(), requires statistics toolbox)
When Z data is provided in the call to
geomline() generate 3D plots
Subplots are created without too much empty space in between (and resize properly !)
Polar coordinates (
Color data can also be displayed as a continous variable, not as a grouping factor (
X and Y axes can be flipped to get horizontal statistics visualizations (
Color generation can be customized in the LCH color space, or can use alternative colormaps (Matlab's default, colorbrewer2), or provide a custom colormap (
Marker shapes and sizes can be customized with
Line styles and width can be customized with
Text elements aspect can be customized with
stat functions (alpha level, N bootstraps) can be modified with
The ordering of grouping variables can be changed between native, sorted, or custom (
Confidence intervals as shaded areas, error bars or thin lines
Set the width and dodging of graphical elements in
The member structure
results contains the results of computations from
stat_ plots as well as graphic handles for all plotted elements
Figure title (
Multiple gramm plots can be combined in the same figure by creating a matrix of gramm objects and calling the
draw() method on the whole matrix. An overarching title can be added by calling
set_title() on the whole matrix.
Different groupings can be used for different
geom layers with the
Matlabs axes properties are acessible through the method
Custom legend labels with
Plot reference line on the plots with
Plot reference polygons on the plots with
Date ticks with
Gramm works best with table-like data: separate variables / structure fields / table columns for the variables of interest, with each variable having as many elements as observations.
The code for the following figures and many others is in
All the mappings presented below can be combined.
Note that we by using Origin as a faceting variable, we visualize exactly the same quantities as in the figure above.
Here the variable given as Y is a Nx1 cell of 1D arrays containing the individual trajectories. Color is given as a Nx1 cellstr.
This example highlights the potential use of gramm for neuroscientific data. Here X is a Nx1 cell containing spike trains collected over N trials. Color is given as a Nx1 cellstr.
stat_bin() it is possible to construct peristimulus time histograms.
By making calling the update() method after a first draw, the same axes can be reused for another gramm plot. Here this allows to plot the whole dataset in the background of each facet.