props {ggvis}R Documentation

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:

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

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:

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)))

[Package ggvis version 0.4.9 Index]