addition/interpolation, projection/prediction, and limiting/offsetting rule layers

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: ordr
 Title: A Tidyverse Extension for Ordinations and Biplots
-Version: 0.1.1.0001
+Version: 0.1.1.0002
 Authors@R: c(
   person("Jason Cory", "Brunson", email = "[email protected]",
     role = c("aut", "cre"), comment = c(ORCID = "0000-0003-3126-9494")),
@@ -74,9 +74,11 @@ Collate:
     'fun-lra.r'
     'fun-wrap.r'
     'geom-axis.r'
+    'geom-interpolation.r'
     'geom-intervals.r'
     'geom-isoline.r'
     'geom-origin.r'
+    'geom-rule.r'
     'geom-text-radiate.r'
     'geom-utils.r'
     'geom-vector.r'
@@ -105,6 +107,9 @@ Collate:
     'stat-chull.r'
     'stat-cone.r'
     'stat-matrix.r'
+    'stat-referent.r'
+    'stat-projection.r'
+    'stat-rule.r'
     'stat-scale.r'
     'stat-spantree.r'
     'themes.r'

NAMESPACE

@@ -23,6 +23,7 @@ S3method(biplot,tbl_ord)
 S3method(dim,tbl_ord)
 S3method(format,tbl_ord)
 S3method(fortify,tbl_ord)
+S3method(ggplot_add,LayerRef)
 S3method(glance,tbl_ord)
 S3method(lda_ord,data.frame)
 S3method(lda_ord,default)
@@ -185,10 +186,12 @@ export("%>%")
 export(CoordBiplot)
 export(CoordRect)
 export(GeomAxis)
+export(GeomInterpolation)
 export(GeomIsoline)
 export(GeomLineranges)
 export(GeomOrigin)
 export(GeomPointranges)
+export(GeomRule)
 export(GeomTextRadiate)
 export(GeomUnitCircle)
 export(GeomVector)
@@ -199,18 +202,25 @@ export(StatColsCenter)
 export(StatColsChull)
 export(StatColsCone)
 export(StatColsEllipse)
+export(StatColsProjection)
+export(StatColsRule)
 export(StatColsScale)
 export(StatColsSpantree)
 export(StatColsStar)
 export(StatCone)
+export(StatProjection)
+export(StatReferent)
 export(StatRows)
 export(StatRowsCenter)
 export(StatRowsChull)
 export(StatRowsCone)
 export(StatRowsEllipse)
+export(StatRowsProjection)
+export(StatRowsRule)
 export(StatRowsScale)
 export(StatRowsSpantree)
 export(StatRowsStar)
+export(StatRule)
 export(StatScale)
 export(StatSpantree)
 export(StatStar)
@@ -230,6 +240,7 @@ export(draw_key_line)
 export(eigen_ord)
 export(geom_axis)
 export(geom_cols_axis)
+export(geom_cols_interpolation)
 export(geom_cols_isoline)
 export(geom_cols_label)
 export(geom_cols_label_repel)
@@ -238,16 +249,19 @@ export(geom_cols_path)
 export(geom_cols_point)
 export(geom_cols_pointranges)
 export(geom_cols_polygon)
+export(geom_cols_rule)
 export(geom_cols_text)
 export(geom_cols_text_radiate)
 export(geom_cols_text_repel)
 export(geom_cols_vector)
+export(geom_interpolation)
 export(geom_isoline)
 export(geom_label_repel)
 export(geom_lineranges)
 export(geom_origin)
 export(geom_pointranges)
 export(geom_rows_axis)
+export(geom_rows_interpolation)
 export(geom_rows_isoline)
 export(geom_rows_label)
 export(geom_rows_label_repel)
@@ -256,10 +270,12 @@ export(geom_rows_path)
 export(geom_rows_point)
 export(geom_rows_pointranges)
 export(geom_rows_polygon)
+export(geom_rows_rule)
 export(geom_rows_text)
 export(geom_rows_text_radiate)
 export(geom_rows_text_repel)
 export(geom_rows_vector)
+export(geom_rule)
 export(geom_text_radiate)
 export(geom_text_repel)
 export(geom_unit_circle)
@@ -279,6 +295,9 @@ export(left_join_cols)
 export(left_join_rows)
 export(lra)
 export(make_tbl_ord)
+export(maxpp)
+export(minabspp)
+export(minpp)
 export(mutate_cols)
 export(mutate_rows)
 export(negate_ord)
@@ -310,18 +329,25 @@ export(stat_cols_center)
 export(stat_cols_chull)
 export(stat_cols_cone)
 export(stat_cols_ellipse)
+export(stat_cols_projection)
+export(stat_cols_rule)
 export(stat_cols_scale)
 export(stat_cols_spantree)
 export(stat_cols_star)
 export(stat_cone)
+export(stat_projection)
+export(stat_referent)
 export(stat_rows)
 export(stat_rows_center)
 export(stat_rows_chull)
 export(stat_rows_cone)
 export(stat_rows_ellipse)
+export(stat_rows_projection)
+export(stat_rows_rule)
 export(stat_rows_scale)
 export(stat_rows_spantree)
 export(stat_rows_star)
+export(stat_rule)
 export(stat_scale)
 export(stat_spantree)
 export(stat_star)

NEWS.md

@@ -11,7 +11,23 @@ Multiple harmonizers are now available for scaling secondary axes. That recommen
 ## GDA-geared coordinate systems
 
 Two new coordinate systems provide control over the aspect ratio of the plotting window without compromising that of the (artificial) coordinate axes:
-`GeomRect` (alias `GeomSquare`) extends `GeomFixed` with an `aspect_ratio` parameter for the plotting window, while `GeomBiplot` removes the `ratio` parameter and forces the coordinate axes to have aspect ratio 1.
+`GeomRect` (alias `GeomSquare`) extends `GeomFixed` with an `window_ratio` parameter for the plotting window, while `GeomBiplot` removes the `ratio` parameter and forces the coordinate axes to have aspect ratio 1.
+
+## referential stats
+
+A new statistical transformation serves to parent specific "referential stats", meaning those that depend on non-inherited (in this setting, positional) data to transform the inherited data. The reference data are passed to the new `referent` parameter. The new stat is coupled with an additional `LayerRef` class that enables `ggplot_add()` to pass the inherited positional aesthetics to `$setup_params()`. Biplot-specific `stat_*_*()` shortcuts accept additional argument types to `referent` that result in the opposite matrix factor being used as reference data.
+
+## projection stat
+
+The 'projection' referential stat prepares segment endpoints between `x,y` positions and their projections on axes defined by the reference data. It is a natural graphical element for predictive biplots of ordination models of continuous data.
+
+## rule stat
+
+A new 'rule' statistical transformation computes additional position aesthetics that the 'axis' geom uses to limit and offset axes. The stat is referential and expects a set of functions that compute limits `lower` and `upper` along the axes and `yintercept` and `xintercept` associated with offset axes. The 'axis' geom preprocesses these aesthetics to rule endpoints `xmin,ymin,xmax,ymax` and offset vectors `xend,yend` to force the plotting window to contain the limited axis segments or, if the axes remain lines, the offsets where they are centered.
+
+## angle,radius specifications
+
+Several geometric object layers ('vector', 'isoline', and 'axis') now accept polar as well as cartesian coordinates. Whereas cartesian coordinates influence the plotting window, polar coordinates do not, so this allows for the plot to ignore elements like axes that may not be intended to influence the window dimensions. This is an experimental convenience feature that may be removed in a future version.
 
 # ordr 0.1.1
 

R/coord-rect.r

@@ -25,9 +25,9 @@ CoordRect <- ggproto(
     )
     aesthetic_y <- scale_y$aesthetics[1]
 
-    # synchronize limits and ranges according to `aspect_ratio` after adjusting
+    # synchronize limits and ranges according to `window_ratio` after adjusting
     # for `ratio` (if it is provided; it isn't in `CoordBiplot`)
-    adj_ratio <- self$aspect_ratio / (self$ratio %||% 1)
+    adj_ratio <- self$window_ratio / (self$ratio %||% 1)
     limits <- reconcile_rectangle(limits_x, limits_y, adj_ratio)
     continuous_range <- reconcile_rectangle(
       continuous_range_x, continuous_range_y, adj_ratio
@@ -66,25 +66,25 @@ CoordBiplot <- ggproto(
   }
 )
 
-#' Cartesian coordinates and plotting window with fixed aspect ratios
+#' @title Cartesian coordinates and plotting window with fixed aspect ratios
 #'
-#' 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.
+#' @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 aspect_ratio aspect ratio of plotting window
+#' @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, aspect_ratio = 2)
-#' p + coord_rect(ratio = 1, aspect_ratio = 1/2)
+#' 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))
@@ -93,15 +93,15 @@ CoordBiplot <- ggproto(
 #' # Resize the plot to see that the specified aspect ratio is maintained
 #' @export
 coord_rect <- function(
-    ratio = 1, aspect_ratio = ratio,
+    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, aspect_ratio = aspect_ratio,
+    ratio = ratio, window_ratio = window_ratio,
     expand = expand,
     clip = clip
   )
@@ -116,7 +116,7 @@ coord_square <- coord_rect
 #' @examples
 #' p <- ggplot(mtcars, aes(mpg, hp/10)) + geom_point()
 #' p + coord_biplot()
-#' p + coord_biplot(aspect_ratio = 2)
+#' p + coord_biplot(window_ratio = 2)
 #' 
 #' # prevent rescaling in response to `theme()` aspect ratio
 #' p <- ggplot(mtcars, aes(mpg, hp/5)) + geom_point()
@@ -125,18 +125,18 @@ coord_square <- coord_rect
 #' 
 #' # NB: `theme(aspect.ratio = )` overrides `Coord*$aspect`:
 #' p + coord_fixed(ratio = 1) + theme(aspect.ratio = 1)
-#' p + coord_biplot(aspect_ratio = 2) + theme(aspect.ratio = 1)
+#' p + coord_biplot(window_ratio = 2) + theme(aspect.ratio = 1)
 #' @export
 coord_biplot <- function(
-    aspect_ratio = 1,
+    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),
-    aspect_ratio = aspect_ratio,
+    window_ratio = window_ratio,
     expand = expand,
     clip = clip
   )