gramm data visualization toolbox
Editor's Note: This file was selected as MATLAB Central Pick of the Week
Gramm is a MATLAB toolbox that enables the rapid creation of complex, publication-quality figures. Its design philosophy focuses on a declarative approach, where users specify the desired end result, as opposed to the traditional imperative method involving for loops, if/else statements, etc.
The MATLAB implementation of gramm
is inspired by the "grammar of graphics" principles (Wilkinson 1999) and the ggplot2 library for R by Hadley Wickham. As a reference to this inspiration, gramm stands for GRAMmar of graphics for MATLAB. A similar library called Seaborn also exists for Python.
Gramm has been used in many publications from varied fields and is particularily suited for neuroscience, from human movement 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).
Typical use cases are described in these live scripts. We recommend opening the live scripts in MATLAB to benefit from interactive elements. A simplified workflow is presented below this table.
To run the files in Matlab online, you will need to add the gramm folder to your path (select the gramm folder in the files panel on the left, right click>Add to Path>Selected Folder(s)).
- Getting Started:
- Explore grouped data:
- Explore X/Y data:
- Explore Time Series data:
- Advanced examples:
The typical workflow to generate this figure with only 7 lines of code is detailed in the "Getting Started" live script.. The figure uses data from the carbig
dataset and represents the evolution of fuel economy of new cars with time, depending on the number of cylinders indicated by color, and regions of origin separated across subplot columns.
Here are the main steps to generate this figure:
- Provide gramm with the relevant data for the figure: X and Y variables, but also the variables that will determine color, subplot rows/columns, etc.
load example_data.mat %Load example dataset about cars
% Create a gramm object g, provide x (year of production) and y (fuel economy) data,
% color grouping data (number of cylinders) and select a subset of the data (even numbers of cylinders)
g=gramm('x',cars.Model_Year,'y',cars.MPG,'color',cars.Cylinders,...
'subset',~mod(cars.Cylinders,2);
% Subdivide the data in subplots horizontally by region of origin
g.facet_grid([],cars.Origin_Region);
- Add graphical layers to your figure: raw data layers (directly plot data as points, lines...) or statistical layers (fits, histograms, densities, summaries with confidence intervals...). One instruction is enough to add each layer, and all layers offer many customization options.
% Plot raw data as points with a small horizontal offset between groups
g.geom_point("dodge",0.5);
% Plot linear fits of the data
g.stat_glm();
- Optionally configure legends, title and adjust the look the figure (colors, axes, etc.)
% 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');
- Draw the figure, gramm 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.
g.draw();
We recommend installing gramm directly through MATLAB's Add-ons explorer. Search for "gramm" and click Add!
You can also install gramm manually by downloading the latest .mltbx file or by adding the gramm folder from the repository to your path.
Once the toolbox is installed, type doc
in the MATLAB command window and you will see gramm in the "Supplemental Software" section at the bottom of the left navigation bar. From there you will have access to several live script demos and a cheat sheet with all commands in a compact format.
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
Recent versions of gramm (3.0 and above) target MATLAB above R2018b. Older releases work in older MATLAB versions. The statistics toolbox is required for some methods: stat_glm()
, some stat_summary()
methods, stat_density()
. The curve fitting toolbox or the statistics toolbox is required for stat_fit()
.
-
Accepts X, Y, Z and grouping data in varied types and shapes (arrays, matrices, cells)
-
Multiple ways of separating groups of data:
- 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()
andfacet_wrap()
). Multiple options for consistent axis limits across facets, rows, columns, etc. (using'scale'
and'space'
) - Separate figures (
fig()
)
- Colors, lightness, point markers, line styles, and point/line size (
-
Multiple ways of directly plotting the data:
- scatter plots (
geom_point()
) and jittered scatter plot (geom_jitter()
) - lines (
geom_line()
) - pre-computed confidence intervals (
geom_interval()
) - bars plots (
geom_bar()
) - raster plots (
geom_raster()
) - labels (
geom_label()
) - point counts (
geom_count()
) - swarm / beeswarm plots (
geom_swarm()
) - text labels (
geom_label()
)
- scatter plots (
-
Multiple statistical visualizations on 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()
andstat_density()
) - 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. - Smoothed data (
stat_smooth()
) - 2D binning (
stat_bin2d()
) - GLM fits (
stat_glm()
, requires statistics toolbox) - Custom fits with user-provided anonymous function (
stat_fit()
) - Ellipses of confidence (
stat_ellipse()
)
- y data summarized by x values (uniques or binned) with confidence intervals (
-
Easy export in multiple formats with a convenient
export()
method that can be called afterdraw()
and maintains correct dimensions/aspect ratio. -
All visualizations have plenty of options accessible through arguments, from computational to esthetic ones.
-
Representation of groupings can be fully customized (colormaps, ordering)
-
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. -
MATLABs axes properties are modifiable through the method
axe_property()
-
Non-data graphical elements can be added such as reference lines or polygons (
geom_abline()
,geom_vline()
,geom_hline()
,geom_polygon()
) -
For advanced customization, handles of all graphic elements and computation results are easily available after the
draw()
through theresults
structure of the gramm object
All these examples are from the advanced examples live scripts
gramm was inspired and/or used code from:
- ggplot2
- Panda for color conversion
- subtightplot for subplot creation
- colorbrewer2
- viridis colormap
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.
MATLAB Release Compatibility
Platform Compatibility
Windows macOS LinuxCategories
- AI, Data Science, and Statistics > Statistics and Machine Learning Toolbox > ANOVA >
- Sciences > Neuroscience > Frequently-used Algorithms >
- AI, Data Science, and Statistics > Statistics and Machine Learning Toolbox > Descriptive Statistics and Visualization > Statistical Visualization > Box Plots >
Tags
Acknowledgements
Inspired: electroCUDA, MatPlotLib Perceptually Uniform Colormaps
Community Treasure Hunt
Find the treasures in MATLAB Central and discover how the community can help you!
Start Hunting!Discover Live Editor
Create scripts with code, output, and formatted text in a single executable document.
@gramm
@gramm/private
doc
Versions that use the GitHub default branch cannot be downloaded
Version | Published | Release Notes | |
---|---|---|---|
3.0.0 | See release notes for this release on GitHub: https://github.com/piermorel/gramm/releases/tag/v3.0.0 |
|
|
2.27.1 | See release notes for this release on GitHub: https://github.com/piermorel/gramm/releases/tag/v2.27.1 |
|
|
2.27 | See release notes for this release on GitHub: https://github.com/piermorel/gramm/releases/tag/v2.27 |
||
2.26 | Switching to new github integration |
|
|
2.25 | Added full tab auto-complete for arguments and options with functionSignatures.json |
|
|
2.24.2.0 | Updated description |
|
|
2.24.0.0 | - Added JOSS paper and DOI information
|
|
|
2.23.0.0 | Preparation for JOSS submission |
|
|
2.22.0.0 | Added set_layout_options() allowing to fully customize figure layout in gramm |
||
2.21.0.0 | Corrected bug in geom_bar() when used with the 'stacked' option |
|
|
2.20.0.0 | - Overhaul of legend and colormap support
|
||
2.19.0.0 | Added toggles for row/column labels, improved handling of empty subsets |
|
|
2.18.0.0 | - Added more customization options to geom_bar
|
|
|
2.17.0.0 | Gramm now merges color and marker/size/linestyle legend if they are the same |
|
|
2.16.0.0 | - Added continuous color support to 3D lines and points
|
|
|
2.15.0.0 | - Possibility to set ‘CLim’ in set_continuous_color() in order to force color limits.
|
|
|
2.14.0.0 | Added geom_polygon() method to add custom polygons on plots |
|
|
2.13.0.0 | - Improved graphic fixes for old matlab versions
|
|
|
2.12.0.0 | - Added export() method
|
|
|
2.11.0.0 | Added coord_flip(), which can be used to generate horizontal box plots, violin plots, error bars, etc. |
|
|
2.10.1.0 | - Added the possibility to provide a custom function to stat_summary()
|
|
|
2.10.0.0 | - stat_smooth() now provides more smoothing algorithms, better documentation and more conservative CI estimates
|
|
|
2.9.0.0 | - Added fig() function to separate data across figures
|
|
|
2.8.2.0 | Corrected bug in stat_summary() polar interpolation when x data didn't start at zero radians. Added safety checks. |
|
|
2.8.1.0 | - Corrected absence of y ticks if single facet when using facet_wrap()
|
|
|
2.8.0.0 | Added 'alpha' option to geom_point(), geom_jitter() and geom_line() |
|
|
2.7.0.0 | - Added geom_label() to plot text
|
|
|
2.6.0.0 | - Added set_stat_options() to specify alpha level and N bootstrap samples in all stat_ functions
|
|
|
2.5.0.0 | Added customization options for text, lines and points:
|
|
|
2.4.0.0 | - Added corner histogram of x-y difference stat_cornerhist()
|
||
2.3.1.0 | - Added notch option to stat_boxplot()
|
|
|
2.3.0.0 | - Added stat_violin() to create violin plots
|
|
|
2.2.3.0 | Added functionality to edit legend axes |
|
|
2.2.2.0 | - Corrected rare error on y limit computation
|
|
|
2.2.1.0 | Corrected error with geom_line() and 3D data |
|
|
2.2.0.0 | - Represent user-provided confidence intervals with geom_interval()
|
|
|
2.1.1.0 | - Corrected errorbar thickness
|
|
|
2.1.0.0 | - Added set_parent() method
|
|
|
2.0.1.0 | Updated description |
|
|
2.0.0.0 | - Full refactor from a single file to a @gramm class folder
|
|
|
1.16.1.0 | Corrected stat_summary() to prevent erroneous line/area interruptions |
|
|
1.16.0.0 | - Added 'space' option to facet_grid()
|
|
|
1.15.0.0 | - Improved legend layout
|
|
|
1.14.1.0 | - Changed Picture |
|
|
1.14.0.0 | - ‘z’ input data in gramm() creates 3D plots when using geom_point() or geom_line()
|
|
|
1.13.0.0 | Added possibility to set a global title with set_title() |
|
|
1.12.2.0 | Description correction |
|
|
1.12.1.0 | Added simpler way to set ordering with set_order_options() |
|
|
1.12.0.0 | - Added set_order_options()
|
|
|
1.11.0.0 | Added box and whiskers plots, Quantile-Quantile plots
|
|
|
1.10.0.0 | Added cheat sheet, added geom_funline(), added 'dodge' option to stat_summary() |
|
|
1.9.0.0 | - Results from stat_ plots are now returned in the results member structure.
|
|
|
1.8.0.0 | Changing manually the limits (using pan or zoom) of a facet in a gramm generated figure will now automatically change the scale of the other facets according to the ‘scale’ facet preferences |
|
|
1.7.0.0 | - Added stat_fit() for custom fits (requires curve fitting toolbox)
|
|
|
1.6.0.0 | Plenty of new features (separation by lightness, confidence ellipses, color options, geom_hline, geom_vline) |
|
|
1.5.1.0 | Bug corrrection |
|
|
1.5.0.0 | Enhancements and bug fixes for continuous colors, which can now be forced and customized using set_continuous_color() |
|
|
1.4.0.0 | Added ‘edges’ option for custom bins to stat_bin2d() and stat_bin()
|
|
|
1.3.0.0 | Greatly improved geom_raster() speed when used with option 'geom','line' |
|
|
1.2.0.0 | Additional usage examples |
|
|
1.1.0.0 | Corrected set_datetick() issue, corrected initialization of faceting variables |
|
|
1.0.0.0 |
|