Translate and/or compute NPC (Normalised Parent Coordinates) for use with
aesthetics x and y.
Usage
compute_npcx(x, group = 1L, h.step = 0.1, margin.npc = 0.05, each.len = 1)
compute_npcy(y, group = 1L, v.step = 0.1, margin.npc = 0.05, each.len = 1)
as_npcx(x, ...)
as_npcy(y, ...)
compute_npc(a, margin.npc = 0.05)
as_npc(a, margin.npc = 0.05)Arguments
- x
numeric or if character, one of "right", "left", "maximum", "minimum", "centre", "center" or "middle".
- group
integer vector, ggplot's group id. Used to shift coordinates to avoid overlaps.
- h.step, v.step
numeric [0..1] The step size for shifting coordinates in npc units. Usually << 1.
- margin.npc
numeric [0..1] The margin added towards the nearest plotting area edge when converting character coordinates into npc. Usually << 1.
- each.len
integer The number of steps per group.
- y
numeric or if character, one of "top", "bottom", "maximum", "minimum", "centre", "center" or "middle".
- ...
named arguments passed to
compute_npcx()orcompute_npcy().- a
numeric or if character, one of "right", "left", "top", "maximum", "minimum", "bottom", "centre", "center" or "middle".
Details
Functions compute_npcx and compute_npcy convert
character-encoded positions to npc units and shift positions to avoid
overlaps when grouping is active. If numeric, they validate the npc values.
Function compute_npcx does the translation either for both x
and y aesthetics, but does not implement a shift for grpups.
Functions as_npcx(), as_npcy() and as_npc() are
wrappers on these functions that return the value as objects of class
"AsIs" so that in 'ggplot2' >= 3.5.0 they can be used with any layer
function.
These functions use NPC (Normalised Parent Coordinates) instead of data coordinates. They translate named positions into numeric values in [0..1] and they can also shift the position according to the group, e.g., for each increase in the group number displace the position inwards or outwards, by a user-supplied distance. They make it possible to set automatically set default positions for grouped text labels.
Out of bounds numeric values are constrained to [0..1]. Unrecognized
character values are silently converted into NA_integer_.
Note
The as_npc() functions make it easier the use of NPC coordinates with 'ggplot2' >= 3.5.0. The _compute_ functions are used by several layer functions in packages 'ggpp' and 'ggpmisc', are compatible with 'ggplot2' <= 3.4.4 and can be useful to developers of other 'ggplot2' extensions.
Examples
compute_npcx("right")
#> [1] 0.95
compute_npcx(c("left", "right"))
#> [1] 0.05 0.95
compute_npcx(c("minimum", "maximum"))
#> [1] 0 1
compute_npcx(c("left", "right"), margin.npc = 0)
#> [1] 0 1
compute_npcy("bottom")
#> [1] 0.05
compute_npcy("bottom", group = 1L:3L)
#> [1] 0.05 0.15 0.25
compute_npcy("bottom", group = 1L:3L, v.step = 0.2)
#> [1] 0.05 0.25 0.45
compute_npcy("bottom", group = 2L)
#> [1] 0.15
compute_npcx(0.5)
#> [1] 0.5
compute_npcx(1)
#> [1] 1
compute_npcx(-2)
#> [1] 0
as_npc("right")
#> [1] 0.95
class(as_npc("right"))
#> [1] "AsIs"
class(compute_npcx("right"))
#> [1] "numeric"