Changes for JOSS revision

- Added contribution guidelines
- Expanded installation instructions
- Added statement of need to readme
- Emphasized role of examples.m file and output

CONTRIBUTING.md

@@ -0,0 +1,6 @@
+# How to contribute
+
+ - **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.
+ - **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.
+ - **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.
+ - **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

@@ -4,11 +4,20 @@ Gramm is a powerful plotting toolbox which allows to quickly create complex, pub
 
 
 ## Table of contents ##
+
+- [Why gramm?](#why-gramm)
 - [Citing gramm](#citing-gramm)
 - [Using gramm](#using-gramm)
 - [Features](#features)
 - [Use cases and examples (screenshots)](#use-cases-and-examples)
 
+## Why gramm ##
+
+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. 
+
+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.
+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)).
+
 ## Citing gramm ##
 
 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')
 g.draw()
 ```
 
-### Installation
-Add the folder containing the @gramm class folder to your path
+### Installation ###
+
+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))
 
 ### Figure export 
 
@@ -64,7 +74,7 @@ Tested under Matlab 2014b+ versions. With pre-2014b versions, gramm forces <code
 ### Documentation ###
 
 - [gramm cheat sheet](https://github.com/piermorel/gramm/blob/master/gramm%20cheat%20sheet.pdf)
-- Numerous examples in <code>html/examples.html</code> and the corresponding code in examples.m
+- 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)
 -  <code>doc gramm</code> to find links to the documentation of each method.
 
 
@@ -121,13 +131,13 @@ Tested under Matlab 2014b+ versions. With pre-2014b versions, gramm forces <code
 - Custom legend labels with <code>set_names()</code>
 - Plot reference line on the plots with <code>geom_abline()</code>, <code>geom_vline()</code>,<code>geom_hline()</code>
 - Plot reference polygons on the plots with <code>geom_polygon()</code>
-- Date ticks with set_datetick()
+- Date ticks with <code>set_datetick()</code>
 - 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.
 
 
 ## Use cases and examples
 
-The code for the following figures and numerous others is in <code>examples.m</code>.
+The code for the following figures and many others is in <code>examples.m</code>.
 
 ### Mapping groups of data to different visual properties
 All the mappings presented below can be combined.

examples.m

@@ -1,5 +1,4 @@
-%% gramm examples
-% Examples and how-tos for gramm
+%% gramm examples and how-tos
 %% Example from the readme
 % 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

html/examples.html

@@ -6,7 +6,7 @@
    <!--
 This HTML was auto-generated from MATLAB code.
 To make changes, update the MATLAB code and republish this document.
-      --><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">
+      --><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">
 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}
 
 html { min-height:100%; margin-bottom:1px; }
@@ -66,7 +66,7 @@
 
 
 
-  </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>;
+  </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>;
 </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);
 </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);
 </pre><p>Plot raw data as points</p><pre class="codeinput">g.geom_point();
@@ -1220,10 +1220,52 @@
 g17=gramm(<span class="string">'x'</span>,X,<span class="string">'y'</span>,Y,<span class="string">'color'</span>,C);
 g17.geom_line();
 g17.draw();
-</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><!--
+</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]);
+
+<span class="comment">% Define groups</span>
+cyl = [4 6 8]; <span class="comment">% Manually</span>
+orig = unique(cars.Origin_Region); <span class="comment">% Based on data</span>
+
+<span class="comment">% Loop over groups</span>
+<span class="keyword">for</span> oi = 1:length(orig) <span class="comment">% External loop on the axes</span>
+
+    <span class="comment">% Axes creation</span>
+    ax = subplot(1,length(orig),oi);
+    hold <span class="string">on</span>
+
+    <span class="keyword">for</span> ci = 1:length(cyl) <span class="comment">%Internal loop on the colors</span>
+
+        <span class="comment">% Data selection</span>
+        sel = strcmp(cars.Origin_Region,orig{oi}) &amp; <span class="keyword">...</span>
+            cars.Cylinders==cyl(ci) &amp; <span class="keyword">...</span>
+            ~isnan(cars.Model_Year) &amp; ~isnan(cars.MPG);
+
+        <span class="comment">% Plotting of raw data</span>
+        plot(cars.Model_Year(sel),cars.MPG(sel),<span class="string">'.'</span>, <span class="keyword">...</span>
+            <span class="string">'MarkerSize'</span>,15);
+
+        <span class="comment">% Keep the same color for the statistics</span>
+        ax.ColorOrderIndex = ax.ColorOrderIndex - 1;
+
+        <span class="comment">% Statistics (linear fit and plotting)</span>
+        b = [ones(sum(sel),1) cars.Model_Year(sel)] \ <span class="keyword">...</span>
+			cars.MPG(sel);
+        x_fit = [min(cars.Model_Year(sel)) <span class="keyword">...</span>
+			max(cars.Model_Year(sel))];
+        plot(x_fit, x_fit * b(2) + b(1),<span class="string">'LineWidth'</span>,1.5);
+    <span class="keyword">end</span>
+
+    <span class="comment">% Axes legends</span>
+    title([<span class="string">'Origin: '</span> orig{oi}]);
+    xlabel(<span class="string">'Year'</span>);
+    ylabel(<span class="string">'Fuel Economy (MPG)'</span>);
+<span class="keyword">end</span>
+<span class="comment">% Ugly color legend</span>
+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>);
+title(l,<span class="string">'#Cyl'</span>);
+</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><!--
 ##### SOURCE BEGIN #####
-%% gramm examples
-% Examples and how-tos for gramm
+%% gramm examples and how-tos
 %% Example from the readme
 % 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
@@ -2606,6 +2648,51 @@
 g17.draw();
 
 
+%% Raw matlab code equivalent to the first figure (in paper.md)
+
+figure('Position',[100 100 800 400],'Color',[1 1 1]);
+
+% Define groups
+cyl = [4 6 8]; % Manually
+orig = unique(cars.Origin_Region); % Based on data
+
+% Loop over groups
+for oi = 1:length(orig) % External loop on the axes
+
+    % Axes creation
+    ax = subplot(1,length(orig),oi);
+    hold on
+
+    for ci = 1:length(cyl) %Internal loop on the colors
+
+        % Data selection
+        sel = strcmp(cars.Origin_Region,orig{oi}) & ...
+            cars.Cylinders==cyl(ci) & ...
+            ~isnan(cars.Model_Year) & ~isnan(cars.MPG);
+
+        % Plotting of raw data
+        plot(cars.Model_Year(sel),cars.MPG(sel),'.', ...
+            'MarkerSize',15);
+
+        % Keep the same color for the statistics
+        ax.ColorOrderIndex = ax.ColorOrderIndex - 1;
+
+        % Statistics (linear fit and plotting)
+        b = [ones(sum(sel),1) cars.Model_Year(sel)] \ ...
+			cars.MPG(sel);
+        x_fit = [min(cars.Model_Year(sel)) ...
+			max(cars.Model_Year(sel))];
+        plot(x_fit, x_fit * b(2) + b(1),'LineWidth',1.5);
+    end
+
+    % Axes legends
+    title(['Origin: ' orig{oi}]);
+    xlabel('Year');
+    ylabel('Fuel Economy (MPG)');
+end
+% Ugly color legend
+l = legend('4','','6','','8','','Location','southeast');
+title(l,'#Cyl');