ggplot2 docs sneak peek

102 views
Skip to first unread message

Hadley Wickham

unread,
Mar 17, 2012, 11:08:00 AM3/17/12
to ggplot2
Hi all,

Over the last couple of days, I've been hard at work preparing a
replacement for the outdated ggplot2 documentation website:
http://had.co.nz/ggplot2/docs/. It's not 100% done, but it's getting
pretty close, and it's probably at a useful point for feedback.

The cool thing about the website is that it's generated from the
package documentation so it will always be perfectly in sync. The
same code (https://github.com/hadley/staticdocs) can be used for any
package, so I'll hopefully be able to get plyr and reshape2 docs up on
their respective websites too.

Hadley

--
Assistant Professor / Dobelman Family Junior Chair
Department of Statistics / Rice University
http://had.co.nz/

Winston Chang

unread,
Mar 17, 2012, 4:07:46 PM3/17/12
to Hadley Wickham, ggplot2
It looks really nice, especially compared to the usual html documentation. I think that in general you could get away with using smaller images (maybe by using a lower dpi value). It would also be nice to be able to collapse/expand the images, individually or all together. That would make it easier to compare variations in the example code.

-Winston

--
You received this message because you are subscribed to the ggplot2 mailing list.
Please provide a reproducible example: http://gist.github.com/270442

To post: email ggp...@googlegroups.com
To unsubscribe: email ggplot2+u...@googlegroups.com
More options: http://groups.google.com/group/ggplot2

Jean-Olivier Irisson

unread,
Mar 19, 2012, 8:16:15 PM3/19/12
to Hadley Wickham, ggplot2
On 2012-Mar-17, at 16:08 , Hadley Wickham wrote:
>
> Over the last couple of days, I've been hard at work preparing a
> replacement for the outdated ggplot2 documentation website:
> http://had.co.nz/ggplot2/docs/. It's not 100% done, but it's getting
> pretty close, and it's probably at a useful point for feedback.
>
> The cool thing about the website is that it's generated from the
> package documentation so it will always be perfectly in sync. The
> same code (https://github.com/hadley/staticdocs) can be used for any
> package, so I'll hopefully be able to get plyr and reshape2 docs up on
> their respective websites too.

It's great that it will be kept up to date, the abundance of links and the clean layout are really appreciable. But I am afraid it lost the main appeal of the old site: the visual index. The small thumbnails allowed to quickly browse the various functions and get a feel for their use. It was great to discover geoms or to guess which scale function one should use. It gave a real incentive to go read the help on the website rather than in R's help browser.

With the new site, I'm not sure the incentive would be as strong. The fact that every function name is a link is nice, but with the new ggplot help, most functions that really deserve a link are already linked in the "See also" part. The graphical output after each example is of course very nice, but I think it can also be available in R's built in html help (I use inline text-based help in a terminal but I have seen people with graphs in their help files in previous versions of ggplot at least) and example() is not very hard to run. On the other hand, going to the site has a cost: having a web browser open instead of the clean help panel of RStudio for example, send to an external website for non-ggplot2 functions, without the usual navigation of the regular help browser, etc.

Also, compared to the old site, I am missing the list of accessible aesthetics for each geom, and in particular the required vs facultative ones.

Finally, and that's more a general remark about ggplot's help, I find that having a mix of true functions (such as aes, aes_string) and "fake" ones which are only used to document usage (such as aes_group_order or aes_colour_fill_alpha) is confusing, especially given the similarity of names. Another good (bad?) example is alpha, which is a function that was in ggplot, is now in scale, but which now also has a help page in ggplot. It's not the documenting the alpha() function anymore, just the usage of the alpha aesthetic, but someone looking for the function might not understand why it is not available. Maybe prefix all those "fake" functions with doc_ or usage_? In any case, the website could be a great opportunity to differentiate the true functions from the others, and appropriately show the relevant "usage" documentation when browsing a particular function (show links or even inline versions of all the aes_*** usage help files when reading the help of aes).

Thanks for all your efforts. I don't want to sound too harsh even though I probably do :-/ . I really think that the thumbnails provided large additional value to the website.

Jean-Olivier Irisson
---
Observatoire Océanologique
Station Zoologique, B.P. 28, Chemin du Lazaret
06230 Villefranche-sur-Mer
Tel: +33 04 93 76 38 04
Mob: +33 06 21 05 19 90
http://jo.irisson.com/

Hadley Wickham

unread,
Mar 19, 2012, 11:48:09 PM3/19/12
to Jean-Olivier Irisson, ggplot2
> It's great that it will be kept up to date, the abundance of links and the clean layout are really appreciable. But I am afraid it lost the main appeal of the old site: the visual index. The small thumbnails allowed to quickly browse the various functions and get a feel for their use. It was great to discover geoms or to guess which scale function one should use. It gave a real incentive to go read the help on the website rather than in R's help browser.

Yes, we'll recreate that by hand - it's not something that can (or
should) be automated, but will be part of the new ggplot2 website.

> With the new site, I'm not sure the incentive would be as strong. The fact that every function name is a link is nice, but with the new ggplot help, most functions that really deserve a link are already linked in the "See also" part. The graphical output after each example is of course very nice, but I think it can also be available in R's built in html help (I use inline text-based help in a terminal but I have seen people with graphs in their help files in previous versions of ggplot at least) and example() is not very hard to run. On the other hand, going to the site has a cost: having a web browser open instead of the clean help panel of RStudio for example, send to an external website for non-ggplot2 functions, without the usual navigation of the regular help browser, etc.
>
> Also, compared to the old site, I am missing the list of accessible aesthetics for each geom, and in particular the required vs facultative ones.

Yes, that's missing in the Rd files too and is on the to do list to
fix - https://github.com/hadley/ggplot2/issues/447

> Finally, and that's more a general remark about ggplot's help, I find that having a mix of true functions (such as aes, aes_string) and "fake" ones which are only used to document usage (such as aes_group_order or aes_colour_fill_alpha) is confusing, especially given the similarity of names. Another good (bad?) example is alpha, which is a function that was in ggplot, is now in scale, but which now also has a help page in ggplot. It's not the documenting the alpha() function anymore, just the usage of the alpha aesthetic, but someone looking for the function might not understand why it is not available. Maybe prefix all those "fake" functions with doc_ or usage_? In any case, the website could be a great opportunity to differentiate the true functions from the others, and appropriately show the relevant "usage" documentation when browsing a particular function (show links or even inline versions of all the aes_*** usage help files when reading the help of aes).

Well, that comes from's R confusion between topics and functions, so I
don't think there's much I can do about it.

Jean-Olivier Irisson

unread,
Mar 20, 2012, 3:00:53 AM3/20/12
to Hadley Wickham, ggplot2
On 2012-Mar-20, at 04:48 , Hadley Wickham wrote:
>
>> It's great that it will be kept up to date, the abundance of links and the clean layout are really appreciable. But I am afraid it lost the main appeal of the old site: the visual index. The small thumbnails allowed to quickly browse the various functions and get a feel for their use. It was great to discover geoms or to guess which scale function one should use. It gave a real incentive to go read the help on the website rather than in R's help browser.
>
> Yes, we'll recreate that by hand - it's not something that can (or
> should) be automated, but will be part of the new ggplot2 website.

Great! That's a relief!

>> Finally, and that's more a general remark about ggplot's help, I find that having a mix of true functions (such as aes, aes_string) and "fake" ones which are only used to document usage (such as aes_group_order or aes_colour_fill_alpha) is confusing, especially given the similarity of names. Another good (bad?) example is alpha, which is a function that was in ggplot, is now in scale, but which now also has a help page in ggplot. It's not the documenting the alpha() function anymore, just the usage of the alpha aesthetic, but someone looking for the function might not understand why it is not available. Maybe prefix all those "fake" functions with doc_ or usage_? In any case, the website could be a great opportunity to differentiate the true functions from the others, and appropriately show the relevant "usage" documentation when browsing a particular function (show links or even inline versions of all the aes_*** usage help files when reading the help of aes).
>
> Well, that comes from's R confusion between topics and functions, so I
> don't think there's much I can do about it.

You can't fix it in R's doc but you might on the website right? Solutions I would think of are:
- a list of the help files which are topics, manually updated
- a common prefix for all topics
- a custom roxygen tag for topics which either generate the topics list file or directly influences the generation of the website
- a common word/phrase in the description part (or any other part) of the help file which works as a custom tag (currently, many start by "This page demonstrates" for example)

Then topics would be separated from functions on the index page (functions themselves could probably be split in geom, scales, facet etc. as in the old site).

Timothy Bates

unread,
Mar 20, 2012, 1:40:51 PM3/20/12
to ggplot2
On 17 Mar 2012, at 3:08 PM, Hadley Wickham <had...@rice.edu> wrote:
Over the last couple of days, I've been hard at work preparing a
replacement for the outdated ggplot2 documentation website:
http://had.co.nz/ggplot2/docs/.  It's not 100% done, but it's getting
pretty close, and it's probably at a useful point for feedback.

Hi hadley, 
So, first off: Thanks for working hard on this.


The cool thing about the website is that it's generated from the
package documentation so it will always be perfectly in sync.

I think in R, because people are busy, and no-one’s paid, there’s a perfectly reasonably desire to keep things simple and automated. If that’s the goal then this hits it.

However, Just as R package “documentation” files, with their alphabetical listings of everything, (even data files!!) mixed up with internal helpers and key functions buried amongst that are almost no use to someone looking for help.

Automated documentation, built out of the code and it’s parameters, is that it really leaves a lot to be desired for someone with a question in their mind (and that’s about everyone).

What works really well is curated task-driven pages with clear explanatory text, well-chosen (and commented) examples, and a well organized contents page

My positive suggestions would be

Try and add hints to the list generator so that, for instance, it can collect example data files together under a “Data files” heading.
Even a set of basic heading hints, embedded in the source that this program could use to aggregate: 
# Core functions
# Example Data
# Sub functions
  ## Aesthetics
  ## Geoms
 ...

Try to prioritize the tiny set of commonly used functions over all the others. Create a learning curve.

Give examples, with comments as to what the example is trying to do, all the parameters named, links to the graphical output...
Like the old diamonds book…

Link everything: Make it possible to get from qplot to other pages that use it, or expand on it, or supplant it, or give examples for it…
Link to stack overflow, and crossvalidated, and to bloggers who’ve used the package and tried to give good specific examples.
Have a search box which aggregates stackoverflow, r-help with tags for ggplot2…

Negative comments
This alphabetical list of  250+ functions will not help people trying to learn ggplot or solve a problem
Probably doesn’t need to have a dedicate dbox of dependencies, etc. Maybe this whole page could be an appendix: an alphabetical listing and technical data?
The top link of "ggplot2-package: ggplot2” takes you to this:





I think at that point most people will give up (some will cry :-) )


Take this with a grain of salt, I’ve just been teaching  in R with bright post-graduates highlights and it drives home repeatedly to me how they see R as almost purposively obscure and inconsistent during their learning (despite their also loving how R gets things done when it does work smoothly for them)

There’s also a _very_ low bar set for help R in general, with error messages that help you solve the error frowned upon. 

Compare to a well organized and helpful site, like  http://www.statmethods.net

I think he went backwards with the reworking, but it is still a great place to learn R from.

My guess is that if you stick a markdown wiki into had.co.nz, then users can take care of all of this for you: many of us like to store knowledge publicly.

best, t

hamamelis

unread,
Mar 20, 2012, 7:02:41 PM3/20/12
to ggp...@googlegroups.com
I like the colour graphs - it gives a quick impression of how things may turn out.

I note that scale_colour_manual has an entry but scale_linetype_manual & scale_size_manual both link to scalce_colour_manual.

I recently worked out how to use these two (and colour too) and there is a worked example at the end of https://groups.google.com/forum/?fromgroups#!topic/ggplot2/YfgemhNoAZ4.  You are welcome to use it or adapt it, if it would be any use.

Ian


Brian Diggs

unread,
Mar 20, 2012, 7:03:43 PM3/20/12
to Timothy Bates, ggplot2
On 3/20/2012 10:40 AM, Timothy Bates wrote:
> On 17 Mar 2012, at 3:08 PM, Hadley
> Wickham<hadley-OhmvVRJSr/I...@public.gmane.org> wrote:
>> Over the last couple of days, I've been hard at work preparing a
>> replacement for the outdated ggplot2 documentation website:
>> http://had.co.nz/ggplot2/docs/. It's not 100% done, but it's
>> getting pretty close, and it's probably at a useful point for
>> feedback.
>
> Hi hadley, So, first off: Thanks for working hard on this.
>
>
>> The cool thing about the website is that it's generated from the
>> package documentation so it will always be perfectly in sync.
>
> I think in R, because people are busy, and no-one�s paid, there�s a

> perfectly reasonably desire to keep things simple and automated. If
> that�s the goal then this hits it.
>
> However, Just as R package �documentation� files, with their

> alphabetical listings of everything, (even data files!!) mixed up
> with internal helpers and key functions buried amongst that are
> almost no use to someone looking for help.
>
> Automated documentation, built out of the code and it�s parameters,

> is that it really leaves a lot to be desired for someone with a
> question in their mind (and that�s about everyone).

>
> What works really well is curated task-driven pages with clear
> explanatory text, well-chosen (and commented) examples, and a well
> organized contents page

In principle, I think you are right. However, the problem is that
carefully curated information can never really keep up with
automatically organized data. The problems with volume and immediacy are
too great. Compare, for example, DMOZ vs Google (or a more fair
comparison may be Wikipedia vs Google).

The place where this works well is books, because the expected updating
cycle (new editions) are much longer and level of being out of date is
accepted. Not to mention a different economic model.

> My positive suggestions would be
>
> Try and add hints to the list generator so that, for instance, it can

> collect example data files together under a �Data files� heading.


> Even a set of basic heading hints, embedded in the source that this
> program could use to aggregate: # Core functions # Example Data # Sub
> functions ## Aesthetics ## Geoms ...

Some of this is doable automatically. Breaking out datasets is the
easiest. They are (should be) tagged with the keyword datasets.
Unfortunately, the list of allowable keywords is fixed, and looking over
them (gtools::keywords()) doesn't necessarily give a good set of generic
ones for this purpose. One that I was looking for in particular is
something that would tag a page as general descriptive documentation and
not documenting a specific function. "documentation" is more about
functions which are designed to manage, manipulate, and display
documentation. Maybe it should all go together as part of "package" (but
I think that is abusing that). There needs to be a "concepts" or
something like that. (The counter argument being that that kind of
documentation belongs in a vignette, not Rd files.)

The other facility available is the @family tag of roxygen, and the see
also section of the Rd files in general. Unfortunately, the @family tag
does not survive to the Rd files; at that point it is just a list of
linked functions.

I decided to try and see what could be pulled out in terms of automated
cluster detection of Rd files based on cross references.

library("tools")
library("plyr")
library("igraph")

tagsets <- function(l, tags) {
has_tag <- ((attr(l, "Rd_tag") == tags[1]) & is.null(attr(l,
"Rd_option"))) #Rd_option indicates other package
if (is.recursive(l)) {
tags <- tags[c(!has_tag, rep(TRUE, length(tags)-1))]
llply(l, tagsets, tags)
} else {
if(has_tag) {
l
}
}
}

Rdfiles <- list.files("ggplot2/man", pattern="Rd", full.names=TRUE)
seealso <- ldply(Rdfiles, function(Rdfile) {
Rd <- parse_Rd(Rdfile)
fun.name <- unlist(tagsets(Rd, c("\\name", "VERB")))
alias.names <- unlist(tagsets(Rd, c("\\alias", "VERB")))
alias.names <- setdiff(alias.names, fun.name)
seealsos <- unlist(tagsets(Rd, c("\\seealso", "\\link", "TEXT")))
if (length(seealsos) > 0 | length(alias.names) > 0) {
rbind(
data.frame(fun=fun.name, seealso=c(seealsos, alias.names)),
ldply(alias.names, function(alias) {
data.frame(fun=alias, seealso=c(fun.name,
setdiff(alias.names, alias), seealsos))
}))
} else {
NULL
}})


g <- graph.data.frame(seealso, directed=TRUE)

g.cl <- maximal.cliques(g)
llply(g.cl[sapply(g.cl, function(cl) {length(cl)>3})], function(cl)
{V(g)[cl]})

This identifies the clusters:

[[1]]
Vertex sequence:
[1] "geom_abline" "geom_hline" "geom_segment" "geom_vline"

[[2]]
Vertex sequence:
[1] "guide_colourbar" "guide_colorbar" "guide_legend" "guides"

[[3]]
Vertex sequence:
[1] "hmisc" "mean_cl_boot" "mean_cl_normal" "mean_sdl"
[5] "median_hilow"

[[4]]
Vertex sequence:
[1] "label_both" "label_bquote" "label_parsed" "label_value"

[[5]]
Vertex sequence:
[1] "position_dodge" "position_fill" "position_identity"
[4] "position_jitter" "position_stack"

[[6]]
Vertex sequence:
[1] "scale_colour_brewer" "scale_color_brewer"
[3] "scale_fill_brewer" "scale_colour_gradient"
[5] "scale_color_continuous" "scale_color_gradient"
[7] "scale_colour_continuous" "scale_fill_continuous"
[9] "scale_fill_gradient" "scale_colour_gradient2"
[11] "scale_color_gradient2" "scale_fill_gradient2"
[13] "scale_colour_gradientn" "scale_color_gradientn"
[15] "scale_fill_gradientn" "scale_colour_grey"
[17] "scale_color_grey" "scale_fill_grey"
[19] "scale_colour_hue" "scale_color_discrete"
[21] "scale_color_hue" "scale_colour_discrete"
[23] "scale_fill_discrete" "scale_fill_hue"

[[7]]
Vertex sequence:
[1] "scale_colour_identity" "scale_alpha_identity"
[3] "scale_color_identity" "scale_fill_identity"
[5] "scale_linetype_identity" "scale_shape_identity"
[7] "scale_size_identity"

[[8]]
Vertex sequence:
[1] "scale_colour_manual" "scale_alpha_manual" "scale_color_manual"
[4] "scale_fill_manual" "scale_linetype_manual" "scale_shape_manual"
[7] "scale_size_manual"

[[9]]
Vertex sequence:
[1] "scale_x_continuous" "scale_x_log10" "scale_x_reverse"
[4] "scale_x_sqrt" "scale_y_continuous" "scale_y_log10"
[7] "scale_y_reverse" "scale_y_sqrt" "scale_x_date"
[10] "scale_y_date" "scale_x_datetime" "scale_y_datetime"
[13] "scale_x_discrete" "scale_y_discrete"

[[10]]
Vertex sequence:
[1] "geom_crossbar" "geom_errorbar" "geom_linerange" "geom_pointrange"
[5] "geom_smooth"

[[11]]
Vertex sequence:
[1] "geom_crossbar" "geom_errorbar" "geom_linerange" "geom_pointrange"
[5] "stat_summary"

[[12]]
Vertex sequence:
[1] "fortify-multcomp" "fortify.cld" "fortify.confint.glht"
[4] "fortify.glht" "fortify.summary.glht"

[[13]]
Vertex sequence:
[1] "aes_colour_fill_alpha" "alpha" "color"
[4] "colour" "fill"

[[14]]
Vertex sequence:
[1] "aes_linetype_size_shape" "linetype"
[3] "shape" "size"

[[15]]
Vertex sequence:
[1] "aes_position" "x" "xend" "xmax" "xmin"

[6] "y" "yend" "ymax" "ymin"

Which seems to pick up the families: facet labellers (4th one), position
adjustments (5th one), position scales (9th one), guides (2nd one), and
colour scales (6th one). Coming up with automatic names to categorize
these may not be easy, though.

> Try to prioritize the tiny set of commonly used functions over all
> the others. Create a learning curve.

This gets into the realm of territory of the difference between a
tutorial and a reference manual. A tutorial is designed to show how
something is to be used: the various ways to approach it and the idioms
of it. This is better as a vignette (or book). A reference manual is to
list the gritty details. It should be organized as well as possible, but
it serves a different purpose. Rd files are reference manuals.

> Give examples, with comments as to what the example is trying to do,
> all the parameters named, links to the graphical output... Like the

> old diamonds book�


>
> Link everything: Make it possible to get from qplot to other pages
> that use it, or expand on it, or supplant it, or give examples for

> it�

This is an interesting idea. Using a parser on the examples, it should
be possible to find every place a specific function is used. Maybe the
package that marks up the code can also include unique anchor links for
each line which can be linked to on a separate page, or in a section at
the bottom (examples of this/these functions on other pages). Extracting
appropriate context would not be easy, so maybe just a static line above
and below that with a link to the exact spot that function is used on
another page.

> Link to stack overflow, and crossvalidated, and to bloggers

> who�ve used the package and tried to give good specific examples.


> Have a search box which aggregates stackoverflow, r-help with tags

> for ggplot2�

Here, I'm not in agreement with you. This documentation, whatever it is,
should be self contained. Not that those are not good resources (and
maybe a single spot which lists other resources in general is itself a
fine thing).

> Negative comments This alphabetical list of 250+ functions will not
> help people trying to learn ggplot or solve a problem Probably

> doesn�t need to have a dedicate dbox of dependencies, etc. Maybe this


> whole page could be an appendix: an alphabetical listing and

> technical data? The top link of "ggplot2-package: ggplot2� takes you
> to this:


>
>
>
>
>
>
> I think at that point most people will give up (some will cry :-) )

