Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 166 lines (160 sloc) 6.837 kB
953fe47 @hadley Convert all documentation to roxygen
authored
1 #' Points, as for a scatterplot
1244716 @hadley Trim whitespace
authored
2 #'
953fe47 @hadley Convert all documentation to roxygen
authored
3 #' The point geom is used to create scatterplots.
4 #'
5 #' The scatterplot is useful for displaying the relationship between two
1244716 @hadley Trim whitespace
authored
6 #' continuous variables, although it can also be used with one continuous
953fe47 @hadley Convert all documentation to roxygen
authored
7 #' and one categorical variable, or two categorical variables. See
8 #' \code{\link{geom_jitter}} for possibilities.
9 #'
1244716 @hadley Trim whitespace
authored
10 #' The \emph{bubblechart} is a scatterplot with a third variable mapped to
953fe47 @hadley Convert all documentation to roxygen
authored
11 #' the size of points. There are no special names for scatterplots where
12 #' another variable is mapped to point shape or colour, however.
13 #'
14 #' The biggest potential problem with a scatterplot is overplotting: whenever
15 #' you have more than a few points, points may be plotted on top of one
1244716 @hadley Trim whitespace
authored
16 #' another. This can severely distort the visual appearance of the plot.
953fe47 @hadley Convert all documentation to roxygen
authored
17 #' There is no one solution to this problem, but there are some techniques
18 #' that can help. You can add additional information with
1244716 @hadley Trim whitespace
authored
19 #' \code{\link{stat_smooth}}, \code{\link{stat_quantile}} or
953fe47 @hadley Convert all documentation to roxygen
authored
20 #' \code{\link{stat_density2d}}. If you have few unique x values,
21 #' \code{\link{geom_boxplot}} may also be useful. Alternatively, you can
22 #' summarise the number of points at each location and display that in some
23 #' way, using \code{\link{stat_sum}}. Another technique is to use transparent
1e28092 @bbolker various doc/comment typos
bbolker authored
24 #' points, e.g. \code{geom_point(alpha = 0.05)}.
953fe47 @hadley Convert all documentation to roxygen
authored
25 #'
1244716 @hadley Trim whitespace
authored
26 #' @section Aesthetics:
d7971cb @hadley Fix document aesthetics.
authored
27 #' \Sexpr[results=rd,stage=build]{ggplot2:::rd_aesthetics("geom", "point")}
9781e4a @hadley geom_point doc improvements
authored
28 #'
953fe47 @hadley Convert all documentation to roxygen
authored
29 #' @seealso \code{\link{scale_size}} to see scale area of points, instead of
30 #' radius, \code{\link{geom_jitter}} to jitter points to reduce (mild)
31 #' overplotting
9781e4a @hadley geom_point doc improvements
authored
32 #' @param mapping The aesthetic mapping, usually constructed with
33 #' \code{\link{aes}} or \code{\link{aes_string}}. Only needs to be set
34 #' at the layer level if you are overriding the plot defaults.
3c39ed7 @hadley Improve layer() documentation
authored
35 #' @param data A data frame. If specified, overrides the default data frame
36 #' defined at the top level of the plot.
1e28092 @bbolker various doc/comment typos
bbolker authored
37 #' @param position Position adjustment, either as a string, or the result of
3c39ed7 @hadley Improve layer() documentation
authored
38 #' a call to a position adjustment function.
9781e4a @hadley geom_point doc improvements
authored
39 #' @param stat The statistical transformation to use on the data for this
3c39ed7 @hadley Improve layer() documentation
authored
40 #' layer, as a string.
9781e4a @hadley geom_point doc improvements
authored
41 #' @param na.rm If \code{FALSE} (the default), removes missing values with
42 #' a warning. If \code{TRUE} silently removes missing values.
a273159 @hadley Rename show_guide to show.legend
authored
43 #' @param show.legend logical. Should this layer be included in the legends?
d530de7 @hadley Merge branch 'docs' of https://github.com/joranE/ggplot2 into joranE-…
authored
44 #' \code{NA}, the default, includes if any aesthetics are mapped.
45 #' \code{FALSE} never includes, and \code{TRUE} always includes.
6aded8c @wch Make sure all geom_xx functions have show_guide and inherit.aes argum…
wch authored
46 #' @param inherit.aes If \code{FALSE}, overrides the default aesthetics,
47 #' rather than combining with them. This is most useful for helper functions
48 #' that define both data and aesthetics and shouldn't inherit behaviour from
49 #' the default plot specification, e.g. \code{\link{borders}}.
3c39ed7 @hadley Improve layer() documentation
authored
50 #' @param ... other arguments passed on to \code{\link{layer}}. There are
51 #' three types of arguments you can use here:
52 #'
53 #' \itemize{
54 #' \item Aesthetics: to set an aesthetic to a fixed value, like
55 #' \code{color = "red"} or \code{size = 3}.
56 #' \item Other arguments to the layer, for example you override the
57 #' default \code{stat} associated with the layer.
58 #' \item Other arguments passed on to the stat.
59 #' }
11a65bd add docs for show_guide
Joran Elias authored
60 #' @inheritParams layer
953fe47 @hadley Convert all documentation to roxygen
authored
61 #' @export
62 #' @examples
63 #' p <- ggplot(mtcars, aes(wt, mpg))
64 #' p + geom_point()
1244716 @hadley Trim whitespace
authored
65 #'
953fe47 @hadley Convert all documentation to roxygen
authored
66 #' # Add aesthetic mappings
67 #' p + geom_point(aes(colour = factor(cyl)))
68 #' p + geom_point(aes(shape = factor(cyl)))
69 #' p + geom_point(aes(size = qsec))
1244716 @hadley Trim whitespace
authored
70 #'
953fe47 @hadley Convert all documentation to roxygen
authored
71 #' # Change scales
72 #' p + geom_point(aes(colour = cyl)) + scale_colour_gradient(low = "blue")
73 #' p + geom_point(aes(shape = factor(cyl))) + scale_shape(solid = FALSE)
1244716 @hadley Trim whitespace
authored
74 #'
953fe47 @hadley Convert all documentation to roxygen
authored
75 #' # Set aesthetics to fixed value
bbfc5be @hrbrmstr finished removing qplot from remaining functions except for the expli…
hrbrmstr authored
76 #' ggplot(mtcars, aes(wt, mpg)) + geom_point(colour = "red", size = 3)
1244716 @hadley Trim whitespace
authored
77 #'
7239047 @hadley geom_point doc tweaks
authored
78 #' \donttest{
953fe47 @hadley Convert all documentation to roxygen
authored
79 #' # Varying alpha is useful for large datasets
80 #' d <- ggplot(diamonds, aes(carat, price))
81 #' d + geom_point(alpha = 1/10)
82 #' d + geom_point(alpha = 1/20)
83 #' d + geom_point(alpha = 1/100)
7239047 @hadley geom_point doc tweaks
authored
84 #' }
1244716 @hadley Trim whitespace
authored
85 #'
2b1387f @hadley Tweak stroke example
authored
86 #' # For shapes that have a border (like 21), you can colour the inside and
87 #' # outside separately. Use the stroke aesthetic to modify the width of the
88 #' # border
89 #' ggplot(mtcars, aes(wt, mpg)) +
7239047 @hadley geom_point doc tweaks
authored
90 #' geom_point(shape = 21, colour = "black", fill = "white", size = 5, stroke = 5)
5380ecd @SeySayux Add stroke option to geom_point.
SeySayux authored
91 #'
98c18d1 @hadley Tweak geom_point examples
authored
92 #' \donttest{
953fe47 @hadley Convert all documentation to roxygen
authored
93 #' # You can create interesting shapes by layering multiple points of
94 #' # different sizes
95 #' p <- ggplot(mtcars, aes(mpg, wt))
1244716 @hadley Trim whitespace
authored
96 #' p + geom_point(colour="grey50", size = 4) + geom_point(aes(colour = cyl))
97 #' p + aes(shape = factor(cyl)) +
953fe47 @hadley Convert all documentation to roxygen
authored
98 #' geom_point(aes(colour = factor(cyl)), size = 4) +
7239047 @hadley geom_point doc tweaks
authored
99 #' geom_point(colour = "grey90", size = 1.5)
100 #' p + geom_point(colour = "black", size = 4.5) +
101 #' geom_point(colour = "pink", size = 4) +
1244716 @hadley Trim whitespace
authored
102 #' geom_point(aes(shape = factor(cyl)))
103 #'
953fe47 @hadley Convert all documentation to roxygen
authored
104 #' # These extra layers don't usually appear in the legend, but we can
105 #' # force their inclusion
a273159 @hadley Rename show_guide to show.legend
authored
106 #' p + geom_point(colour = "black", size = 4.5, show.legend = TRUE) +
107 #' geom_point(colour = "pink", size = 4, show.legend = TRUE) +
1244716 @hadley Trim whitespace
authored
108 #' geom_point(aes(shape = factor(cyl)))
109 #'
953fe47 @hadley Convert all documentation to roxygen
authored
110 #' # geom_point warns when missing values have been dropped from the data set
111 #' # and not plotted, you can turn this off by setting na.rm = TRUE
112 #' mtcars2 <- transform(mtcars, mpg = ifelse(runif(32) < 0.2, NA, mpg))
bbfc5be @hrbrmstr finished removing qplot from remaining functions except for the expli…
hrbrmstr authored
113 #' ggplot(mtcars2, aes(wt, mpg)) + geom_point()
114 #' ggplot(mtcars2, aes(wt, mpg)) + geom_point(na.rm = TRUE)
c5b872e @hadley Don't test any example that takes over 5 seconds
authored
115 #' }
ec3cd49 @hadley Processing RStudio diagnostics
authored
116 geom_point <- function(mapping = NULL, data = NULL, stat = "identity",
117 position = "identity", na.rm = FALSE,
118 show.legend = NA, inherit.aes = TRUE, ...) {
138ab04 @wch Change Layer$new() calls to layer(). Closes #1180
wch authored
119 layer(
b24e2cb @wch Convert geom_point to R6
wch authored
120 data = data,
121 mapping = mapping,
122 stat = stat,
5c0a08f @wch Remove R6 suffix from Geom*R6 and Stat*R6
wch authored
123 geom = GeomPoint,
b24e2cb @wch Convert geom_point to R6
wch authored
124 position = position,
a273159 @hadley Rename show_guide to show.legend
authored
125 show.legend = show.legend,
6aded8c @wch Make sure all geom_xx functions have show_guide and inherit.aes argum…
wch authored
126 inherit.aes = inherit.aes,
42537b2 @wch Separate geom_params, stat_params, and other params
wch authored
127 geom_params = list(na.rm = na.rm),
128 params = list(...)
b24e2cb @wch Convert geom_point to R6
wch authored
129 )
130 }
131
4c3d5e2 @wch Document and export Geoms, Stats, and Positions. Closes #1184
wch authored
132 #' @rdname ggplot2-ggproto
133 #' @format NULL
134 #' @usage NULL
135 #' @export
ee96a37 @wch Rename proto2 to ggproto
wch authored
136 GeomPoint <- ggproto("GeomPoint", Geom,
4a89836 @hadley Simplify proto2 object creation
authored
137 draw_groups = function(self, ...) self$draw(...),
b24e2cb @wch Convert geom_point to R6
wch authored
138
4a89836 @hadley Simplify proto2 object creation
authored
139 draw = function(self, data, scales, coordinates, na.rm = FALSE, ...) {
b52dc4b @hadley Tweak geom_point style
authored
140 data <- remove_missing(data, na.rm, c("x", "y", "size", "shape"),
141 name = "geom_point")
4a89836 @hadley Simplify proto2 object creation
authored
142 if (empty(data)) return(zeroGrob())
b24e2cb @wch Convert geom_point to R6
wch authored
143
1487e01 @wch Convert coords to ggproto
wch authored
144 coords <- coordinates$transform(data, scales)
ef1cd13 @hadley Eliminate my_name() method
authored
145 ggname("geom_point",
b52dc4b @hadley Tweak geom_point style
authored
146 pointsGrob(
147 coords$x, coords$y,
148 pch = coords$shape,
149 gp = gpar(
150 col = alpha(coords$colour, coords$alpha),
151 fill = alpha(coords$fill, coords$alpha),
a9c214c @hadley Adjust stroke scale to work in mm.
authored
152 # Stroke is added around the outside of the point
153 fontsize = coords$size * .pt + coords$stroke * .stroke / 2,
154 lwd = coords$stroke * .stroke / 2
b52dc4b @hadley Tweak geom_point style
authored
155 )
156 )
4a89836 @hadley Simplify proto2 object creation
authored
157 )
158 },
b24e2cb @wch Convert geom_point to R6
wch authored
159
f99947f @hadley Rename guide_geom to draw_key #1182
authored
160 draw_key = draw_key_point,
b24e2cb @wch Convert geom_point to R6
wch authored
161
4a89836 @hadley Simplify proto2 object creation
authored
162 required_aes = c("x", "y"),
163 default_aes = aes(shape = 19, colour = "black", size = 2, fill = NA,
164 alpha = NA, stroke = 1)
b24e2cb @wch Convert geom_point to R6
wch authored
165 )
Something went wrong with that request. Please try again.