Skip to content

Commit f74c06d

Browse files
committed
Changes for JOSS revision
- Added contribution guidelines - Expanded installation instructions - Added statement of need to readme - Emphasized role of examples.m file and output
1 parent 8f6ecb0 commit f74c06d

File tree

4 files changed

+114
-12
lines changed

4 files changed

+114
-12
lines changed

CONTRIBUTING.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# How to contribute
2+
3+
- **Questions**: If you have a question on the use of gramm, first look through the documentation and in particular through examples.m and the corresponding [html/examples.html](http://htmlpreview.github.io/?https://github.com/piermorel/gramm/blob/master/html/examples.html) file to see if there is not already a recipe for what you want to achieve. If not then take a look at [closed issues](https://github.com/piermorel/gramm/issues?q=is%3Aissue+is%3Aclosed) on GitHub. Finally, if you can not find an answer there, do not hesitate to create a new [issue](https://github.com/piermorel/gramm/issues) with your question: they act as a sort of FAQ.
4+
- **Bugs**: Known bugs are left as [open issues](https://github.com/piermorel/gramm/issues) on GitHub, if you find a new one, please report it there and include a minimal working example demonstrating how the gramm results differ from what is expected.
5+
- **Enhancements**: You can propose enhancements by participating in this already existing [feature wishlist](https://github.com/piermorel/gramm/issues/50) thread that serves as a more general discussion and outlines what is planned next. For very specific/simple enhancements you can create separate issues on GitHub.
6+
- **Modifications**: If you want to extend the functionality of gramm, you are welcome to do so! Adding new ```geom_``` or ```stat_``` functions can be relatively easy due to their modular conception, while more in-depth changes might require some discussions on the internals of gramm. For discussion create a new issue or if your modifications are ready just submit a pull request. For new features, an addition to examples.m demonstrating their use is welcome. Additionally, you can make sure that your changes do not break anything by running examples.m in its entirety and comparing its output to the figures in the ```html/``` folder. I will review the code and functionality and eventually discuss/make changes to your commit before merging when it is working satisfactorily.

README.md

+15-5
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,20 @@ Gramm is a powerful plotting toolbox which allows to quickly create complex, pub
44

55

66
## Table of contents ##
7+
8+
- [Why gramm?](#why-gramm)
79
- [Citing gramm](#citing-gramm)
810
- [Using gramm](#using-gramm)
911
- [Features](#features)
1012
- [Use cases and examples (screenshots)](#use-cases-and-examples)
1113

14+
## Why gramm ##
15+
16+
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](https://www.jstatsoft.org/article/view/v040i01)) 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.
17+
18+
Inspired by ggplot2 ([Wickham 2009](http://ggplot2.org)), the R implementation of "grammar of graphics" principles ([Wilkinson 1999](http://www.springer.com/de/book/9781475731002)), gramm improves Matlab's plotting functionality, allowing to generate complex figures using high-level object-oriented code.
19+
Gramm has been used in several publications in the field of neuroscience, from human psychophysics ([Morel et al. 2017](https://doi.org/10.1371/journal.pbio.2001323)), to electrophysiology ([Morel et al. 2016](https://doi.org/10.1088/1741-2560/13/1/016002); [Ferrea et al. 2017](https://doi.org/10.1152/jn.00504.2017)), human functional imaging ([Wan et al. 2017](https://doi.org/10.1002/hbm.23932)) and animal training ([Berger et al. 2017](https://doi.org/10.1152/jn.00614.2017)).
20+
1221
## Citing gramm ##
1322

1423
If you use gramm plots in a publication you can cite it using the following DOI:
@@ -49,8 +58,9 @@ g.set_title('Fuel economy of new cars between 1970 and 1982')
4958
g.draw()
5059
```
5160

52-
### Installation
53-
Add the folder containing the @gramm class folder to your path
61+
### Installation ###
62+
63+
Download the gramm toolbox from GitHub ("Clone or download" button>download ZIP) or [clone it](https://help.github.com/articles/cloning-a-repository/), and add the folder containing the @gramm class folder to your Matlab path (using the [GUI](https://mathworks.com/help/matlab/matlab_env/add-remove-or-reorder-folders-on-the-search-path.html) or [```addpath()```](https://mathworks.com/help/matlab/ref/addpath.html))
5464

5565
### Figure export
5666

@@ -64,7 +74,7 @@ Tested under Matlab 2014b+ versions. With pre-2014b versions, gramm forces <code
6474
### Documentation ###
6575

6676
- [gramm cheat sheet](https://github.com/piermorel/gramm/blob/master/gramm%20cheat%20sheet.pdf)
67-
- Numerous examples in <code>html/examples.html</code> and the corresponding code in examples.m
77+
- Numerous coding examples and test cases in ```examples.m```, exported for preview in [html/examples.html](http://htmlpreview.github.io/?https://github.com/piermorel/gramm/blob/master/html/examples.html)
6878
- <code>doc gramm</code> to find links to the documentation of each method.
6979

7080

@@ -121,13 +131,13 @@ Tested under Matlab 2014b+ versions. With pre-2014b versions, gramm forces <code
121131
- Custom legend labels with <code>set_names()</code>
122132
- Plot reference line on the plots with <code>geom_abline()</code>, <code>geom_vline()</code>,<code>geom_hline()</code>
123133
- Plot reference polygons on the plots with <code>geom_polygon()</code>
124-
- Date ticks with set_datetick()
134+
- Date ticks with <code>set_datetick()</code>
125135
- 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.
126136

127137

128138
## Use cases and examples
129139

130-
The code for the following figures and numerous others is in <code>examples.m</code>.
140+
The code for the following figures and many others is in <code>examples.m</code>.
131141

132142
### Mapping groups of data to different visual properties
133143
All the mappings presented below can be combined.

examples.m

+1-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
%% gramm examples
2-
% Examples and how-tos for gramm
1+
%% gramm examples and how-tos
32
%% Example from the readme
43
% Here we plot the evolution of fuel economy of new cars bewteen 1970 and 1980 (carbig
54
% dataset). Gramm is used to easily separate groups on the basis of the number of

html/examples.html

+92-5
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
<!--
77
This HTML was auto-generated from MATLAB code.
88
To make changes, update the MATLAB code and republish this document.
9-
--><title>gramm examples</title><meta name="generator" content="MATLAB 9.0"><link rel="schema.DC" href="http://purl.org/dc/elements/1.1/"><meta name="DC.date" content="2017-12-04"><meta name="DC.source" content="examples.m"><style type="text/css">
9+
--><title>gramm examples and how-tos</title><meta name="generator" content="MATLAB 9.0"><link rel="schema.DC" href="http://purl.org/dc/elements/1.1/"><meta name="DC.date" content="2018-02-13"><meta name="DC.source" content="examples.m"><style type="text/css">
1010
html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;vertical-align:baseline;background:transparent}body{line-height:1}ol,ul{list-style:none}blockquote,q{quotes:none}blockquote:before,blockquote:after,q:before,q:after{content:'';content:none}:focus{outine:0}ins{text-decoration:none}del{text-decoration:line-through}table{border-collapse:collapse;border-spacing:0}
1111

1212
html { min-height:100%; margin-bottom:1px; }
@@ -66,7 +66,7 @@
6666

6767

6868

69-
</style></head><body><div class="content"><h1>gramm examples</h1><!--introduction--><p>Examples and how-tos for gramm</p><!--/introduction--><h2>Contents</h2><div><ul><li><a href="#1">Example from the readme</a></li><li><a href="#9">Grouping options in gramm</a></li><li><a href="#10">Methods for visualizing Y~X relationships with X as categorical variable</a></li><li><a href="#11">Methods for visualizing X densities</a></li><li><a href="#12">Methods for visualizing Y~X relationship with both X and Y as continuous variables</a></li><li><a href="#13">Methods for visualizing custom confidence intervals</a></li><li><a href="#14">Methods for visualizing 2D densities</a></li><li><a href="#15">Methods for visualizing repeated trajectories</a></li><li><a href="#16">Methods for visualizing repeated densities (e.g. spike densities)</a></li><li><a href="#17">Options for separating groups across subplots with facet_grid()</a></li><li><a href="#18">Options for creating histograms with stat_bin()</a></li><li><a href="#21">Visualize x-y difference with inset histogram using stat_cornerhist()</a></li><li><a href="#22">Graphic and normalization options in stat_violin()</a></li><li><a href="#23">Options for dodging and spacing graphic elements in <tt>stat_summary()</tt> and <tt>stat_boxplot()</tt></a></li><li><a href="#25">Plotting text or labeling with geom_label()</a></li><li><a href="#26">Smooth continuous data with stat_smooth()</a></li><li><a href="#27">Superimposing gramm plots with update(): Using different groups for different stat_ and geom_ methods</a></li><li><a href="#29">Superimposing gramm plots with update(): Plotting all the data in the background of facets</a></li><li><a href="#30">Use custom layouts in gramm, marginal histogram example</a></li><li><a href="#31">Plot one variable against many others</a></li><li><a href="#32">Customizing color maps with set_color_options()</a></li><li><a href="#33">Customizing color/lightness maps and legends with set_color_options()</a></li><li><a href="#34">Using a continuous color scale</a></li><li><a href="#35">Changing the order of elements with set_order_options()</a></li><li><a href="#36">Customize the size and style of graphic elements with set_line_options() and set_point_options()</a></li><li><a href="#37">Decorate plot backgrounds with geom_polygon()</a></li><li><a href="#38">Advanced customization of gramm figures</a></li><li><a href="#39">Using different input formats for x and y (1D arrays, cells of arrays, 2D arrays)</a></li></ul></div><h2>Example from the readme<a name="1"></a></h2><p>Here we plot the evolution of fuel economy of new cars bewteen 1970 and 1980 (carbig dataset). Gramm is used to easily separate groups on the basis of the number of cylinders of the cars (color), and on the basis of the region of origin of the cars (subplot columns). Both the raw data (points) and a glm fit with 95% confidence interval (line+shaded area) are plotted.</p><p>We stat by loading the sample data (structure created from the carbig dataset)</p><pre class="codeinput">load <span class="string">example_data</span>;
69+
</style></head><body><div class="content"><h1>gramm examples and how-tos</h1><!--introduction--><!--/introduction--><h2>Contents</h2><div><ul><li><a href="#1">Example from the readme</a></li><li><a href="#9">Grouping options in gramm</a></li><li><a href="#10">Methods for visualizing Y~X relationships with X as categorical variable</a></li><li><a href="#11">Methods for visualizing X densities</a></li><li><a href="#12">Methods for visualizing Y~X relationship with both X and Y as continuous variables</a></li><li><a href="#13">Methods for visualizing custom confidence intervals</a></li><li><a href="#14">Methods for visualizing 2D densities</a></li><li><a href="#15">Methods for visualizing repeated trajectories</a></li><li><a href="#16">Methods for visualizing repeated densities (e.g. spike densities)</a></li><li><a href="#17">Options for separating groups across subplots with facet_grid()</a></li><li><a href="#18">Options for creating histograms with stat_bin()</a></li><li><a href="#21">Visualize x-y difference with inset histogram using stat_cornerhist()</a></li><li><a href="#22">Graphic and normalization options in stat_violin()</a></li><li><a href="#23">Options for dodging and spacing graphic elements in <tt>stat_summary()</tt> and <tt>stat_boxplot()</tt></a></li><li><a href="#25">Plotting text or labeling with geom_label()</a></li><li><a href="#26">Smooth continuous data with stat_smooth()</a></li><li><a href="#27">Superimposing gramm plots with update(): Using different groups for different stat_ and geom_ methods</a></li><li><a href="#29">Superimposing gramm plots with update(): Plotting all the data in the background of facets</a></li><li><a href="#30">Use custom layouts in gramm, marginal histogram example</a></li><li><a href="#31">Plot one variable against many others</a></li><li><a href="#32">Customizing color maps with set_color_options()</a></li><li><a href="#33">Customizing color/lightness maps and legends with set_color_options()</a></li><li><a href="#34">Using a continuous color scale</a></li><li><a href="#35">Changing the order of elements with set_order_options()</a></li><li><a href="#36">Customize the size and style of graphic elements with set_line_options() and set_point_options()</a></li><li><a href="#37">Decorate plot backgrounds with geom_polygon()</a></li><li><a href="#38">Advanced customization of gramm figures</a></li><li><a href="#39">Using different input formats for x and y (1D arrays, cells of arrays, 2D arrays)</a></li><li><a href="#45">Raw matlab code equivalent to the first figure (in paper.md)</a></li></ul></div><h2>Example from the readme<a name="1"></a></h2><p>Here we plot the evolution of fuel economy of new cars bewteen 1970 and 1980 (carbig dataset). Gramm is used to easily separate groups on the basis of the number of cylinders of the cars (color), and on the basis of the region of origin of the cars (subplot columns). Both the raw data (points) and a glm fit with 95% confidence interval (line+shaded area) are plotted.</p><p>We stat by loading the sample data (structure created from the carbig dataset)</p><pre class="codeinput">load <span class="string">example_data</span>;
7070
</pre><p>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</p><pre class="codeinput">g=gramm(<span class="string">'x'</span>,cars.Model_Year,<span class="string">'y'</span>,cars.MPG,<span class="string">'color'</span>,cars.Cylinders,<span class="string">'subset'</span>,cars.Cylinders~=3 &amp; cars.Cylinders~=5);
7171
</pre><p>Subdivide the data in subplots horizontally by region of origin using facet_grid()</p><pre class="codeinput">g.facet_grid([],cars.Origin_Region);
7272
</pre><p>Plot raw data as points</p><pre class="codeinput">g.geom_point();
@@ -1220,10 +1220,52 @@
12201220
g17=gramm(<span class="string">'x'</span>,X,<span class="string">'y'</span>,Y,<span class="string">'color'</span>,C);
12211221
g17.geom_line();
12221222
g17.draw();
1223-
</pre><img vspace="5" hspace="5" src="examples_41.png" alt=""> <p class="footer"><br><a href="http://www.mathworks.com/products/matlab/">Published with MATLAB&reg; R2016a</a><br></p></div><!--
1223+
</pre><img vspace="5" hspace="5" src="examples_41.png" alt=""> <h2>Raw matlab code equivalent to the first figure (in paper.md)<a name="45"></a></h2><pre class="codeinput">figure(<span class="string">'Position'</span>,[100 100 800 400],<span class="string">'Color'</span>,[1 1 1]);
1224+
1225+
<span class="comment">% Define groups</span>
1226+
cyl = [4 6 8]; <span class="comment">% Manually</span>
1227+
orig = unique(cars.Origin_Region); <span class="comment">% Based on data</span>
1228+
1229+
<span class="comment">% Loop over groups</span>
1230+
<span class="keyword">for</span> oi = 1:length(orig) <span class="comment">% External loop on the axes</span>
1231+
1232+
<span class="comment">% Axes creation</span>
1233+
ax = subplot(1,length(orig),oi);
1234+
hold <span class="string">on</span>
1235+
1236+
<span class="keyword">for</span> ci = 1:length(cyl) <span class="comment">%Internal loop on the colors</span>
1237+
1238+
<span class="comment">% Data selection</span>
1239+
sel = strcmp(cars.Origin_Region,orig{oi}) &amp; <span class="keyword">...</span>
1240+
cars.Cylinders==cyl(ci) &amp; <span class="keyword">...</span>
1241+
~isnan(cars.Model_Year) &amp; ~isnan(cars.MPG);
1242+
1243+
<span class="comment">% Plotting of raw data</span>
1244+
plot(cars.Model_Year(sel),cars.MPG(sel),<span class="string">'.'</span>, <span class="keyword">...</span>
1245+
<span class="string">'MarkerSize'</span>,15);
1246+
1247+
<span class="comment">% Keep the same color for the statistics</span>
1248+
ax.ColorOrderIndex = ax.ColorOrderIndex - 1;
1249+
1250+
<span class="comment">% Statistics (linear fit and plotting)</span>
1251+
b = [ones(sum(sel),1) cars.Model_Year(sel)] \ <span class="keyword">...</span>
1252+
cars.MPG(sel);
1253+
x_fit = [min(cars.Model_Year(sel)) <span class="keyword">...</span>
1254+
max(cars.Model_Year(sel))];
1255+
plot(x_fit, x_fit * b(2) + b(1),<span class="string">'LineWidth'</span>,1.5);
1256+
<span class="keyword">end</span>
1257+
1258+
<span class="comment">% Axes legends</span>
1259+
title([<span class="string">'Origin: '</span> orig{oi}]);
1260+
xlabel(<span class="string">'Year'</span>);
1261+
ylabel(<span class="string">'Fuel Economy (MPG)'</span>);
1262+
<span class="keyword">end</span>
1263+
<span class="comment">% Ugly color legend</span>
1264+
l = legend(<span class="string">'4'</span>,<span class="string">''</span>,<span class="string">'6'</span>,<span class="string">''</span>,<span class="string">'8'</span>,<span class="string">''</span>,<span class="string">'Location'</span>,<span class="string">'southeast'</span>);
1265+
title(l,<span class="string">'#Cyl'</span>);
1266+
</pre><img vspace="5" hspace="5" src="examples_42.png" alt=""> <p class="footer"><br><a href="http://www.mathworks.com/products/matlab/">Published with MATLAB&reg; R2016a</a><br></p></div><!--
12241267
##### SOURCE BEGIN #####
1225-
%% gramm examples
1226-
% Examples and how-tos for gramm
1268+
%% gramm examples and how-tos
12271269
%% Example from the readme
12281270
% Here we plot the evolution of fuel economy of new cars bewteen 1970 and 1980 (carbig
12291271
% dataset). Gramm is used to easily separate groups on the basis of the number of
@@ -2606,6 +2648,51 @@
26062648
g17.draw();
26072649
26082650
2651+
%% Raw matlab code equivalent to the first figure (in paper.md)
2652+
2653+
figure('Position',[100 100 800 400],'Color',[1 1 1]);
2654+
2655+
% Define groups
2656+
cyl = [4 6 8]; % Manually
2657+
orig = unique(cars.Origin_Region); % Based on data
2658+
2659+
% Loop over groups
2660+
for oi = 1:length(orig) % External loop on the axes
2661+
2662+
% Axes creation
2663+
ax = subplot(1,length(orig),oi);
2664+
hold on
2665+
2666+
for ci = 1:length(cyl) %Internal loop on the colors
2667+
2668+
% Data selection
2669+
sel = strcmp(cars.Origin_Region,orig{oi}) & ...
2670+
cars.Cylinders==cyl(ci) & ...
2671+
~isnan(cars.Model_Year) & ~isnan(cars.MPG);
2672+
2673+
% Plotting of raw data
2674+
plot(cars.Model_Year(sel),cars.MPG(sel),'.', ...
2675+
'MarkerSize',15);
2676+
2677+
% Keep the same color for the statistics
2678+
ax.ColorOrderIndex = ax.ColorOrderIndex - 1;
2679+
2680+
% Statistics (linear fit and plotting)
2681+
b = [ones(sum(sel),1) cars.Model_Year(sel)] \ ...
2682+
cars.MPG(sel);
2683+
x_fit = [min(cars.Model_Year(sel)) ...
2684+
max(cars.Model_Year(sel))];
2685+
plot(x_fit, x_fit * b(2) + b(1),'LineWidth',1.5);
2686+
end
2687+
2688+
% Axes legends
2689+
title(['Origin: ' orig{oi}]);
2690+
xlabel('Year');
2691+
ylabel('Fuel Economy (MPG)');
2692+
end
2693+
% Ugly color legend
2694+
l = legend('4','','6','','8','','Location','southeast');
2695+
title(l,'#Cyl');
26092696
26102697
26112698

0 commit comments

Comments
 (0)