Improved aesthetic documentation #740

Closed
wants to merge 16 commits into
from

Conversation

Projects
None yet
4 participants
Contributor

BrianDiggs commented Dec 14, 2012

This wishlist item is inspired by a recent issue (Issue #726), an email on the help list (https://groups.google.com/d/topic/ggplot2/4rVJ1xWsLeQ/discussion), and some previous work I have done (Issue #717).

I think the documentation of aesthetics themselves needs to be overhauled/improved and I wanted to create this issue to put down some of my ideas. This has always been a thin part of the documentation. The ggplot2 book has it as Appendix B which is only 3 pages. JakeRuss added documentation of linetype, size, shape, colour, fill, and alpha in June 2011. Documentation for position, order, and group was added in January 2012. But is is jumbled and not well linked.

Here are my suggestions:

  • Rename the documents/topics to start with "aesthetic" rather than "aes" to distinguish them from the aes family of functions (aes, aes_string, aes_all, aes_auto).

  • Divide the documentation into separate topics for each aesthetic. Very closely related concepts (such as the position aesthetics, hjust and vjust, colour and fill) can be kept together, but shape and linetype don't belong together. For the cases with combined documentation, there should be aliases to each separately (aesthetic-hjust, for example).

  • Document all the aesthetics

    > unique(names(aes_all(ggplot2:::.all_aesthetics)))
    [1] "hjust"      "alpha"      "angle"      "fill"       "size"      
    [6] "colour"     "group"      "label"      "linetype"   "lower"     
    [11] "ymax"       "middle"     "ymin"       "order"      "shape"     
    [16] "radius"     "sample"     "upper"      "vjust"      "weight"    
    [21] "width"      "x"          "xend"       "xmax"       "xmin"      
    [26] "xintercept" "y"          "yend"       "yintercept" "z"         

Taking out those already documented, that leaves hjust, angle, label, lower, middle, radius, sample, upper, vjust, weight, width, and z (and, according to geom_text, family, fontface and lineheight; are there others?)

  • In the list of aesthetics in each geom, add links for each to its corresponding aesthetic page (the consistent naming and/or aliasing based on the aesthetic should make this template-able)

Ultimately, this will address the problem of "what does that aesthetic control?" or "why would I want to set that?" or the reverse questions of "what aesthetic controls such-and-such aspect of the plot?"

If anyone else thinks this could be useful, I'll make a branch on my clone of the repository and attach it as a pull request to which people can comment an contribute.

BrianDiggs added some commits Nov 6, 2012

@BrianDiggs BrianDiggs Fix errors in shape documentation
There are 26, not 25 shapes (shape 0 was not shown). Only symbols 21
through 25 have a fill option; 19 and 20 do not.
bff7613
@BrianDiggs BrianDiggs Improved graphic for shapes catalog
Revamped the graphic for showing the different shapes (0-25) utilizing
facet_wrap instead of staggering along the axes. Also using theme to
get rid of unnecessary elements, but retainging the grid lines that show
exactly where the points are centered. Changed the fill from black to
lightblue and made the symbols bigger.
f558ee0
@BrianDiggs BrianDiggs Move scale_shape_identity into s e5bdf74
@BrianDiggs BrianDiggs Added display of default linetypes 064c532
@BrianDiggs BrianDiggs Commit corresponding Rd file 4c10ad7
Collaborator

wch commented Dec 13, 2012

This sounds like a good idea to me. I believe that the aesthetics in the help page are automatically generated, so that's something to keep in mind.

BrianDiggs added some commits Dec 14, 2012

@BrianDiggs BrianDiggs Pull all aesthetic documentation into a single file 57ada20
@BrianDiggs BrianDiggs Change to aesthetic prefix; split into more topics
For documentation, change the aes prefix to aesthetic to
differentiate between the aes functions and the descriptions
of aesthetics. This results in renamed man files.

alpha split from colour and fill; linetype, shape, and size
split apart.

Standardized titles

Gave them all @family aesthetics to make automatic
cross-referencing.

Fixed cross-references in aes function documentation.
b12fd9a
Contributor

BrianDiggs commented Dec 14, 2012

I've started the pull request, but the changes are not done yet so it is not ready to pull. I am accepting pull requests onto my doc/aesthetics branch. Things still to do:

  • Add rest of aesthetics
  • Make sure each aesthetic has examples with
    • setting it
    • using it as a discrete mapped scale (if appropriate)
    • using it as a continuous mapped scale (if appropriate)
    • using a manual scale
    • using an identity scale
  • Something which demonstrates the palette, if appropriate
  • Links/references to the underlying grid/par concept
  • Update code which generates the aesthetic section of the documentation to include links (and defaults?)

BrianDiggs added some commits Jan 8, 2013

@BrianDiggs BrianDiggs Rewrite of helper functions for dynamic Rd files
Removed geom_aesthetics and stat_aesthetics since they were
not used anywhere else in the codebase

Refactored aesthetics and rd_aesthetics so that aesthetics only
collects the information about a given geom or stat's aesthetics
and rd_aesthetics is responsible for all the formatting of this
into Rd format. Parameters of the two functions are the same, but
aesthetics now returns a data.frame rather than a character vector.

rd_aesthetics now also outputs the default values for aesthetics.

roxygen-like documentation added for aesthetics function (same format
as roxygen documentation, but with just comment prefix rather than
roxygen prefix) as a type of internal documentation.
4dacb6a
@BrianDiggs BrianDiggs Fix bug in aesthetics shown by GeomCustomAnn
When a default was -Inf, it would come across as a language
object, not a numeric object. This caused problems as a
component of a list as a column of a data.frame. Running eval
on each element removes the call and makes -Inf numeric.
18bac81
@BrianDiggs BrianDiggs Fix bug in aesthetics shown by GeomBoxplot and StatBoxplot
When a default was a derived variable (..count..), eval
could not be called on it, so only call eval on those that
are actually calls.
551fc5a
@BrianDiggs BrianDiggs Resurrect TopLevel$find_all()
This function was not used in any (non-commented out) code.
Now works again. only.documented argument dropped because
the objects do not contain their own documentation anymore.
c2e51b1
@BrianDiggs BrianDiggs Fix Rd output for aesthetic with no default
Propogated change in aesthetics() where the default is
a character to rd_aesthetics so that the checks are against
a character vector.
d1ae0f6
@BrianDiggs BrianDiggs Infrastructure to link to geoms that use an aesthetic
geom_with_aesthetic and rd_geom_with_aesthetic in
utilities-help.r and a new Geoms section in the aesthetics
roxygen file which includes build-time lookup of which
geoms recognize a given aesthetic, creating a list and link
to them. re-roxygenized.
7924848
@BrianDiggs BrianDiggs Added some example plots for linetype.
Named/numbered linetypes and default palette.
e42b748

fmitha commented Jun 7, 2013

What is the status of this? Just wondering.

Contributor

BrianDiggs commented Jun 7, 2013

I haven't really looked at this seriously in several months. The core infrastructure is there. What is needed is more examples and descriptions. I'm happy to review pull requests to this branch that add examples. When I notice good ones on the mailing list or elsewhere, I try to add them, but I have not had time to sit down and systematically write examples like I would like to. It's something I'd like to do, but not something I have a time table to get done.

fmitha commented Jun 7, 2013

On Fri, 7 Jun 2013, Brian Diggs wrote:

I haven't really looked at this seriously in several months. The core
infrastructure is there. What is needed is more examples and
descriptions. I'm happy to review pull requests to this branch that add
examples. When I notice good ones on the mailing list or elsewhere, I
try to add them, but I have not had time to sit down and systematically
write examples like I would like to. It's something I'd like to do, but
not something I have a time table to get done.

Thanks for the clarification, Brian.

BrianDiggs added some commits Jun 19, 2013

@BrianDiggs BrianDiggs Merge remote-tracking branch 'origin/doc/shape' into doc/aesthetics
Conflicts:
	R/aes-linetype-size-shape.r
	man/aes_linetype_size_shape.Rd

Better representation of all shapes.
f5006fb
@BrianDiggs BrianDiggs Merge branch 'doc/linetype' into doc/aesthetics
Conflicts:
	R/aes-linetype-size-shape.r
	man/aes_linetype_size_shape.Rd

Better linetype palette examples.
c29f0fb
Owner

hadley commented Feb 24, 2014

Could you please rebase/merge against master, re-document with the development version of roxygen2 (install_github("klutometis/roxygen) and resubmit?

This looks great!

hadley closed this Feb 24, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment