coordPresets: Process coordinate adjustment presets

In jmw86069/jamba: Jam Base Methods

Process coordinate adjustment presets

Description

Process coordinate adjustment presets

Usage

coordPresets(
  preset = "default",
  x = 0,
  y = 0,
  adjPreset = "default",
  adjX = 0.5,
  adjY = 0.5,
  adjOffsetX = 0,
  adjOffsetY = 0,
  preset_type = c("plot"),
  verbose = FALSE,
  ...
)

Arguments

preset	character vector of coordinate positions, or "default" to use the ⁠x,y⁠ coordinates.
x, y	numeric vectors indicating the default coordinates ⁠x,y⁠.
adjPreset	character vector of text label positions, or "default" to use preset, or when preset="default" the ⁠adjX,adjY⁠ values are used.
adjX, adjY	numeric vectors indicating default text adjustment values, as described for adj in graphics::text().
adjOffsetX, adjOffsetY	numeric vector used to apply an offset value to the ⁠adjX,adjY⁠ values, where positive values would place a label farther away from center. Note these units are relative to the text label size, when used with graphics::text(), larger labels will be adjusted more than smaller labels.
preset_type	character string indicating the reference point for the preset boundaries: "plot" uses the plot border. "margin" uses the margin border. Note that the margin used is the inner margin around the plot figure, not the outer margin which may be applied around multi-panel plot figures.
verbose	logical indicating whether to print verbose output.
...	additional arguments are ignored.

Details

This function is intended to be a convenient way to define coordinates using preset terms like "topleft", "bottom", "center".

Similarly, it is intended to help define corresponding text adjustments, using adj compatible with graphics::text(), using preset terms like "bottomright", "center".

When preset is "default", the original ⁠x,y⁠ coordinates are used. Otherwise the ⁠x,y⁠ coordinates are defined using the plot region coordinates, where "left" uses par("usr")[1], and "top" uses par("usr")[4].

When adjPreset is "default" it will use the preset to define a reciprocal text placement. For example when preset="topright" the text placement will be equivalent to adjPreset="bottomleft". The adjPreset terms "top", "bottom", "right", "left", and "center" refer to the text label placement relative to ⁠x,y⁠ coordinate.

If both preset="default" and adjPreset="default" the original ⁠adjX,adjY⁠ values are returned.

The function is vectorized, and uses the longest input argument, so one can supply a vector of preset and it will return coordinates and adjustments of length equal to the input preset vector. The preset value takes priority over the supplied ⁠x,y⁠ coordinates.

Value

data.frame after adjustment, where the number of rows is determined by the longest input argument, with colnames:

• x

• y

• adjX

• adjY

• preset

• adjPreset

See Also

Other jam plot functions: adjustAxisLabelMargins(), decideMfrow(), drawLabels(), getPlotAspect(), groupedAxis(), imageByColors(), imageDefault(), minorLogTicksAxis(), nullPlot(), plotPolygonDensity(), plotRidges(), plotSmoothScatter(), shadowText_options(), shadowText(), showColors(), smoothScatterJam(), sqrtAxis(), usrBox()

Examples

# determine coordinates
presetV <- c("top",
   "bottom",
   "left",
   "right",
   "topleft");
cp1 <- coordPresets(preset=presetV);
cp1;

# make sure to prepare the plot region first
jamba::nullPlot(plotAreaTitle="");
points(cp1$x, cp1$y, pch=20, cex=2, col="red");

# unfortunately graphics::text() does not have vectorized adj
# so it must iterate each row
title(main="text() is not vectorized, text is adjacent to edges")
for (i in seq_along(presetV)) {
   text(cp1$x[i], cp1$y[i],
      labels=presetV[i],
      adj=c(cp1$adjX[i], cp1$adjY[i]));
}

# drawLabels() will be vectorized for unique adj subsets
# and adds a small buffer around text
jamba::nullPlot(plotAreaTitle="");
title(main="drawLabels() is vectorized, includes small buffer")
drawLabels(txt=presetV,
   preset=presetV)

jamba::nullPlot(plotAreaTitle="");
title(main="drawLabels() can place labels outside plot edges")
drawLabels(txt=presetV,
   preset=presetV,
   adjPreset=presetV)

# drawLabels() is vectorized for example
jamba::nullPlot(plotAreaTitle="");
title(main="Use adjPreset to position labels at a center point")
presetV2 <- c("topleft",
   "topright",
   "bottomleft",
   "bottomright");
cp2 <- coordPresets(preset="center",
   adjPreset=presetV2,
   adjOffsetX=0.1,
   adjOffsetY=0.4);
points(cp2$x,
   cp2$y,
   pch=20,
   cex=2,
   col="red");
drawLabels(x=cp2$x,
   y=cp2$y,
   adjX=cp2$adjX,
   adjY=cp2$adjY,
   txt=presetV2,
   boxCexAdjust=c(1.15,1.6),
   labelCex=1.3,
   lx=rep(1.5, 4),
   ly=rep(1.5, 4))

# demonstrate margin coordinates
par("oma"=c(1, 1, 1, 1));
nullPlot(xlim=c(0, 1), ylim=c(1, 5));
cpxy <- coordPresets(rep(c("top", "bottom", "left", "right"), each=2),
   preset_type=rep(c("plot", "figure"), 4));
drawLabels(preset=c("top", "top"),
   txt=c("top label relative to figure",
      "top label relative to plot"),
   preset_type=c("figure", "plot"))
points(cpxy$x, cpxy$y, cex=2,
   col="red4", bg="red1", xpd=NA,
   pch=rep(c(21, 23), 4))
par("oma"=c(0, 0, 0, 0));

jmw86069/jamba documentation built on Oct. 9, 2024, 10:52 a.m.