diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5e60b04 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/README.md b/README.md index 47c9c3c..6ffb243 100644 --- a/README.md +++ b/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 html/examples.html 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) - doc gramm to find links to the documentation of each method. @@ -121,13 +131,13 @@ Tested under Matlab 2014b+ versions. With pre-2014b versions, gramm forces set_names() - Plot reference line on the plots with geom_abline(), geom_vline(),geom_hline() - Plot reference polygons on the plots with geom_polygon() -- Date ticks with set_datetick() +- Date ticks with set_datetick() - 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 examples.m. +The code for the following figures and many others is in examples.m. ### Mapping groups of data to different visual properties All the mappings presented below can be combined. diff --git a/examples.m b/examples.m index 176b45b..44187a5 100644 --- a/examples.m +++ b/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 diff --git a/html/examples.html b/html/examples.html index 63df1f3..ae29379 100644 --- a/html/examples.html +++ b/html/examples.html @@ -6,7 +6,7 @@ gramm examples

gramm examples

Examples and how-tos for gramm

Contents

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 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.

We stat by loading the sample data (structure created from the carbig dataset)

load example_data;
+  

gramm examples and how-tos

Contents

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 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.

We stat by loading the sample data (structure created from the carbig dataset)

load example_data;
 

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

g=gramm('x',cars.Model_Year,'y',cars.MPG,'color',cars.Cylinders,'subset',cars.Cylinders~=3 & cars.Cylinders~=5);
 

Subdivide the data in subplots horizontally by region of origin using facet_grid()

g.facet_grid([],cars.Origin_Region);
 

Plot raw data as points

g.geom_point();
@@ -1220,10 +1220,52 @@
 g17=gramm('x',X,'y',Y,'color',C);
 g17.geom_line();
 g17.draw();
-