Skip to content

Commit

Permalink
Improving documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@hadley
hadley committed Jan 3, 2008
1 parent 2bc2b85 commit aea9a35
Show file tree
Hide file tree
Showing 33 changed files with 228 additions and 81 deletions.
11 changes: 8 additions & 3 deletions NEWS
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
ggplot 0.5.7
----------------------------------------

New geoms and aesthetics
New geoms, scales and aesthetics

* new stat_step and geom_step to draw staircase plots (like plot(type="s"))
* new order aesthetic (currently only for lines/paths) that allows you to control the drawing order within a group
* stat_step and geom_step to draw staircase plots (like plot(type="s"))
* order aesthetic (currently only for lines/paths) allows you to control the drawing order within a group
* scale_manual makes it easier to let ggplot uses the exact colours/sizes/linetypes that you want


Improved options handling
Expand All @@ -16,11 +17,13 @@ These changes mean that you can modify plot options in the same way that you mod

Improved documentation

* many tweaks to the online documentation, particular including the actual code you need to run for each object!
* required aesthetics now listed in documentation
* geom_polygon now has a decent example
* numerous minor corrections suggested by Jörg Beyer
* separated plotting advice from details of plot construction (what vs how), thanks to Bert Gunter for this suggestion


Improved map projections (with coord_map)

* coord_map defaults to orientation = c(90, 0, mean(range(y))) - this ensures that multiple layers line up correctly, but means you will have to specify the orientation yourself for many projections
Expand All @@ -37,6 +40,7 @@ Bug fixes
* use LazyLoad: false instead of SaveData: true for better future compatability

