Improved aesthetic documentation #740
Conversation
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.
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.
|
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. |
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.
|
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:
|
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.
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.
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.
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.
Propogated change in aesthetics() where the default is a character to rd_aesthetics so that the checks are against a character vector.
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.
Named/numbered linetypes and default palette.
|
What is the status of this? Just wondering. |
|
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. |
|
On Fri, 7 Jun 2013, Brian Diggs wrote:
Thanks for the clarification, Brian. |
Conflicts: R/aes-linetype-size-shape.r man/aes_linetype_size_shape.Rd Better representation of all shapes.
Conflicts: R/aes-linetype-size-shape.r man/aes_linetype_size_shape.Rd Better linetype palette examples.
|
Could you please rebase/merge against master, re-document with the development version of roxygen2 ( This looks great! |
|
This old issue has been automatically locked. If you believe you have found a related problem, please file a new issue (with reprex) and link to this issue. https://reprex.tidyverse.org/ |
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
aesfamily 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,
hjustandvjust,colourandfill) can be kept together, butshapeandlinetypedon't belong together. For the cases with combined documentation, there should be aliases to each separately (aesthetic-hjust, for example).Document all the aesthetics
Taking out those already documented, that leaves
hjust,angle,label,lower,middle,radius,sample,upper,vjust,weight,width, andz(and, according togeom_text,family,fontfaceandlineheight; are there others?)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.