I almost did ;)

But I would still argue that "learn ggplot" is the realm of a
tutorial/vignette/book, not the manual pages.

> Take this with a grain of salt, I�ve just been teaching in R with


> bright post-graduates highlights and it drives home repeatedly to me
> how they see R as almost purposively obscure and inconsistent during
> their learning (despite their also loving how R gets things done when
> it does work smoothly for them)
>

> There�s also a _very_ low bar set for help R in general, with error


> messages that help you solve the error frowned upon.

I don't think they are frowned on so much as no one wants to put in the
effort to do better. They'd rather work on something else.

> Compare to a well organized and helpful site, like
> http://www.statmethods.net
>
> I think he went backwards with the reworking, but it is still a great
> place to learn R from.
>
> My guess is that if you stick a markdown wiki into had.co.nz, then
> users can take care of all of this for you: many of us like to store
> knowledge publicly.

There is the Wiki on the GitHub site:
https://github.com/hadley/ggplot2/wiki
It's got some good resources in it, and it is publicly editable (well,
with a github login).

> best, t
>


--
Brian S. Diggs, PhD
Senior Research Associate, Department of Surgery
Oregon Health & Science University

Hadley Wickham

unread,
Mar 21, 2012, 9:37:38 AM3/21/12
to Timothy Bates, ggplot2
> So, first off: Thanks for working hard on this.

