gramm (complete data visualization toolbox, ggplot2/R-like)

version 2.25 (2.29 MB) by Pierre Morel
Quickly create publication-quality plots: automatic colors & subplots, stats, violin/box plots, etc.


Updated 3 Nov 2021

From GitHub

View License on GitHub

Editor's Note: This file was selected as MATLAB Central Pick of the Week

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. As a reference to this inspiration, gramm stands for GRAMmar of graphics for Matlab.

For quick help use the cheat sheet:

Morel, (2018). Gramm: grammar of graphics plotting in Matlab. Journal of Open Source Software, 3(23), 568,

The typical workflow to generate a figure with gramm is the following (the example figures in the vignette are generated using 6 lines of code):

- In a first step, provide gramm with the relevant data for the figure: X and Y variables, but also grouping variables that will determine color, subplot rows/columns, etc.

- In the next steps, add graphical layers to your figure: raw data layers (directly plot data as points, lines...) or statistical layers (plot fits, histograms, densities, summaries with confidence intervals...). One instruction is enough to add each layer, and all layers offer many customization options.

- In the last step, gramm draws the figure, and takes care of all the annoying parts: no need to loop over colors or subplots, colors and legends are generated automatically, axes limits are taken care of, etc.

- Accepts X,Y and Z data as arrays, matrices or cells of arrays
- Accepts grouping data as arrays or cellstr. Gramm works best with table-like data: separate variables/fields/columns for the variables of interest, with each variable having as many elements as observations.

- Multiple ways of separating data by groups:
- Colors, lightness, point markers, line styles, and point/line size ('color', 'lightness', 'marker', 'linestyle', 'size')
- Subplots by row and/or columns, or wrapping columns (facet_grid() and facet_wrap()). Multiple options for consistent axis limits across facets, rows, columns, etc. (using 'scale' and 'space').

- Multiple ways of directly plotting the data:
- scatter plots (geom_point()) and jittered scatter plot (geom_jitter())
- lines (geom_line())
- confidence intervals (geom_interval())
- bars plots (geom_bar())
- raster plots (geom_raster())
- point counts (point_count())

- Multiple ways of plotting statistical visualizations of the data:
- y data summarized by x values (uniques or binned) with confidence intervals (stat_summary())
- histograms and density plots of x values (stat_bin() and stat_density())
- histograms of x-y differences (stat_cornerhist())
- box and whisker plots (stat_boxplot())
- violin plots (stat_violin())
- quantile-quantile plots (stat_qq()) of x data distribution against theoretical distribution or y data distribution.
- spline-smoothed y data with optional confidence interval (stat_smooth())
- 2D binning with contour or heatmap output (stat_bin2d())
- GLM fits (stat_glm(), requires statistics toolbox)
- Custom fits with user-provided anonymous function (stat_fit(), requires curve fitting toolbox)
- Ellipses of confidence (stat_ellipse())

- Subplots are created without too much empty space in between (and resize properly !)
- Polar coordinates (set_polar())
- 'z' input data in gramm() creates 3D plots when using geom_point() or geom_line()
- Color data can also be displayed as a continous variable, not as a grouping factor (set_continuous_color())
- X and Y axes can be flipped to get horizontal statistics visualizations (coord_flip())
- Color generation can be customized in the LCH color space, or can use alternative/custom colormaps (set_color_options())
- Marker shapes and sizes can be customized with set_point_options()
- Line styles and width can be customized with set_line_options()
- Text elements aspect can be customized with set_text_options()
- Confidence intervals as shaded areas, error bars or thin lines
- Set the width and dodging of graphical elements in geom_ functions, stat_bin(), stat_summary(), and stat_boxplot(), with 'width' and 'dodge' arguments
- The member structure results contains the results of computations from stat_ plots as well as graphic handles for all plotted elements
- Global title (set_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 stat_ and geom_ layers with the update() method
- Matlab axes properties are acessible through the method axe_property
- Custom legend labels with set_names
- Plot reference elements on the plots with geom_abline, geom_vline, geom_hline, and geom_polygon
- Date ticks with set_datetick
- Draw in a specific figure or uipanel/uitab with set_parent()

Cite As

Morel, Pierre. “Gramm: Grammar of Graphics Plotting in Matlab.” The Journal of Open Source Software, vol. 3, no. 23, The Open Journal, Mar. 2018, p. 568, doi:10.21105/joss.00568.

View more styles
MATLAB Release Compatibility
Created with R2012b
Compatible with any release
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!
To view or report issues in this GitHub add-on, visit the GitHub Repository.
To view or report issues in this GitHub add-on, visit the GitHub Repository.