* coord_cartesian: fixed bug that prevented you from overriding the default axis expansion
* coord_equal: now scales correctly if ratio < 1
* geom_abline: fix bug where slope was ignored
* geom_jitter now works correctly with groups and categorical values (was actually a bug in how scale_discrete deals with continuous values)
* geom_path: automatically switch between polylineGrob and segmentsGrob when drawing paths so that setting line type now works properly
Expand All @@ -46,6 +50,7 @@ Bug fixes
* quickplot added as an alias of qplot, to avoid confusion with qunif, etc
* scale_*: better error message if you add a scale without a matching aesthetic mapping in the plot
* scale_identity no longer converts everything to character
* scale_identity: grob argument renamed to guide
* stat_*: made all statistics more robust to errors
* stat_quantile: fixed bug when only drawing a single quantile
* stat_smooth: returns silently if <2 non-missing data points
Expand Down
118 changes: 75 additions & 43 deletions R/aaa-top-level.r
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ TopLevel <- proto(expr = {
details <- ""
advice <- ""
objname <- ""
desc_params <- list()
desc_params <- list("..." = "ignored ")
icon <- function(.) rectGrob(gp=gpar(fill="white", col=NA))

# Name of physical file to create, doesn't include directory
Expand All @@ -78,6 +78,10 @@ TopLevel <- proto(expr = {
ps("<a href='", .$html_path(), "' title='", .$desc, "'>", .$my_name(prefix=prefix), "</a>")
}

html_abbrev_link_self <- function(., prefix=TRUE) {
ps("<a href='", .$html_path(), "' title='", .$desc, "'>", .$objname, "</a>")
}

html_parent_link <- function(.) {
parent <- parent.env(.)
if (identical(parent, TopLevel)) return("")
Expand All @@ -102,7 +106,10 @@ TopLevel <- proto(expr = {
.$html_head(),
.$html_details(),
.$html_advice(),
.$html_defaults(),
.$html_aesthetics(),
.$html_outputs(),
.$html_parameters(),
# .$html_defaults(),
.$html_returns(),
.$html_seealso(),
.$html_examples(),
Expand All @@ -123,19 +130,19 @@ TopLevel <- proto(expr = {
# Page header -----------------------
html_head <- function(.) {
ps(
.$html_img(),
# "<p class='hierarchy'>", .$html_parent_link(), "</p>\n",
"<h1>", .$my_name(), "</h1>\n",
"<p class='desc'>", .$desc, "</p>\n"
"<h1>", .$html_img(), .$my_name(), "</h1>\n",
"<p class='call'>", .$call(), "</p>\n"
)
}

html_details <- function(.) {
ps(
"<h2>Details</h2>\n",
# "<h2>Details</h2>\n",
"<div class='details'>\n",
"<p>", .$desc, "</p>\n",
html_auto_link(.$details, .$my_name()),
"<p>See <a href='layer.html'>layer</a> and <a href='qplot.html'>qplot</a> for more information on creating a complete plot from multiple components.</p>\n",
"<p>This page describes ", .$my_name(), ", see <a href='layer.html'>layer</a> and <a href='qplot.html'>qplot</a> for how to create a complete plot from individual components.</p>\n",
"</div>\n"
)
}
Expand All @@ -148,28 +155,15 @@ TopLevel <- proto(expr = {
html_auto_link(.$advice, .$my_name()),
"</div>\n"
)
}
}


# Defaults -----------------------
html_defaults <- function(.) {
ps(
.$html_defaults_aesthetics(),
.$html_defaults_outputs(),
.$html_defaults_parameters(),
.$html_defaults_stat(),
.$html_defaults_geom(),
.$html_defaults_position()
)
}

html_scales <- function(., aesthetic) {
scales <- Scale$find(aesthetic, only.documented = TRUE)
if (length(scales) == 0) return()
ps(lapply(scales, function(x) x$html_link_self(prefix=FALSE)), collapse=", ")
}

html_defaults_aesthetics <- function(.) {
html_aesthetics <- function(.) {
if (!exists("default_aes", .)) return("")

req <- rep("<strong>required</strong>", length(.$required_aes))
Expand All @@ -189,7 +183,7 @@ TopLevel <- proto(expr = {

ps(
"<h2>Aesthetics</h2>\n",
html_auto_link(ps("<p>The following aesthetics can be used with ", .$my_name(), ". They are listed along with their default value. All geoms and scales can also use the group aesthetic. Read how this important aesthetic works in scale_group. Typically, you will associate an aesthetic with a variable in your data set. To do this, you use the aes function: <code>", .$my_name(), "(aes(x = var))</code>. Scales control the details of the mapping between data and aesthetic properties; after each aesthetic are listed scales that can be used with that aesthetic. The scale documentation will also provide references to help you interpret the default values.</p>\n<p>Instead of mapping an aesthetic to a variable in your dataset, you can also set it to a fixed value. See the parameters section for details.</p>\n"), .$my_name()),
html_auto_link(ps("<p>The following aesthetics can be used with ", .$my_name(), ". Aesthetics are mapped to variables in the data with the aes function: <code>", .$my_name(), "(aes(x = var))</code>. Scales control how the variable is mapped to the aesthetic and are listed after each aesthetic.</p>\n"), .$my_name()),
"<ul>\n",
ps(
" <li>",
Expand All @@ -200,7 +194,7 @@ TopLevel <- proto(expr = {
)
}

html_defaults_outputs <- function(.) {
html_outputs <- function(.) {
if (!exists("desc_outputs", .)) return("")

ps(
Expand All @@ -211,48 +205,66 @@ TopLevel <- proto(expr = {
"</ul>\n"
)
}

html_defaults <- function(.) {
ps(
"<h2>Defaults</h2>\n",
"<ul>\n",
.$html_defaults_stat(),
.$html_defaults_geom(),
.$html_defaults_position(),
"</ul>\n"
)
}


html_defaults_stat <- function(.) {
if (!exists("default_stat", .)) return("")

ps(
"<h2>Default statistic</h2>\n",
"<p>", .$default_stat()$html_link_self(), ". Override with the <code>stat</code> argument: <code>", .$my_name(), "(stat=\"identity\")</code></p>\n"
"<li>", .$default_stat()$html_link_self(), ". Override with the <code>stat</code> argument: <code>", .$my_name(), "(stat=\"identity\")</code></li>\n"
)
}

html_defaults_geom <- function(.) {
if (!exists("default_geom", .)) return("")

ps(
"<h2>Default geom</h2>\n",
"<p>", .$default_geom()$html_link_self(), ". Override with the <code>geom</code> argument: <code>", .$my_name(), "(geom=\"point\")</code>.</p>\n"
"<li>", .$default_geom()$html_link_self(), ". Override with the <code>geom</code> argument: <code>", .$my_name(), "(geom=\"point\")</code>.</li>\n"
)
}

html_defaults_position <- function(.) {
if (!exists("default_pos", .)) return("")

ps(
"<h2>Default position</h2>\n",
"<p>", .$default_pos()$html_link_self(), ". Override with the <code>position</code> argument: <code>", .$my_name(), "(position=\"jitter\")</code>.</p>\n"
"<li>", .$default_pos()$html_link_self(), ". Override with the <code>position</code> argument: <code>", .$my_name(), "(position=\"jitter\")</code>.</li>\n"
)
}

html_defaults_parameters <- function(.) {
if (!exists("parameters", .)) return("")

params <- function(.) {
param <- .$parameters()
if (length(param) == 0) return("")

desc <- c(.$desc_params, .$.desc_aes)
if (length(param) == 0) return()

if(!exists("required_aes", .)) return(param)

aesthetics <- c(.$required_aes, names(.$default_aes()))
param <- param[setdiff(names(param), aesthetics)]
}


html_parameters <- function(.) {
if (!exists("parameters", .)) return("")
param <- .$params()

ps(
"<h2>Parameters</h2>\n",
"<p>When an aesthetic is used as an a parameter, like <code>", .$my_name(), "(", names(param)[1], " = 3)</code>, it will override mappings from data.</p>\n",
"<ul>\n",
ps("<li><code>", names(param), "</code>, ", desc[names(param)], "</li>\n"),
"</ul>\n"
"<p>Parameters control the appearance of the ", .$class(), ". In addition to the parameters listed below (if any), any aesthetic can be used as a parameter, in which case it will override any aesthetic mapping.</p>\n",
if(length(param) > 0) ps(
"<ul>\n",
ps("<li><code>", names(param), "</code>: ", defaults(.$desc_params, .desc_param)[names(param)], "</li>\n"),
"</ul>\n"
)
)
}

Expand Down Expand Up @@ -283,13 +295,13 @@ TopLevel <- proto(expr = {
ps(.$my_name(), ".png")
}

html_img_link <- function(., align="right") {
html_img_link <- function(., align="left") {
ps("<a href='", .$html_path(), "'>", .$html_img(align), "</a>")
}

html_img <- function(., align="right") {
html_img <- function(., align="left") {
ps(
"<img src='", .$html_img_path(), "' width='50' height='50' alt='' align='", align, "' class='icon' />\n"
"<img src='", .$html_img_path(), "' width='50' height='50' alt='' class='icon' />\n"
)
}

Expand Down Expand Up @@ -324,6 +336,26 @@ TopLevel <- proto(expr = {
}


call <- function(.) {
ps(
.$my_name(), "(",
ps(
"mapping&nbsp;=&nbsp;aes(...)",
"data&nbsp;=&nbsp;NULL",
if(exists("default_stat", .))
ps("stat&nbsp;=&nbsp;'", .$default_stat()$html_abbrev_link_self(), "'"),
if(exists("default_geom", .))
ps("geom&nbsp;=&nbsp;'", .$default_geom()$html_abbrev_link_self(), "'"),
if(exists("default_pos", .))
ps("position&nbsp;=&nbsp;'", .$default_pos()$html_abbrev_link_self(), "'"),
plist(.$params()),
"...",
sep = ", "
),
")"
)
}

})

print.proto <- function(x, ...) x$pprint(...)
Expand Down
15 changes: 15 additions & 0 deletions R/coordinates-.r
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,4 +46,19 @@ Coord <- proto(TopLevel, expr={
)
}

call <- function(.) {
ps(
.$my_name(), "(",
ps(
plist(.$parameters()), ", ..."
),
")", collapse="\n<br />"
)
}

parameters <- function(.) {
params <- formals(get("new", .))
params[setdiff(names(params), c("."))]
}

})
24 changes: 11 additions & 13 deletions R/coordinates-cartesian-equal.r
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,19 @@
CoordEqual <- proto(CoordCartesian, {

new <- function(., ratio=1) {
.$proto(ratio=ratio)
list(.$proto(ratio=ratio), opts(aspect.ratio = ratio))
}

frange <- function(.) {
xlim <- .$x()$frange()
ylim <- .$y()$frange()

widest <- max(diff(xlim), diff(ylim))
xratio <- if (.$ratio < 1) 1 / .$ratio else 1
yratio <- if (.$ratio < 1) 1 else .$ratio

xlim <- mean(xlim) + c(-1, 1) * widest * 0.5
ylim <- mean(ylim) + .$ratio * c(-1, 1) * widest * 0.5
xlim <- mean(xlim) + xratio * c(-1, 1) * widest * 0.5
ylim <- mean(ylim) + yratio * c(-1, 1) * widest * 0.5

expand <- .$expand()
list(
Expand Down Expand Up @@ -44,23 +46,19 @@ CoordEqual <- proto(CoordCartesian, {
desc <- "Equal scale cartesian coordinates"
icon <- function(.) textGrob("=", gp=gpar(cex=3))

details <- "<p>An equal scale coordinate system plays a similar role to ?eqscplot in MASS, but it works for all types of graphics, not just scatterplots.</p>\n<p>This coordinate system has one parameter, <code>ratio</code>, which specifies the ratio between the x and y scales. You will usually need to set the aspect ratio as well - see the example for details.</p>\n"
details <- "<p>An equal scale coordinate system plays a similar role to ?eqscplot in MASS, but it works for all types of graphics, not just scatterplots.</p>\n<p>This coordinate system has one parameter, <code>ratio</code>, which specifies the ratio between the x and y scales. By default, the aspect.ratio of the plot will also be set to this value.</p>\n"

examples <- function(.) {
# coord_equal ensures that the ranges of axes are equal to the
# specified ratio (1 by default, indicating equal ranges).
# You must also ensure the physical lengths of the axes are
# equal to the specified ratio, by setting the aspect.ratio property
# of the plot
# equal to the specified ratio, by setting the aspect.ratio option

(p <- qplot(mpg, wt, data=mtcars) + coord_equal(ratio=1))
p$aspect.ratio <- 1; p

(p <- qplot(mpg, wt, data=mtcars) + coord_equal(ratio=1/5))
p$aspect.ratio <- 1; p
p$aspect.ratio <- 1/5; p
qplot(mpg, wt, data=mtcars) + coord_equal(ratio=1)
qplot(mpg, wt, data=mtcars) + coord_equal(ratio=5)
qplot(mpg, wt, data=mtcars) + coord_equal(ratio=1/5)

# Resize the plot, and observe that the specified aspect ratio is
# Resize the plot, and you'll see that the specified aspect ratio is
# mantained
}

Expand Down
6 changes: 6 additions & 0 deletions R/coordinates-map.r
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,12 @@ CoordMap <- proto(CoordCartesian, {
linesGrob(nz$x, nz$y, default.units="npc")
}

desc_params <- list(
"projection" = "projection to use, see ?mapproject for complete list",
"..." = "other arguments passed on to mapproject",
"orientation" = "orientation, which defaults to c(90, 0, mean(range(x))). This is not optimal for many projections, so you will have to supply your own."
)

details <- "<p>This coordinate system provides the full range of map projections available in the mapproject package.</p>\n\n<p>This is still experimental, and if you have any advice to offer regarding a better (or more correct) way to do this, please let me know</p>\n"

examples <- function(.) {
Expand Down
15 changes: 14 additions & 1 deletion R/doc.r
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,19 @@
"width" = "width of geom"
)

.desc_param <- list(
"name" = "name of scale to appear in legend or on axis",
"limits" = "numeric vector of length 2, giving the extent of the scale",
"trans" = "a transformer to use",
"..." = "ignored",
"to" = "numeric vector of length 2, giving minimum and maximum after transformation",
"guide" = "guide type for legend, one of 'point', 'tile', 'line'",
"breaks" = "numeric vector indicating where breaks should lie",
"labels" = "character vector giving labels associated with breaks",
"expand" = "numeric vector of length 2, giving multiplicative and additive expansion factors"
)


# Generate html for index page for documentation website.
#
# @keyword internal
Expand Down Expand Up @@ -69,8 +82,8 @@ html_index_create <- function(path="web/") {
all_html_pages_create <- function(path="web/") {
options(warn = 1)
system("rm web/graphics/*")
html_index_create(path)
html_template_create_all()
html_index_create(path)
Geom$all_html_pages_create()
Stat$all_html_pages_create()
Scale$all_html_pages_create()
Expand Down
Loading

0 comments on commit aea9a35

Please sign in to comment.