You're welcome.

> However, Just as R package “documentation” files, with their alphabetical
> listings of everything, (even data files!!) mixed up with internal helpers
> and key functions buried amongst that are almost no use to someone looking
> for help.

I partially agree. There are two types of people looking for help:
people who know what they want to do, they just needed some help on
how to do it; and people who are struggling to define the problem they
are trying to solve. Documentation helps the former, but not the
latter.

> Automated documentation, built out of the code and it’s parameters, is
> that it really leaves a lot to be desired for someone with a question in
> their mind (and that’s about everyone).
>
> What works really well is curated task-driven pages with clear explanatory
> text, well-chosen (and commented) examples, and a well organized contents
> page

Yes, I totally agree. However, the fact of the matter is that I don't
have time to write these, and no one else has yet stepped up to the
plate. The point of the new documentation system is to reduce the
amount of work to update the website, and in the longer term tie in to
a better workflow for improving the documentation. By the end of the
summer, I hope to have an in depth tutorial written on how to
contribute, and each documentation page will link back to the original
source on github so people can relatively easily contribute
improvements.

> My positive suggestions would be
>
> Try and add hints to the list generator so that, for instance, it can
> collect example data files together under a “Data files” heading.
> Even a set of basic heading hints, embedded in the source that this
> program could use to aggregate:
> # Core functions
> # Example Data
> # Sub functions
>   ## Aesthetics
>   ## Geoms
>  ...

