diff --git a/DESCRIPTION b/DESCRIPTION index de79ccd..0f6aa4b 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -65,6 +65,7 @@ Collate: 'biplot-key.r' 'biplot.r' 'coord-rect.r' + 'coord-scaffold.r' 'data.r' 'dplyr-verbs.r' 'utils.r' @@ -117,7 +118,7 @@ Collate: 'stat-rule.r' 'stat-scale.r' 'stat-spantree.r' - 'themes.r' + 'theme-scaffold.r' 'zzz-biplot-geoms.r' 'zzz-biplot-stats.r' 'zzz.r' diff --git a/NAMESPACE b/NAMESPACE index cfc82d7..bff1e2e 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -183,8 +183,8 @@ S3method(screeplot,tbl_ord) S3method(stats::model.frame,lda_ord) S3method(tidy,tbl_ord) export("%>%") -export(CoordBiplot) export(CoordRect) +export(CoordScaffold) export(GeomAxis) export(GeomBagplot) export(GeomInterpolation) @@ -248,8 +248,8 @@ export(cbind_cols) export(cbind_rows) export(cmdscale_ord) export(confer_inertia) -export(coord_biplot) export(coord_rect) +export(coord_scaffold) export(coord_square) export(draw_key_crosslines) export(draw_key_crosspoint) diff --git a/R/coord-rect.r b/R/coord-rect.r index 52016b1..a81297e 100644 --- a/R/coord-rect.r +++ b/R/coord-rect.r @@ -1,3 +1,33 @@ +#' @title Cartesian coordinates and plotting window with fixed aspect ratios +#' +#' @description Geometric data analysis often requires that coordinates lie on +#' the same scale. The coordinate system `CoordRect`, alias `CoordSquare`, +#' provides control of both coordinate and window aspect ratios. +#' +#' @inheritParams ggplot2::coord_fixed +#' @param window_ratio aspect ratio of plotting window +#' @example inst/examples/ex-coord-rect.r +#' @export +coord_rect <- function( + ratio = 1, window_ratio = ratio, + xlim = NULL, ylim = NULL, expand = TRUE, clip = "on" +) { + ggplot2:::check_coord_limits(xlim) + ggplot2:::check_coord_limits(ylim) + ggproto( + NULL, CoordRect, + limits = list(x = xlim, y = ylim), + ratio = ratio, window_ratio = window_ratio, + expand = expand, + clip = clip + ) +} + +#' @rdname coord_rect +#' @usage NULL +#' @export +coord_square <- coord_rect + #' @rdname ordr-ggproto #' @format NULL #' @usage NULL @@ -26,7 +56,7 @@ CoordRect <- ggproto( aesthetic_y <- scale_y$aesthetics[1] # synchronize limits and ranges according to `window_ratio` after adjusting - # for `ratio` (if it is provided; it isn't in `CoordBiplot`) + # for `ratio` (if it is provided; it isn't in `CoordScaffold`) adj_ratio <- self$window_ratio / (self$ratio %||% 1) limits <- reconcile_rectangle(limits_x, limits_y, adj_ratio) continuous_range <- reconcile_rectangle( @@ -53,95 +83,6 @@ CoordRect <- ggproto( } ) -#' @rdname ordr-ggproto -#' @format NULL -#' @usage NULL -#' @export -CoordBiplot <- ggproto( - "CoordBiplot", CoordRect, - - # require coordinate aspect ratio to be 1 - aspect = function(self, ranges) { - diff(ranges$y.range) / diff(ranges$x.range) - } -) - -#' @title Cartesian coordinates and plotting window with fixed aspect ratios -#' -#' @description 2- (and 3-) dimensional biplots require that coordinates lie on -#' the same scale but may additionally benefit from a square plotting window. -#' The general-purpose coordinate system `CoordRect`, alias `CoordSquare`, -#' provides control of both coordinate and window aspect ratios, while the -#' convenience `CoordBiplot` system fixes the coordinate aspect ratio at `1` -#' and gives the user control only of the plotting window. -#' -#' @inheritParams ggplot2::coord_fixed -#' @param window_ratio aspect ratio of plotting window -#' @examples -#' # ensures that the resolutions of the axes and the dimensions of the plotting -#' # window respect the specified aspect ratios -#' -#' p <- ggplot(mtcars, aes(mpg, hp/10)) + geom_point() -#' p + coord_rect(ratio = 1) -#' p + coord_rect(ratio = 1, window_ratio = 2) -#' p + coord_rect(ratio = 1, window_ratio = 1/2) -#' p + coord_rect(ratio = 5) -#' p + coord_rect(ratio = 1/5) -#' p + coord_rect(xlim = c(15, 30)) -#' p + coord_rect(ylim = c(15, 30)) -#' -#' # Resize the plot to see that the specified aspect ratio is maintained -#' @export -coord_rect <- function( - ratio = 1, window_ratio = ratio, - xlim = NULL, ylim = NULL, expand = TRUE, clip = "on" -) { - ggplot2:::check_coord_limits(xlim) - ggplot2:::check_coord_limits(ylim) - ggproto( - NULL, CoordRect, - limits = list(x = xlim, y = ylim), - ratio = ratio, window_ratio = window_ratio, - expand = expand, - clip = clip - ) -} - -#' @rdname coord_rect -#' @usage NULL -#' @export -coord_square <- coord_rect - -#' @rdname coord_rect -#' @examples -#' p <- ggplot(mtcars, aes(mpg, hp/10)) + geom_point() -#' p + coord_biplot() -#' p + coord_biplot(window_ratio = 2) -#' -#' # prevent rescaling in response to `theme()` aspect ratio -#' p <- ggplot(mtcars, aes(mpg, hp/5)) + geom_point() -#' p + coord_equal() + theme(aspect.ratio = 1) -#' p + coord_biplot() + theme(aspect.ratio = 1) -#' -#' # NB: `theme(aspect.ratio = )` overrides `Coord*$aspect`: -#' p + coord_fixed(ratio = 1) + theme(aspect.ratio = 1) -#' p + coord_biplot(window_ratio = 2) + theme(aspect.ratio = 1) -#' @export -coord_biplot <- function( - window_ratio = 1, - xlim = NULL, ylim = NULL, expand = TRUE, clip = "on" -) { - ggplot2:::check_coord_limits(xlim) - ggplot2:::check_coord_limits(ylim) - ggproto( - NULL, CoordBiplot, - limits = list(x = xlim, y = ylim), - window_ratio = window_ratio, - expand = expand, - clip = clip - ) -} - reconcile_rectangle <- function(xlim, ylim, ratio) { sides <- c(diff(xlim), diff(ylim)) # by how much to scale each dimension to achieve desired aspect ratio diff --git a/R/coord-scaffold.r b/R/coord-scaffold.r new file mode 100644 index 0000000..af94081 --- /dev/null +++ b/R/coord-scaffold.r @@ -0,0 +1,39 @@ +#' @title Convenience coordinate system for scaffolding axes +#' +#' @description 2- (and 3-) dimensional biplots require that coordinates lie on +#' the same scale but may additionally benefit from a square plotting window. +#' While `CoordRect` provides control of coordinate and window aspect ratios, +#' the convenience `CoordScaffold` system also fixes the coordinate aspect +#' ratio at `1` and gives the user control only of the plotting window. +#' +#' @inheritParams ggplot2::coord_fixed +#' @param window_ratio aspect ratio of plotting window +#' @example inst/examples/ex-coord-scaffold.r +#' @export +coord_scaffold <- function( + window_ratio = 1, + xlim = NULL, ylim = NULL, expand = TRUE, clip = "on" +) { + ggplot2:::check_coord_limits(xlim) + ggplot2:::check_coord_limits(ylim) + ggproto( + NULL, CoordScaffold, + limits = list(x = xlim, y = ylim), + window_ratio = window_ratio, + expand = expand, + clip = clip + ) +} + +#' @rdname ordr-ggproto +#' @format NULL +#' @usage NULL +#' @export +CoordScaffold <- ggproto( + "CoordScaffold", CoordRect, + + # require coordinate aspect ratio to be 1 + aspect = function(self, ranges) { + diff(ranges$y.range) / diff(ranges$x.range) + } +) diff --git a/R/themes.r b/R/theme-scaffold.r similarity index 100% rename from R/themes.r rename to R/theme-scaffold.r diff --git a/inst/examples/ex-coord-rect.r b/inst/examples/ex-coord-rect.r new file mode 100644 index 0000000..177cb49 --- /dev/null +++ b/inst/examples/ex-coord-rect.r @@ -0,0 +1,10 @@ +# ensures that the resolutions of the axes and the dimensions of the plotting +# window respect the specified aspect ratios +p <- ggplot(mtcars, aes(mpg, hp/10)) + geom_point() +p + coord_rect(ratio = 1) +p + coord_rect(ratio = 1, window_ratio = 2) +p + coord_rect(ratio = 1, window_ratio = 1/2) +p + coord_rect(ratio = 5) +p + coord_rect(ratio = 1/5) +p + coord_rect(xlim = c(15, 30)) +p + coord_rect(ylim = c(15, 30)) diff --git a/inst/examples/ex-coord-scaffold.r b/inst/examples/ex-coord-scaffold.r new file mode 100644 index 0000000..f392329 --- /dev/null +++ b/inst/examples/ex-coord-scaffold.r @@ -0,0 +1,13 @@ +# resize the plot to see that the specified aspect ratio is maintained +p <- ggplot(mtcars, aes(mpg, hp/10)) + geom_point() +p + coord_scaffold() +p + coord_scaffold(window_ratio = 2) + +# prevent rescaling in response to `theme()` aspect ratio +p <- ggplot(mtcars, aes(mpg, hp/5)) + geom_point() +p + coord_equal() + theme(aspect.ratio = 1) +p + coord_scaffold() + theme(aspect.ratio = 1) + +# NB: `theme(aspect.ratio = )` overrides `Coord*$aspect`: +p + coord_fixed(ratio = 1) + theme(aspect.ratio = 1) +p + coord_scaffold(window_ratio = 2) + theme(aspect.ratio = 1) diff --git a/man/coord_rect.Rd b/man/coord_rect.Rd index 3ff0f88..733a117 100644 --- a/man/coord_rect.Rd +++ b/man/coord_rect.Rd @@ -3,7 +3,6 @@ \name{coord_rect} \alias{coord_rect} \alias{coord_square} -\alias{coord_biplot} \title{Cartesian coordinates and plotting window with fixed aspect ratios} \usage{ coord_rect( @@ -14,14 +13,6 @@ coord_rect( expand = TRUE, clip = "on" ) - -coord_biplot( - window_ratio = 1, - xlim = NULL, - ylim = NULL, - expand = TRUE, - clip = "on" -) } \arguments{ \item{ratio}{aspect ratio, expressed as \code{y / x}} @@ -44,17 +35,13 @@ limits, then those data points may show up in places such as the axes, the legend, the plot title, or the plot margins.} } \description{ -2- (and 3-) dimensional biplots require that coordinates lie on -the same scale but may additionally benefit from a square plotting window. -The general-purpose coordinate system \code{CoordRect}, alias \code{CoordSquare}, -provides control of both coordinate and window aspect ratios, while the -convenience \code{CoordBiplot} system fixes the coordinate aspect ratio at \code{1} -and gives the user control only of the plotting window. +Geometric data analysis often requires that coordinates lie on +the same scale. The coordinate system \code{CoordRect}, alias \code{CoordSquare}, +provides control of both coordinate and window aspect ratios. } \examples{ # ensures that the resolutions of the axes and the dimensions of the plotting # window respect the specified aspect ratios - p <- ggplot(mtcars, aes(mpg, hp/10)) + geom_point() p + coord_rect(ratio = 1) p + coord_rect(ratio = 1, window_ratio = 2) @@ -63,18 +50,4 @@ p + coord_rect(ratio = 5) p + coord_rect(ratio = 1/5) p + coord_rect(xlim = c(15, 30)) p + coord_rect(ylim = c(15, 30)) - -# Resize the plot to see that the specified aspect ratio is maintained -p <- ggplot(mtcars, aes(mpg, hp/10)) + geom_point() -p + coord_biplot() -p + coord_biplot(window_ratio = 2) - -# prevent rescaling in response to `theme()` aspect ratio -p <- ggplot(mtcars, aes(mpg, hp/5)) + geom_point() -p + coord_equal() + theme(aspect.ratio = 1) -p + coord_biplot() + theme(aspect.ratio = 1) - -# NB: `theme(aspect.ratio = )` overrides `Coord*$aspect`: -p + coord_fixed(ratio = 1) + theme(aspect.ratio = 1) -p + coord_biplot(window_ratio = 2) + theme(aspect.ratio = 1) } diff --git a/man/coord_scaffold.Rd b/man/coord_scaffold.Rd new file mode 100644 index 0000000..10bdb92 --- /dev/null +++ b/man/coord_scaffold.Rd @@ -0,0 +1,54 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/coord-scaffold.r +\name{coord_scaffold} +\alias{coord_scaffold} +\title{Convenience coordinate system for scaffolding axes} +\usage{ +coord_scaffold( + window_ratio = 1, + xlim = NULL, + ylim = NULL, + expand = TRUE, + clip = "on" +) +} +\arguments{ +\item{window_ratio}{aspect ratio of plotting window} + +\item{xlim, ylim}{Limits for the x and y axes.} + +\item{expand}{If \code{TRUE}, the default, adds a small expansion factor to +the limits to ensure that data and axes don't overlap. If \code{FALSE}, +limits are taken exactly from the data or \code{xlim}/\code{ylim}.} + +\item{clip}{Should drawing be clipped to the extent of the plot panel? A +setting of \code{"on"} (the default) means yes, and a setting of \code{"off"} +means no. In most cases, the default of \code{"on"} should not be changed, +as setting \code{clip = "off"} can cause unexpected results. It allows +drawing of data points anywhere on the plot, including in the plot margins. If +limits are set via \code{xlim} and \code{ylim} and some data points fall outside those +limits, then those data points may show up in places such as the axes, the +legend, the plot title, or the plot margins.} +} +\description{ +2- (and 3-) dimensional biplots require that coordinates lie on +the same scale but may additionally benefit from a square plotting window. +While \code{CoordRect} provides control of coordinate and window aspect ratios, +the convenience \code{CoordScaffold} system also fixes the coordinate aspect +ratio at \code{1} and gives the user control only of the plotting window. +} +\examples{ +# resize the plot to see that the specified aspect ratio is maintained +p <- ggplot(mtcars, aes(mpg, hp/10)) + geom_point() +p + coord_scaffold() +p + coord_scaffold(window_ratio = 2) + +# prevent rescaling in response to `theme()` aspect ratio +p <- ggplot(mtcars, aes(mpg, hp/5)) + geom_point() +p + coord_equal() + theme(aspect.ratio = 1) +p + coord_scaffold() + theme(aspect.ratio = 1) + +# NB: `theme(aspect.ratio = )` overrides `Coord*$aspect`: +p + coord_fixed(ratio = 1) + theme(aspect.ratio = 1) +p + coord_scaffold(window_ratio = 2) + theme(aspect.ratio = 1) +} diff --git a/man/ordr-ggproto.Rd b/man/ordr-ggproto.Rd index 90a0f19..1ba77f3 100644 --- a/man/ordr-ggproto.Rd +++ b/man/ordr-ggproto.Rd @@ -1,6 +1,6 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/aaa-.r, R/coord-rect.r, R/geom-axis.r, -% R/geom-bagplot.r, R/geom-interpolation.r, R/geom-intervals.r, +% Please edit documentation in R/aaa-.r, R/coord-rect.r, R/coord-scaffold.r, +% R/geom-axis.r, R/geom-bagplot.r, R/geom-interpolation.r, R/geom-intervals.r, % R/geom-isoline.r, R/geom-origin.r, R/geom-rule.r, R/geom-text-radiate.r, % R/geom-vector.r, R/stat-chull.r, R/stat-depth.r, R/stat-bagplot.r, % R/stat-center.r, R/stat-cone.r, R/stat-matrix.r, R/stat-referent.r, @@ -10,7 +10,7 @@ \name{ordr-ggproto} \alias{ordr-ggproto} \alias{CoordRect} -\alias{CoordBiplot} +\alias{CoordScaffold} \alias{GeomAxis} \alias{GeomBagplot} \alias{GeomInterpolation} diff --git a/man/theme_scaffold.Rd b/man/theme_scaffold.Rd index dfebf57..b4813ce 100644 --- a/man/theme_scaffold.Rd +++ b/man/theme_scaffold.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/themes.r +% Please edit documentation in R/theme-scaffold.r \name{theme_scaffold} \alias{theme_scaffold} \alias{theme_biplot}