props | R Documentation |
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.
props(..., .props = NULL, inherit = TRUE, env = parent.frame())
is.ggvis_props(x)
... |
A set of name-value pairs. The name should be a valid vega property. The first two unnamed components are taken to be |
.props |
When calling |
inherit |
If |
env |
The environment in which to evaluate variable properties. |
x |
an object to test for props-ness. |
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
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.
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.
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.
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
.
# 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)))
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.