This is something I will do.

> Try to prioritize the tiny set of commonly used functions over all the
> others. Create a learning curve.

This, I think, is the job of the book, not the documentation.

> Give examples, with comments as to what the example is trying to do,
> all the parameters named, links to the graphical output...
> Like the old diamonds book…

There are about 1,200 examples in the documentation - it's simply too
much work to describe every one extensively. My expectation is not
that people will be able to learn ggplot2 from scratch from the
documentation, but the documentation should help to how what's
possible.

> Link everything: Make it possible to get from qplot to other pages that
> use it, or expand on it, or supplant it, or give examples for it…

I have tried this in the past in another project, and it's not as
helpful as you might think. Links really need to be hand curated to
be useful - that's the job of the see also section.

> Link to stack overflow, and crossvalidated, and to bloggers who’ve used
> the package and tried to give good specific examples.

I think that's a great idea, but I don't have that list...

> Have a search box which aggregates stackoverflow, r-help with tags for
> ggplot2…

I think that's getting beyond the scope of the documentation.

> Negative comments
> This alphabetical list of  250+ functions will not help people trying to
> learn ggplot or solve a problem
> Probably doesn’t need to have a dedicate dbox of dependencies, etc. Maybe
> this whole page could be an appendix: an alphabetical listing and technical
> data?
> The top link of "ggplot2-package: ggplot2” takes you to this:
>
>
>
>
>

