unit {grid} | R Documentation

## Function to Create a Unit Object

### Description

This function creates a unit object — a vector of unit values. A unit value is typically just a single numeric value with an associated unit.

### Usage

    unit(x, units, data=NULL)
    is.unit(unit)

### Arguments

`x` | A numeric vector.
`units` | A character vector specifying the units for the corresponding numeric values.
`data` | This argument is used to supply extra information for special `unit` types.
`unit` | Any object.

### Details

Unit objects allow the user to specify locations and dimensions in a large number of different coordinate systems. All drawing occurs relative to a viewport and the `units` specifies what coordinate system to use within that viewport.

Possible `units` (coordinate systems) are:

`"npc"`
  Normalised Parent Coordinates (the default). The origin of the viewport is (0, 0) and the viewport has a width and height of 1 unit. For example, (0.5, 0.5) is the centre of the viewport.
`"cm"`
  Centimetres.
`"inches"`
  Inches. 1 in = 2.54 cm.
`"mm"`
  Millimetres. 10 mm = 1 cm.
`"points"`
  Points. 72.27 pt = 1 in.
`"picas"`
  Picas. 1 pc = 12 pt.
`"bigpts"`
  Big Points. 72 bp = 1 in.
`"dida"`
  Dida. 1157 dd = 1238 pt.
`"cicero"`
  Cicero. 1 cc = 12 dd.
`"scaledpts"`
  Scaled Points. 65536 sp = 1 pt.
`"lines"`
  Lines of text. Locations and dimensions are in terms of multiples of the default text size of the viewport (as specified by the viewport's `fontsize` and `lineheight`).
`"mylines"`
  Same as `"lines"`, except will be influenced by grob's own gpar settings.
`"char"`
  Multiples of nominal font height of the viewport (as specified by the viewport's `fontsize`).
`"mychar"`
  Same as `"char"`, except will be influenced by grob's own gpar settings.
`"native"`
  Locations and dimensions are relative to the viewport's `xscale` and `yscale`.
`"snpc"`
  Square Normalised Parent Coordinates. Same as Normalised Parent Coordinates, except gives the same answer for horizontal and vertical locations/dimensions. It uses the lesser of npc-width and npc-height. This is useful for making things which are a proportion of the viewport, but have to be square (or have a fixed aspect ratio).
`"strwidth"`
  Multiples of the width of the string specified in the `data` argument. The font size is determined by the pointsize of the viewport.
`"strheight"`
  Multiples of the height of the string specified in the `data` argument. The font size is determined by the pointsize of the viewport.
`"grobwidth"`
  Multiples of the width of the grob specified in the `data` argument.
`"grobheight"`
  Multiples of the height of the grob specified in the `data` argument.

The `data` argument must be a list when the `unit.length()` is greater than 1. For example, `unit(rep(1, 3), c("npc", "strwidth", "inches"), data=list(NULL, "my string", NULL))`.

It is possible to subset unit objects in the normal way (e.g., `unit(1:5, "npc")[2:4]`), but a special function `unit.c` is provided for combining unit objects.

Certain arithmetic and summary operations are defined for unit objects. In particular, it is possible to add and subtract unit objects (e.g., `unit(1, "npc") - unit(1, "inches")`), and to specify the minimum or maximum of a list of unit objects (e.g., `min(unit(0.5, "npc"), unit(1, "inches"))`).

The `is.unit()` function returns a boolean value indicating whether the supplied argument is of class `"unit"`.

### Value

An object of class `"unit"`.

### WARNING

A special function `unit.length` is provided for determining the number of unit values in a unit object.

The `length` function will work in some cases, but in general will not give the right answer.

There is also a special function `unit.c` for concatenating several unit objects.

The `c` function will not give the right answer.

### Author(s)

Paul Murrell

### See Also

`unit.c`, `unit.rep`, `unit.pmin`, `unit.pmax`, and `unit.length`

### Examples

    unit(1, "npc")
    unit(1:3/4, "npc")
    unit(1:3/4, "npc") + unit(1, "inches")
    min(unit(0.5, "npc"), unit(1, "inches"))
    unit.c(unit(0.5, "npc"), unit(2, "inches") + unit(1:3/4, "npc"),
           unit(1, "strwidth", "hi there"))

[Package Contents]