new_polys: Add one or more proportional-vertex based polygon shapes

In j-martineau/pj: Element-wise plots by JAM

Add one or more proportional-vertex based polygon shapes

Description

A proportional-vertex based polygon shape is created by proportionally defining an arbitrary number of vertex locations within a bounding rectangle. The shapes are located in plotting regions using bounding rectangles; a concept used in defining function parameters. See the defining bounding rectangles section for details.

Usage

new_polys(
  pj,
  pvx,
  pvy,
  x,
  y,
  w = NA,
  h = NA,
  re = NA,
  te = NA,
  px = 0.5,
  py = 0.5,
  region = ".",
  look = NULL,
  mod = NULL,
  name = "."
)

Arguments

pj	an object of class 'pj'.
pvx	proportion vector of length 3 or greater indicating the proportional x locations of the vertices of all polygons to be plotted as a proportion of the distance from left to right edge of bounding rectangles. All polygons must have the same number of vertices, and these proportions will be the same for all polygons. All values must be between 0 and 1, inclusive. See the the pvx and pvy arguments section. Length must be equal to the length of pvx.
pvy	proportion vector of length 3 or greater indicating the proportional y locations of the vertices of all polygons to be plotted as a proportion of the distance from bottom to top edge of bounding rectangles. All polygons must have the same number of vertices, and these proportions will be the same for all polygons. All values must be between 0 and 1, inclusive. See the the pvx and pvy arguments section. Length must be equal to the length of pvy.
x	numeric vector giving horizontal location. When x is used in conjunction with px and w these vectors define a fixed horizontal point for each shape. When x is used in conjunction with re, x defines the left edge of the bounding rectangle of each shape.
y	numeric vector giving vertical location. When y is used in conjunction with py and h these vectors define a fixed vertical point for each shape. When y is used in conjunction with te,y defines the bottom edge of the bounding rectangle of each shape.
w	NA or a numeric vector defining the width of each bounding rectangle.
h	NA or a numeric vector defining the height of each bounding rectangle.
re	NA or a numeric vector defining the right edge of each bounding rectangle.
te	NA or a numeric vector defining the top edge of each bounding rectangle.
px	NA or a proportion vector defining the location of x as the proportion of the distance from left to right edge of bounding rectangles. Values are generally between 0 and 1, inclusive, however, when they are outside those values, fixed points x will lie outside bounding rectangles.
py	NA or a proportion vector defining the location of y as the proportion of the distance from bottom to top edge of bounding rectangles. Values are generally between 0 and 1, inclusive, however, when they are outside those values, fixed points y will lie outside bounding rectangles.
region	either character scalar "." to indicate the most recently used region, a positive integer to indicate the ID number of a region (0 indicates the background region), or a character scalar to indicate the name of a region ('bg' indicates the background region).
look	an optional list containing up to four lists specifying looks to apply to the shape. See the using look to make shapes appear section.
mod	an optional list containing up to four lists specifying modifications to apply to the shape. See the using mod to transform shapes section.
name	character scalar indicating a name for the shape. The special value "." indicates that the pj package create a default name for the shape.

Value

pj with the addition of the defined proportional-vertex polygons

pvx, pvy, and vertex locations

pvx indicates, as a proportion, how far across the bounding rectangle each of the vertices of all polygons are located (from left to right). pvy indicates, as a proportion, how far up the bounding rectangle each of the vertices of all polygons are located. For example:

pvx = c(0, 1/2, 1), pvy = c(0, 1, 0)

Produces an upward isosceles triangle.

pvx = c(0, 1/2, 1, 1/2), pvy = c(1/2, 1, 1/2, 0)

Produces a diamond/rhombus, or a kite that is symmetric both horizontally and vertically.

pvx = c(0, 0, 1, 1), pvy = c(0, 1, 1, 0)

Produces a rectangle identical to the boundary rectangle.

pvx = c(0, 0, 1/2, 1, 1), pvy = c(0, 1, 1, 1/2, 0)

Produces a five-sided polygon that is a modified rectangle where the top right corner is cut off by a line running from halfway across the top edge of the bounding rectangle to halfway up the right edge of the bounding rectangle.

Defining bounding rectangles

Bounding rectangles can be defined in a number of ways. The following shows valid combination of non-NA locating arguments:

(x + px) + w + (y + py) + h

(horizontal anchor) + width + (vertical anchor) + height

(x + px) + w + y + te

(horizontal anchor) + bottom edge + top edge

x + re + (y + py) + h

left edge + right edge + (vertical anchor) + height

x + re + y + te

left edge + right edge + bottom edge + top edge

Bounding rectangles, px, and py

When px is not NA, it represents where the value x is located as a proportion of the distance between the left and right edge of each bounding rectangle. Likewise, when py is not NA, it represents where the value y is located as a proportion of the distance between the bottom and top edge of each bounding rectangle. For example:

• when px = 0.5 and py = 0.5, the center of the bounding rectangle is located at (x, y).

• when px = 0 and py = 0, the bottom left corner of the bounding rectangle is located at (x, y).

• when px = 1 and py = 1, the top right corner of the bounding rectangle is located at (x, y).

• when px = 1/3 and py = 2/3, the point 1/3 of the way from left to right edge and 2/3 of the way from bottom to top edge of the bounding rectangle is located at (x, y).

px and py can be less than 0 or greater than 1, resulting in the fixed point (x, y) being outside the bounding rectangle.

Using look to make shapes appear

By itself, this function simply defines the location of x-y pairs in the assigned region for the specified shape. Various looks can be added to the shape using the look parameter or via the add_ends, add_fills, add_glyphs, add_labels, add_lines, and add_marks functions. Sub-lists of the look argument must be named 'end', 'fill', 'glyph', 'label', 'line', and/or 'mark' to indicate that line end marks, fill colors, glyphs (single characters), labels, lines, and/or point marks be added to the shape.

Using mod to transform shapes

Shapes can be transformed in four ways: dilation, reflection, rotation, and translation/. using the mod argument or the mod_dilate, mod_reflect, mod_rotate, and mod_translate. Sub-lists of the mod argument must be named 'dilate', 'reflect', 'rotate', and/or 'translate' to indicate that a dilation, reflection, rotation, and or translation be applied to the shape.

Argument recycling

The argument set {x, y, w, h, re, te, px, py} is recycled.

See Also

Other new_polygons: new_free(), new_regulars(), new_stars()

j-martineau/pj documentation built on March 19, 2022, 5:32 a.m.