> I think at that point most people will give up (some will cry :-) )

Well, that's one of the documentation pages that needs the most work.
Patches are welcome.

> Take this with a grain of salt, I’ve just been teaching  in R with bright
> post-graduates highlights and it drives home repeatedly to me how they see R
> as almost purposively obscure and inconsistent during their learning
> (despite their also loving how R gets things done when it does work smoothly
> for them)

Yes, but you can't learn R from the documentation! You have to
internalise a few organising principles first, and the documentation
(which is very task driven) is not appropriate.

> There’s also a _very_ low bar set for help R in general, with error
> messages that help you solve the error frowned upon.

Writing good error messages is surprisingly hard - you need to be able
to build up an accurate mental model of what the user might have done
to trigger the error, and what is going to help them fix it.

> Compare to a well organized and helpful site, like
>  http://www.statmethods.net
>
> I think he went backwards with the reworking, but it is still a great
> place to learn R from.

But a bad place to look up the specifics of individual functions.

> My guess is that if you stick a markdown wiki into had.co.nz, then users
> can take care of all of this for you: many of us like to store knowledge
> publicly.

As Brian mentioned, there already is a markdown wiki. I personally
doubt that a wiki can ever make an excellent learning resource because
it lacks the single vision needed to make an effective, linear,
learning experience. The other problem with the wiki is maintenance -
it's easy to dump some code up on a wiki, but it's much hard to keep
it working for 5 years. One of the reasons that incorporating code
into ggplot2 takes longer than might be expected is that I have to be
able to make a long-term commitment to maintain it - and this means it
needs to be clear and well-written.

