tutorials and documentation

[schluppeck]

pierre, thanks for your work on this really fantastic toolbox - and making it available here. we've started using it in my lab and it has quickly proven to be super-useful.

i have also been encouraging colleagues to re-think they way they do their plotting in matlab with gramm.

you mentioned in a separate thread that developing some tutorials + walk-throughs and a bit more documentation is a priority (but potentially v time consuming). i thought i'd open this up to get your and other people's ideas about what would be most useful, to prioritise where i/we could best contribute...

[piermorel]

Thanks for opening the issue on this. Currently documentation is in 4 places:

• The workflow section in Readme.md is a brief walk through the first example of examples.m
• The cheat sheet: its main purpose is to list all commands and the options for each. Its usefulness if you don't know how to use gramm/ggplot is limited
• The actual documentation doc gramm is more complete/explicit than the cheat sheet but suffers from the same drawbacks.
• The examples.m file (and associated output in the html folder) is for now what is probably most useful: users can open examples.html, look out for something similar to what they want to do and try to understand how it works from the code. But you need to understand a bit in the first place.

I was discussing about documentation with @MooMinIL there initially: https://github.com/piermorel/gramm/issues/23 Integrating a better version of the workflow for beginners in the cheat sheet seemed like a good idea, especially since gramm is "weird" for Matlab users (object based, and ggplot2 is a bit weird).

[schluppeck]

Great - the documentation looks super-detailed... I agree - experts / people with experience should be able to look up what they want to achieve and use code examples to get there.

Maybe best to try and come up with a gentle, more verbose tutorial style intro for newcomers to the grammar of graphics ideas and GRAMM. I'll have a go a putting together some code snippets + a markdown document (pitched at that level) to go along and send you a PR - so you can have a look...

[piermorel]

Great, thanks ! In the meantime I will see about organizing examples.m better, adding more examples for things that are not straightforward (update()is a strong contender there!).

[piermorel]

I added method category titles to the cheat sheet in the last commit... does that help?

[MooMinIL]

Great job, I think it really helps visualizing the order methods are used. I would, however, change it so that the ordering itself is slightly more obvious from the titles, maybe change the order in which things are mentioned: "CONSTRUCTOR – Object creation and assignment, first step" -> "first step: CONSTRUCTOR – Object creation and assignment". Just a thought.

Also, Just noticed the export feature, pretty cool!

[MooMinIL]

Hey, I went through the cheatsheet recently and realized that in the CONSTRUCTOR section, the fields 'ymax'/'ymin' aren't represented and in general are only mentioned in the geom_interval section without explained how the intervals are formatted (absolute or relative values). Just FYI.

[piermorel]

Thanks for the comment, I added precisions about those in the latest commit.

[musm]

Are there any tutorials for 3d scatter plots?

[piermorel]

Nothing yet, I should add some stuff in the examples.m ... If you're wondering, it just works by providing a 'z' variable in the gramm() call (same format as 'y'). Then only geom_point(), geom_line(), and stat_ellipse() work.

[Leberer]

Hej, wasn't sure if it's worth opening a new "issue" for my question so I better just put it here. Thanks from me as well, Pierre. Totally new to Matlab for my Master thesis and gramm helps me to keep all those graphs nice and consistent. The example file really helps me so far when the cheatsheet isn't there to save the day...

One quick question though. I wanted to create a graph with two axes (in my case a climate diagram with temperature and precipitation on different Y-axes). I didn't find anything in the examples or here so I don't know if this is possible or not? I ended up using matlabs yyaxis implementation and it works, just would be amazing if it's possible in gramm as well.

[piermorel]

Hello,

Glad to hear you are enjoying gramm! However it doesn't support double y axes. Just a quick look into that shows me that this actually something that has changed in recent matlab versions (plotyy to yyaxis), which doesn't make things easier in terms of comaptibility.

With the new yyaxis it may be possible to hack something by changing the yyaxis of each facet after a draw() call (the facet axes handles are stored as properties of the object) and using update() to plot the new data? I can't try it now but let me know how it goes.

[svenjakemmer]

Hi, thanks for this great package! I come from R, now programming in Matlab and was super happy to find your package :). I was wondering if there is a way to plot two data sets in the same graph. Let's say I have one data set that I want to use to plot a line, and another to plot data points. I found the update() function, but I can't manage to plot the data on the same axes.

% Data for lines
x_line = 1:10;
y_line = sin(x_line);

% Data for points
x_points = 1:0.5:10;
y_points = cos(x_points);

% Create a gramm object with the line data
clear g
g = gramm('x',x_line,'y',y_line);

% Add a line layer
g.geom_line();

% Draw the lines
figure('Position',[100 100 800 600]);
g.draw(); 

% Update x and y values for the data points
g.update('x', x_points,'y',y_points, 'color', y_points);

% Add a point layer with the second data set
g.geom_point();
g.set_color_options();

% Draw data points
g.draw();

This is what I get:

Moreover, I needed to define the y_points as color argument to be able to see the data points at all. Would be happy to have them just in the same color as the lines. Do you have an advice for me? Thanks in advance!

[piermorel]

Hi Svenja,

Thanks for your feedback, it looks like you uncovered a gramm bug with update ! I will create a new issue and look into it.