# Gramm brings the grammar of graphics to MATLAB, one object and a draw call

> Gramm is a MATLAB toolbox for publication-quality figures that replaces loops over colours and subplots with a declarative object, a set of layers and a single draw call, following the grammar of graphics principles and the semantics of ggplot2. It ships as a MATLAB add-on, its live scripts double as its documentation, and its strongest showing is in the neuroscience literature.

**piermorel/gramm** — 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.

- Repository: https://github.com/piermorel/gramm
- Stars: 827 · Forks: 223
- Language: HTML
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/piermorel-gramm

## A declarative figure instead of a plotting script

Gramm is a MATLAB toolbox that enables the rapid creation of complex, publication-quality figures, and its design philosophy is stated as a contrast: users specify the desired end result, as opposed to the traditional imperative method involving for loops, if and else statements, and similar constructs.

That distinction is the whole project. The familiar way to build a grouped, facetted figure in MATLAB is a loop over the colour groups, a loop over the subplot positions, and a pile of bookkeeping to keep the legends and the axes straight. Gramm replaces that with an object you configure and then draw.

The lineage is stated plainly. The MATLAB implementation of gramm is inspired by the grammar of graphics principles from Wilkinson in 1999 and by the ggplot2 library for R by Hadley Wickham, and the name expands to GRAMmar of graphics for MATLAB. The README also notes that a similar library called Seaborn exists for Python, which is the shortest way to place it in the wider ecosystem.

The audience is researchers who publish figures and who want the same result without the same effort every time. The README says gramm has been used in many publications from varied fields, and that it is particularly suited for neuroscience, citing work from human movement psychophysics to electrophysiology, human functional imaging and animal training.

It is also a toolbox rather than a script collection, which is worth saying plainly: you are adding a dependency to your analysis environment, not dropping a function file next to your data.

## The gramm object takes the data, the layers take the meaning

The workflow in the README is described as seven lines of code for a figure that shows the evolution of fuel economy of new cars with time, coloured by number of cylinders, with regions of origin separated across subplot columns. The first step hands the data to a gramm object:

```matlab
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);
```

The constructor takes the x variable, the y variable, a grouping variable for colour, a subset expression, and facet_grid takes the variables that split the data into subplot rows and columns. A second facet_grid call with different variables would split by another dimension, which is how a figure gets a row per condition and a column per subject without a loop in sight.

The second step adds layers. Raw data layers plot the data directly as points or lines, and statistical layers add fits, histograms, densities and summaries with confidence intervals, with one instruction enough to add each layer and many customization options on each:

```matlab
 % 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(); 
```

Then names, title and the drawing call:

```matlab
% 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');
```

```matlab
g.draw();
```

The last line is where the bookkeeping lives. As the README puts it, 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.

## Facets, statistical layers and the layers you did not know you needed

Two capabilities in the workflow deserve more attention than the getting started example gives them.

The first is that a statistical layer is a first-class citizen. g.stat_glm() adds linear fits to the same figure that already contains the raw points, which means the plot shows the data and the model together without the two living in different scripts or different axes. The same mechanism covers histograms, densities and summaries with confidence intervals, and the README describes the layer set as raw data layers, directly plotting data as points and lines, or statistical layers, fits, histograms, densities and summaries with confidence intervals.

The second is the dodge offset. g.geom_point("dodge",0.5) plots points with a small horizontal offset between groups, which is the fix for the specific failure that makes grouped scatter plots unreadable when the values overlap.

Together these explain why the toolbox has a following in a particular field. A neuroscience figure with a condition per colour, a hemisphere per column and a fitted line per panel is exactly the shape of figure that is painful to write imperatively and easy to write declaratively, and the README's citation list, from human movement psychophysics through electrophysiology and functional imaging to animal training, is a list of exactly those figures.

The gallery and the demo scripts are also where the real feature list lives, since the README points at live scripts for grouped data, X and Y data, time series data, a table read from an open dataset hosted on S3, and advanced examples.

## Installing it: the add-on explorer, the .mltbx, or the folder

There are three documented ways to get Gramm into MATLAB, and the first is the one the project recommends.

Install it directly through MATLAB's Add-ons explorer: search for gramm and click Add. The toolbox is also on the MATLAB Central File Exchange, with the File Exchange entry linked from the README, which matters for teams whose organisation manages toolbox installs centrally rather than per developer.

The manual route is to download the latest .mltbx file, which is the MATLAB toolbox package format, or to add the gramm folder from the repository to the path. The repository makes that last route easy to spot: gramm.prj is a MATLAB project file, the source lives in the gramm directory, and the packaging scripts are buildfile.m and createMLTBX.m, with a buildutils directory alongside them. sample_data holds the datasets the examples load, and examples_dev.m is the developer entry point.

Running the demos without a local install is also supported. The README says that to run the files in Matlab online you need to add the gramm folder to your path, by selecting the gramm folder in the files panel on the left and choosing Add to Path, then Selected Folder(s). Every demo in the list is a live script with an Open in MATLAB Online link, which means a reader can click through the examples in a browser session before deciding to install anything locally.