Bryan Hanson

unread,
Mar 21, 2012, 11:00:32 AM3/21/12
to Hadley Wickham, Timothy Bates, ggplot2
[Deleted most of the thread]

>
>> Negative comments
>> This alphabetical list of 250+ functions will not help people trying to
>> learn ggplot or solve a problem
>> Probably doesn’t need to have a dedicate dbox of dependencies, etc. Maybe
>> this whole page could be an appendix: an alphabetical listing and technical
>> data?
>> The top link of "ggplot2-package: ggplot2” takes you to this:
>>
>>
>>
>>
>>
>> I think at that point most people will give up (some will cry :-) )

IF one wanted to provide a little more guidance to users visiting with multiple purposes/hopes/skill levels, perhaps something between automatically generated documentation and the book, there could be a static piece that gives some hints. I have had some success with undergraduates by asking them to think about their data first, then leading them to appropriate types of plots to make. For instance (word choice here is not what I would use, nor is this a good structure to use):

Is your data univariate? Consider the following types of plots (geoms)...
Is your data bivariate? Consider...
Is your data continous or discrete?
Do you want to group by some factor/category?

One could construct a (somewhat) dichotomous key or other mechanism that leads to suggested ggplot examples, and introduces the total newbie to the ggplot conceptual vocabulary (geoms, faceting etc). I used to have a web site that did this using base and lattice graphics, before I learned ggplot. Never really fleshed out the web site so I took it down, especially since I now always use ggplot for day to day plotting, and certainly in all my courses (where they gobble it up).

