ggvis (version 0.4.9)

props: Manage a list of properties.

Description

props() provides a tool for concise creation of prop objects using a set of conventions designed to capture the most common use cases. If you need something less common, you'll need to use prop to access all possible options.

Usage

props(..., .props = NULL, inherit = TRUE, env = parent.frame())
is.ggvis_props(x)

Arguments

...

A set of name-value pairs. The name should be a valid vega property.

The first two unnamed components are taken to be x and y. Any additional unnamed components will raise an error.

.props

When calling props from other functions, you'll often have a list of quoted function functions. You can pass that function to the .props argument instead of messing around with substitute. In other words, .props lets you opt out of the non-standard evaluation that props does.

inherit

If TRUE, the defaults, will inherit from properties from the parent layer If FALSE, it will start from nothing.

env

The environment in which to evaluate variable properties.

x

an object to test for props-ness.

Heuristics

If the values are not already objects of class prop, props uses the following heuristics to when creating the prop:

• atomic vectors, e.g. x = 1: scaled = FALSE

• an interative input, e.g. x = input_slider: scaled = FALSE

• a formula containing a single value, e.g. x ~ 1: scaled = TRUE

• a formula containing a name or expression, x ~ mpg: scaled = TRUE

Non-standard evaluation

props uses non-standard evaluation in a slightly unusual way: if you provide a formula input, the LHS of the formula will provide the name of the component. In otherwise, props(x = y ~ 1) is the same as props(y ~ 1).

You can combine variables from the dataset and variables defined in the local environment: expressions will be evaluated in the environment which the formula was defined.

If you have the name of a variable in a string, see the props vignette for how to create the needed property mapping.

Enter, exit, hover, and update events

There are four different property events that the marks can use. These can, for example, be used to change the appearance of a mark when the mouse cursor is hovering over it: when the mark is hovered over, it uses the hover event, and when the mark isn't hovered over, it uses the update event

• enter: This event is used by marks when they are added to a plot.

• update: This event is used by marks after they have entered, and also after they have been hovered over.

• exit: This event is used by marks as they are removed from a plot.

• hover: This event is used when the mouse cursor is over the mark.

You can specify the event for a property, by putting a period and the event after the property name. For example, props(fill.update := "black", fill.hover := "red") will make a mark have a black fill normally, and red fill when it is hovered over.

The default event is update, so if you run props(fill := "red"), this is equivalent to props(fill.update := "red").

In practice, the enter and exit events are useful only when the update has a duration (and is therefore not instantaneous). The update event can be thought of as the "default" state.

Key property

In addition to the standard properties, there is a special optional property called key. This is useful for plots with dynamic data and smooth transitions: as the data changes, the key is used to tell the plot how the new data rows should be matched to the old data rows. Note that the key must be an unscaled value. Additionally, the key property doesn't have a event, since it is independent of enter, update, exit, and hover events.

Properties

You can set the following mark properties:

• x The first (typically left-most) x-coordinate.

• x2 The second (typically right-most) x-coordinate.

• width The width of the mark (if supported).

• y The first (typically top-most) y-coordinate.

• y2 The second (typically bottom-most) y-coordinate.

• height The height of the mark (if supported).

• opacity The overall opacity.

• fill The fill color.

• fillOpacity The fill opacity

• stroke The stroke color.

• strokeWidth The stroke width, in pixels.

• strokeOpacity The stroke opacity.

• size [symbol] The pixel area of the symbol. For example in the case of circles, the radius is determined in part by the square root of the size value.

• shape [symbol] The symbol shape to use. One of circle (default), square, cross, diamond, triangle-up, or triangle-down (symbol only)

• innerRadius [arc] The inner radius of the arc, in pixels.

• outerRadius [arc] The outer radius of the arc, in pixels.

• startAngle [arc] The start angle of the arc, in radians.

• endAngle [arc] The end angle of the arc, in radians.

• interpolate [area, line] The line interpolation method to use. One of linear, step-before, step-after, basis, basis-open, cardinal, cardinal-open, monotone.

• tension [area, line] Depending on the interpolation type, sets the tension parameter.

• url [image] The URL from which to retrieve the image.

• align [image, text] The horizontal alignment of the object. One of left, right, center.

• baseline [image, text] The vertical alignment of the object. One of top, middle, bottom.

• text [text] The text to display.

• dx [text] The horizontal margin, in pixels, between the text label and its anchor point. The value is ignored if the align property is center.

• dy [text] The vertical margin, in pixels, between the text label and its anchor point. The value is ignored if the baseline property is middle.

• angle [text] The rotation angle of the text, in degrees.

• font [text] The typeface to set the text in (e.g., Helvetica Neue).

• fontSize [text] The font size, in pixels.

• fontWeight [text] The font weight (e.g., bold).

• fontStyle [text] The font style (e.g., italic).

To each property, you can assign any property object (prop) either locally (i.e. in the mark), or in a parent layer.

Examples

# Set to constant values
props(x := 1, y := 2)
# Map to variables in the dataset
props(x = ~mpg, y = ~cyl)
# Set to a constant value in the data space
props(x = 1, y = 1)
# Use an interactive slider
props(opacity := input_slider(0, 1))

# To control other settings (like custom scales, mult and offset)
# use a prop object
props(prop("x", "old", scale = "x", offset = -1))

# Red when hovered over, black otherwise (these are equivalent)
props(fill := "black", fill.hover := "red")
props(fill.update := "black", fill.hover := "red")

# Use a column called id as the key (for dynamic data)
props(key := ~id)

# Explicitly create prop objects. The following are equivalent:
props(fill = ~cyl)
props(fill.update = ~cyl)
props(prop("fill", ~cyl))
props(prop("fill", ~cyl, scale = "fill", event = "update"))

# Prop objects can be programmatically created and added:
property <- "fill"
expr <- parse(text = "wt/mpg")[[1]]
p <- prop(property, expr)
props(p)

# Using .props
props(.props = list(x = 1, y = 2))
props(.props = list(x = ~mpg, y = ~cyl))
props(.props = list(quote(x := ~mpg)))