separate new coords into rect for gggda & scaffold for ggbiplot

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'

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)

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

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)
+  }
+)

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

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)