Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Improved aesthetic documentation #740

Closed
wants to merge 16 commits into from

4 participants

@BrianDiggs

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
@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
@wch
Collaborator

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
@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
@BrianDiggs

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

What is the status of this? Just wondering.

@BrianDiggs

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
BrianDiggs added some commits
@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
@hadley
Owner

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 hadley closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Nov 6, 2012
  1. @BrianDiggs

    Fix errors in shape documentation

    BrianDiggs authored
    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.
  2. @BrianDiggs

    Improved graphic for shapes catalog

    BrianDiggs authored
    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.
Commits on Nov 8, 2012
  1. @BrianDiggs
Commits on Nov 19, 2012
  1. @BrianDiggs
  2. @BrianDiggs
Commits on Dec 14, 2012
  1. @BrianDiggs
  2. @BrianDiggs

    Change to aesthetic prefix; split into more topics

    BrianDiggs authored
    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.
Commits on Jan 8, 2013
  1. @BrianDiggs

    Rewrite of helper functions for dynamic Rd files

    BrianDiggs authored
    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.
  2. @BrianDiggs

    Fix bug in aesthetics shown by GeomCustomAnn

    BrianDiggs authored
    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.
Commits on Jan 14, 2013
  1. @BrianDiggs

    Fix bug in aesthetics shown by GeomBoxplot and StatBoxplot

    BrianDiggs authored
    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.
  2. @BrianDiggs

    Resurrect TopLevel$find_all()

    BrianDiggs authored
    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.
  3. @BrianDiggs

    Fix Rd output for aesthetic with no default

    BrianDiggs authored
    Propogated change in aesthetics() where the default is
    a character to rd_aesthetics so that the checks are against
    a character vector.
  4. @BrianDiggs

    Infrastructure to link to geoms that use an aesthetic

    BrianDiggs authored
    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.
Commits on Apr 11, 2013
  1. @BrianDiggs

    Added some example plots for linetype.

    BrianDiggs authored
    Named/numbered linetypes and default palette.
Commits on Jun 19, 2013
  1. @BrianDiggs

    Merge remote-tracking branch 'origin/doc/shape' into doc/aesthetics

    BrianDiggs authored
    Conflicts:
    	R/aes-linetype-size-shape.r
    	man/aes_linetype_size_shape.Rd
    
    Better representation of all shapes.
  2. @BrianDiggs

    Merge branch 'doc/linetype' into doc/aesthetics

    BrianDiggs authored
    Conflicts:
    	R/aes-linetype-size-shape.r
    	man/aes_linetype_size_shape.Rd
    
    Better linetype palette examples.
Something went wrong with that request. Please try again.