Bryan


Jean-Olivier Irisson

unread,
Mar 21, 2012, 12:23:26 PM3/21/12
to Bryan Hanson, Hadley Wickham, Timothy Bates, ggplot2
On 2012-Mar-21, at 16:00 , Bryan Hanson wrote:
>
> IF one wanted to provide a little more guidance to users visiting with multiple purposes/hopes/skill levels, perhaps something between automatically generated documentation and the book, there could be a static piece that gives some hints. I have had some success with undergraduates by asking them to think about their data first, then leading them to appropriate types of plots to make. For instance (word choice here is not what I would use, nor is this a good structure to use):
>
> Is your data univariate? Consider the following types of plots (geoms)...
> Is your data bivariate? Consider...
> Is your data continous or discrete?
> Do you want to group by some factor/category?
>
> One could construct a (somewhat) dichotomous key or other mechanism that leads to suggested ggplot examples, and introduces the total newbie to the ggplot conceptual vocabulary (geoms, faceting etc). I used to have a web site that did this using base and lattice graphics, before I learned ggplot. Never really fleshed out the web site so I took it down, especially since I now always use ggplot for day to day plotting, and certainly in all my courses (where they gobble it up).

For this particular purpose, I found the visual index (the thumbnails) on the old site to be quite efficient with students: they would look at their data, decide the type of plot they want (ideally draw it on a piece of paper) and then look at the thumbnails to figure out what ggplot functions are needed to get to the visual result they want.
But Hadley already said the thumbnails are coming back so that's good! ;)

Reply all
Reply to author
Forward
0 new messages