The paper directory and the resources directory suggest that the project also maintains its own bibliography and supporting files, and the images directory holds the exported figures used in the README, which is a reminder that this is a project with a publication history rather than a weekend utility.

## Live scripts as the documentation, and the alternatives

The documentation strategy is unusual and effective. Rather than a manual of function signatures, the README leads with demo live scripts, one per data shape: Getting Started, Groups, XY, TimeSeries, an OnlineTable script that works with table data from an open dataset hosted on S3, and an advanced examples script. Each has a preview link and an Open in MATLAB Online link, and the README recommends opening the live scripts in MATLAB to benefit from interactive elements.

That choice matters because the API is wide. A grammar of graphics interface has a large surface, and live scripts with interactive controls teach it in a way a reference table cannot.

The alternative in the wider ecosystem is named in the README itself: Seaborn, the Python library with a similar role. The difference in approach is mostly the language and the surrounding stack. Gramm is a MATLAB toolbox that produces figures with MATLAB's graphics, and it targets people who already have MATLAB and already publish from it. Seaborn sits on the Python plotting stack and is the right answer for a Python data workflow.

For a MATLAB user the more interesting comparison is with writing the figure by hand with MATLAB's own plotting functions, which is what gramm is replacing. You give up exact control over individual handles and artists, because the figure is generated from the data description, and you gain the ability to change the grouping variable or add a facet and get a correct figure rather than a broken one.

That is the trade to make explicitly. If a figure needs a hand-tuned annotation, a custom inset or an unusual axis arrangement, hand-written MATLAB code is still the more direct route.

## Versions, the file exchange listing and what to verify

The release history is measured in small steps. Version 3.1.0 was published on 2025-11-05, 3.1.1 on 2026-03-26 and 3.1.2 on 2026-04-08, and the last push to the master branch was on 2026-10-02. The repository is not archived, so the code is still being worked on even though the tags are sparse.

Two things are worth checking before you rely on it. The first is the MATLAB version you are on. Gramm is distributed as a toolbox package and through the add-on manager, and toolbox packages carry their own version requirements, which the README does not spell out. The second is whether the toolbox covers the plot types your field needs, since the layer set is a fixed vocabulary and the gallery is the place to check it.

The citation guidance is also practical. The README asks users to cite gramm in publications, and the paper directory in the repository is presumably the source of that bibliography. If your group's figures are generated by this toolbox, the citation is the correct academic practice and it is part of adopting it, not an afterthought.

The licence is MIT, which is permissive for a toolbox that is usually used inside a research group or a commercial analysis pipeline, and the repository carries a CONTRIBUTING.md and a LICENSE file.

The last thing to weigh is the MATLAB dependency itself. Gramm is free and open, but it runs inside a commercial product, and the MathWorks licence is the real cost line for a team that does not already pay for MATLAB. The open-file-exchange listing and the MATLAB Online links remove the friction of trying it, but not of shipping with it.

## Conclusion

Adopt Gramm when you are plotting in MATLAB and want grouped, facetted figures with statistical layers without writing loops over colours and subplots, and when the audience is a journal that expects a particular figure style. Do not adopt it for a Python pipeline, where the README names seaborn as the analogue, and do not adopt it if you have no MATLAB licence, because the toolbox is distributed through the MATLAB add-on explorer and as an .mltbx package. Before you commit, open the Getting Started live script in MATLAB Online, where the README shows it running, and check the 3.1.x release line, since the last push was on 2026-10-02 and the last tagged release was v3.1.2 in April 2026.

## FAQ

### How do I install Gramm for MATLAB?

The recommended route is MATLAB's Add-ons explorer: search for gramm and click Add. You can also download the latest .mltbx file from the MATLAB Central File Exchange, or add the gramm folder from the repository to your path.

### How do I produce a figure with Gramm?

Create a gramm object with the x, y and grouping variables, add layers such as g.geom_point or g.stat_glm, optionally set names and the title, and call g.draw(). Colours, legends, axis limits and the subplot layout are generated for you rather than looped over.

### What is the relationship between Gramm, ggplot2 and seaborn?

Gramm is a MATLAB implementation of the grammar of graphics principles and of the ggplot2 library for R, and its name stands for GRAMmar of graphics for MATLAB. The README also notes that a similar library called Seaborn exists for Python, which is the analogue for a Python workflow.

### Can I try Gramm without a local MATLAB installation?

Yes. Every demo in the README is a live script with an Open in MATLAB Online link, and to run the files there you need to add the gramm folder to your path by selecting it in the files panel and choosing Add to Path, then Selected Folder(s).

## Sources

- [Issues](https://github.com/piermorel/gramm/issues)
- [License: MIT](https://github.com/piermorel/gramm/blob/master/LICENSE)
- [piermorel/gramm on GitHub](https://github.com/piermorel/gramm)
- [README](https://github.com/piermorel/gramm/blob/master/README.md)
- [Releases](https://github.com/piermorel/gramm/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/piermorel-gramm