Plotly for R

https://www.rdocumentation.org/packages/plotly/versions/4.12.0
Admin
This project provides comprehensive documentation for the Plotly R graphing library, enabling users...
Tokens:39,245
Snippets:373
Trust Score:9.8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Running Plotly Shiny Event Data Example

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/event_data

This example demonstrates how to run a plotly event data example within a Shiny context. It is typically used for testing and development.

```r
if (FALSE) {
plotly_example("shiny", "event_data")
}
```

--------------------------------

### Shiny Examples for plotlyProxy

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/plotlyProxy

Demonstrates how to use plotlyProxy with example Shiny applications. Requires the shiny package and an interactive session.

```R
if (require("shiny") && interactive()) {
  plotly_example("shiny", "proxy_relayout")
  plotly_example("shiny", "proxy_mapbox")
}
```

--------------------------------

### Run Plotly Examples

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/plotly_example

Use this function to run various types of examples (demos, Shiny apps, Rmd documents) bundled with the Plotly package. You can specify the type and name of the example, and optionally open the source files for editing.

```R
plotly_example(type = c("demo", "shiny", "rmd"), name, edit = TRUE, ...)
```

--------------------------------

### plotly_example

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Runs example(s) provided by Plotly.

```APIDOC
## plotly_example

### Description
Run a plotly example(s).

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### Install Plotly Package (Alternative)

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

A simple command to install the Plotly R package, often found in repository metadata.

```r
install.packages('plotly')
```

--------------------------------

### Install and Load Kaleido and Plotly

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/save_image

Installs the reticulate package and then uses it to install the 'kaleido' and 'plotly' Python packages. This is a prerequisite for using the `save_image` function.

```R
install.packages("reticulate")
library(reticulate)
use_python(install_python())
py_install(c("kaleido", "plotly"))
```

--------------------------------

### Install Plotly from CRAN

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Use this command to install the stable version of the Plotly R package from CRAN.

```r
install.packages("plotly")
```

--------------------------------

### Install Plotly Development Version from GitHub

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Install the latest development version of the Plotly R package from GitHub using the remotes package.

```r
remotes::install_github("plotly/plotly")
```

--------------------------------

### Basic Highlight Function Usage

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/highlight

Demonstrates how to use the highlight function to enable interactive brushing on a single plot. This is a foundational example for understanding selection behavior.

```R
if (FALSE) { # interactive()

# These examples are designed to show you how to highlight/brush a *single*
# view. For examples of multiple linked views, see `demo(package = "plotly")` 

d <- highlight_key(txhousing, ~city)
p <- ggplot(d, aes(date, median, group = city)) + geom_line()
gg <- ggplotly(p, tooltip = "city") 
highlight(gg, dynamic = TRUE)

# supply custom colors to the brush 
cols <- toRGB(RColorBrewer::brewer.pal(3, "Dark2"), 0.5)
highlight(gg, on = "plotly_hover", color = cols, dynamic = TRUE)

# Use attrs_selected() for complete control over the selection appearance
# note any relevant colors you specify here should override the color argument
s <- attrs_selected(
  showlegend = TRUE,
  mode = "lines+markers",
  marker = list(symbol = "x")
)

highlight(layout(gg, showlegend = TRUE), selected = s)
}
```

--------------------------------

### Configuring Animation Options for ggplotly

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/animation_opts

Demonstrates how to apply animation options to a ggplotly object, specifically setting a 1000ms transition duration. This example requires an interactive R session to run.

```r
if (interactive()) {
  p <- ggplot(txhousing, aes(month, median)) + 
    geom_line(aes(group = year), alpha = 0.3) + 
    geom_smooth() + 
    geom_line(aes(frame = year, ids = month), color = "red") + 
    facet_wrap(~ city)
 
  ggplotly(p, width = 1200, height = 900) %>%
    animation_opts(1000)
}
```

--------------------------------

### Geo-spatial Maps with add_sf or add_polygons

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/add_trace

Provides an example of creating geo-spatial maps using `add_sf()` or `add_polygons()`. This functionality is typically used for visualizing geographical data.

```R
if (FALSE) {
# use `add_sf()` or `add_polygons()` to create geo-spatial maps

```

--------------------------------

### Remove TypedArray Polyfill Example

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/remove_typedarray_polyfill

Demonstrates how to use `remove_typedarray_polyfill` to reduce the file size of an HTML widget. It compares the size of an HTML file saved with and without the polyfill.

```r
if (FALSE) {
p1 <- plot_ly()
p2 <- remove_typedarray_polyfill(p1)
t1 <- tempfile(fileext = ".html")
htmlwidgets::saveWidget(p1, t1)
file.info(t1)$size
htmlwidgets::saveWidget(p2, t1)
file.info(t1)$size
}
```

--------------------------------

### Replace marker object with style()

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/style

This example shows how to replace the entire marker object for a plot_ly() visualization using style(). Note that providing a list to 'marker' will overwrite the existing marker properties.

```R
library(plotly)

marker <- list(
  color = "red",
  line = list(
    width = 20, 
    color = "black"
 )
)
(p <- plot_ly(x = 1:10, y = 1:10, marker = marker))

# note how the entire (marker) object is replaced if a list is provided
style(p, marker = list(line = list(color = "blue")))
```

--------------------------------

### Update marker line color with style()

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/style

This example demonstrates updating a specific attribute, marker.line.color, of a plot_ly() visualization using style(). This method allows for targeted updates without replacing the entire marker object.

```R
library(plotly)

marker <- list(
  color = "red",
  line = list(
    width = 20, 
    color = "black"
 )
)
(p <- plot_ly(x = 1:10, y = 1:10, marker = marker))

# similar to plotly.js, you can update a particular attribute like so 
# https://github.com/plotly/plotly.js/issues/1866#issuecomment-314115744
style(p, marker.line.color = "blue")
```

--------------------------------

### Basic add_trace Usage

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/add_trace

Demonstrates the basic structure of initiating a Plotly object and adding traces. The `plot_ly()` function starts a visualization, and `add_trace()` can be used to specify trace types directly.

```R
p <- plot_ly(economics, x = ~date, y = ~uempmed)
p
```

```R
add_trace(p, type = "scatter", mode = "markers+lines")
```

--------------------------------

### Initialize Plotly Mapbox Object

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/plot_mapbox

Use plot_mapbox() to start a plotly-mapbox object. This function is a direct replacement for plot_ly() when working with mapbox plots.

```r
plot_mapbox(data = data.frame(), ...)
```

--------------------------------

### Add Polygons to Mapbox Plot

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/plot_mapbox

This example shows how to create a mapbox plot with polygon geometries using add_polygons(). It also demonstrates how to set the map's center based on the data's median latitude and longitude.

```r
map_data("world", "canada") %>%
  group_by(group) %>%
  plot_mapbox(x = ~long, y = ~lat) %>%
  add_polygons() %>%
  layout(
    mapbox = list(
      center = list(lat = ~median(lat), lon = ~median(long))
    )
  )
```

--------------------------------

### Convert colors for Plotly marker and line properties

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/toRGB

Shows how to use toRGB to set RGBA colors for Plotly chart elements like markers and lines. This example defines a list 'm' with color properties for a Plotly chart, ensuring color compatibility.

```r
m <- list(
  color = toRGB("red"),
  line = list(
    color = toRGB("black"), 
    width = 19
  )
)

plot_ly(x = 1, y = 1, marker = m)
```

--------------------------------

### Update multiple marker attributes with style()

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/style

This example shows how to update multiple marker attributes, specifically marker.line.width and marker.size, in a plot_ly() visualization using style(). Subsequent calls to style() will overwrite previously set attributes.

```R
library(plotly)

marker <- list(
  color = "red",
  line = list(
    width = 20, 
    color = "black"
 )
)
(p <- plot_ly(x = 1:10, y = 1:10, marker = marker))

# this clobbers the previously supplied marker.line.color
style(p, marker.line = list(width = 2.5), marker.size = 10)
```

--------------------------------

### Change Locale for Date Axes and Text

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/config

Demonstrates how to change the language locale used for rendering date axes and on-graph text, such as modebar buttons. Multiple locale examples are provided.

```r
today <- Sys.Date()
x <- seq.Date(today, today + 360, by = "day")
p <- plot_ly(x = x, y = rnorm(length(x))) %>%
  add_lines()

# japanese
config(p, locale = "ja")
# german
config(p, locale = "de")
# spanish
config(p, locale = "es")
# chinese
config(p, locale = "zh-CN")
```

--------------------------------

### orca_serve

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/orca

Launches a server for static image exporting. This function is deprecated and `save_image()` should be used instead.

```APIDOC
## orca_serve

### Description
Launches a server for static image exporting. This function is deprecated and `save_image()` should be used instead.

### Usage
```
orca_serve(
  port = 5151,
  mathjax = FALSE,
  safe = FALSE,
  request_limit = NULL,
  keep_alive = TRUE,
  window_max_number = NULL,
  quiet = FALSE,
  debug = FALSE,
  more_args = NULL,
  ...
)
```

### Arguments
* `port` (numeric) - Sets the server's port number.
* `mathjax` (boolean) - Whether or not to include MathJax (required to render TeX).
* `safe` (boolean) - Turns on safe mode: where figures likely to make browser window hang during image generating are skipped.
* `request_limit` (numeric) - Sets a request limit that makes orca exit when reached.
* `keep_alive` (boolean) - Turn on keep alive mode where orca will (try to) relaunch server if process unexpectedly exits.
* `window_max_number` (numeric) - Sets maximum number of browser windows the server can keep open at a given time.
* `quiet` (boolean) - Suppress all logging info.
* `debug` (boolean) - Starts app in debug mode and turn on verbose logs on stdout.
* `more_args` (list) - Additional arguments to pass along to system command.
* `...` - Additional arguments passed along to `processx::process`.

### Methods
The `orca_serve()` function returns an object with two methods:

* `export(p, file = "plot.png", format = tools::file_ext(file), scale = NULL, width = NULL, height = NULL)`: Export a static image of a plotly graph. Arguments found here are the same as those found in `orca()`.
* `close()`: Close down the orca server and kill the underlying node process.

### Fields
The `orca_serve()` function returns an object with two fields:

* `port` (numeric): The port number that the server is listening to.
* `process` (R6 object): An R6 class for controlling and querying the underlying node process.

### Example
```R
# NOTE: in a headless environment, you may need to set `more_args="--enable-webgl"`
# to export webgl correctly
p <- plot_ly(z = ~volcano) %>%
  add_surface()
orca(p, "surface-plot.svg")

#' # launch the server
server <- orca_serve()

# export as many graphs as you'd like
server$export(qplot(1:10), "test1.pdf")
server$export(plot_ly(x = 1:10, y = 1:10), "test2.pdf")

# the underlying process is exposed as a field, so you
# have full control over the external process
server$process$is_alive()

# convenience method for closing down the server
server$close()

# remove the exported files from disk
unlink("test1.pdf")
unlink("test2.pdf")
```
```

--------------------------------

### showRGB

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Displays colors already formatted by toRGB().

```APIDOC
## showRGB

### Description
View colors already formatted by toRGB().

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### rangeslider with custom start and end dates

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/rangeslider

Add a range slider with specified start and end values to a Plotly chart. This is useful for focusing on a specific period within the data.

```r
d <- tibble::tibble(
  time = seq(as.Date("2016-01-01"), as.Date("2016-08-31"), by = "days"),
  y = rnorm(seq_along(time))
 )

plot_ly(d, x = ~time, y = ~y) %>%
  add_lines() %>%
  rangeslider(d$time[5], d$time[50])
```

--------------------------------

### Mapping Data to Visual Attributes with add_markers() and add_paths()

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/plot_ly

Demonstrates mapping abstract data values to visual attributes like color, size, symbol, and linetype using add_markers() and add_paths().

```R
if (FALSE) {

p <- plot_ly(palmerpenguins::penguins, x = ~bill_length_mm, y = ~body_mass_g)
add_markers(p, color = ~bill_depth_mm, size = ~bill_depth_mm)
add_markers(p, color = ~species)
add_markers(p, color = ~species, colors = "Set1")
add_markers(p, symbol = ~species)
add_paths(p, linetype = ~species)

}
```

--------------------------------

### Basic Animation with Plotly

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/animation_opts

Demonstrates creating a basic animation using plot_ly and adding markers with frames defined by a variable 'z'.

```r
df <- data.frame(
  x = c(1, 2, 2, 1, 1, 2),
  y = c(1, 2, 2, 1, 1, 2),
  z = c(1, 1, 2, 2, 3, 3)
)
plot_ly(df) %>%
  add_markers(x = 1.5, y = 1.5) %>%
  add_markers(x = ~x, y = ~y, frame = ~z)
```

--------------------------------

### hide_guides

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/hide_guides

Hides guides (legends and colorbars) from a Plotly plot.

```APIDOC
## hide_guides

### Description
Hide guides (legends and colorbars)

### Usage
```
hide_guides(p)
```

### Arguments
* **p** - a plotly object.

### See Also
`hide_legend()`, `hide_colorbar()`
```

--------------------------------

### Partial Bundle Conflict Example

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/partial_bundle

Illustrates a warning: when multiple plotly graphs with different partial bundles are rendered on the same page, later bundles can override earlier ones, causing some plots not to render correctly. This example shows a heatmap (cartesian bundle) failing to render when a surface plot (gl3d bundle) is also present.

```R
library(plotly)
library(htmltools)

p1 <- plot_ly(z = ~volcano) %>% 
  add_heatmap() %>%
  partial_bundle()
p2 <- plot_ly(z = ~volcano) %>% 
  add_surface() %>%
  partial_bundle()

browsable(tagList(p1, p2))
```

--------------------------------

### Hide Guides in Plotly

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/hide_guides

Use this function to hide legends and colorbars from a plotly object. It takes a plotly object as input.

```r
hide_guides(p)
```

--------------------------------

### highlight

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Queries graphical elements in multiple linked views.

```APIDOC
## highlight

### Description
Query graphical elements in multiple linked views.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### Add SF Spatial Data

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/add_trace

Adds spatial data from the 'sf' package to a Plotly chart. Requires the 'sf' package to be installed.

```R
if (requireNamespace("sf", quietly = TRUE)) {
  nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
  plot_ly() %>% add_sf(data = nc)
}
```

--------------------------------

### Hide Colorbar in Plotly

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/hide_colorbar

Use this function to hide color bars in a Plotly object. Ensure the plotly package is installed and loaded.

```r
p <- plot_ly(mtcars, x = ~wt, y = ~cyl, color = ~cyl)
hide_colorbar(p)
```

--------------------------------

### Initiate plot_ly Visualization

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/plot_ly

This is the basic structure for initiating a plotly visualization. It sets up the environment for adding traces and defining plot attributes. Formulas are recommended for referencing column names in data frames.

```R
plot_ly(
  data = data.frame(),
  ...,
  type = NULL,
  name,
  color,
  colors = NULL,
  alpha = NULL,
  stroke,
  strokes = NULL,
  alpha_stroke = 1,
  size,
  sizes = c(10, 100),
  span,
  spans = c(1, 20),
  symbol,
  symbols = NULL,
  linetype,
  linetypes = NULL,
  split,
  frame,
  width = NULL,
  height = NULL,
  source = "A"
)
```

--------------------------------

### signup

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/signup

Creates a new Plotly account through the R console. It requires a username and email, and optionally saves the credentials.

```APIDOC
## signup

### Description
Creates a new Plotly account.

### Usage
```R
signup(username, email, save = TRUE)
```

### Arguments
* **username** (string) - Desired username.
* **email** (string) - Desired email.
* **save** (boolean) - If request is successful, should the username & API key be automatically stored as an environment variable in a .Rprofile?

### Value
* **api_key** (string) - Key to use with the API.
* **tmp_pw** (string) - Temporary password to access your Plotly account.

### Examples
```R
# You need a plotly username and API key to communicate with the plotly API.

# If you don't already have an API key, you can obtain one with a valid
# username and email via signup().
s <- signup('anna.lyst', 'anna.lyst@plot.ly')

# If you already have a username and API key, please create the following
# environment variables:
Sys.setenv("plotly_username" = "me")
Sys.setenv("plotly_api_key" = "mykey")
# You can also change the default domain if you have a plotly server.
Sys.setenv("plotly_domain" = "http://mydomain.com")

# If you want to automatically load these environment variables when you
# start R, you can put them inside your ~/.Rprofile 
# (see help(.Rprofile) for more details)
```
```

--------------------------------

### General Plotly API interaction with api()

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/api_create

Shows how to use the low-level `api()` function to list endpoints, perform searches, and retrieve account-specific information. Requires Plotly credentials for some operations.

```R
# list all the endpoints
api()
```

```R
# search the entire platform!
api("search?q=overdose")
api("search?q=plottype:pie trump fake")
```

```R
# these examples will require a user account
usr <- Sys.getenv("plotly_username", NA)
if (!is.na(usr)) {
  # your account info
  api(sprintf("users/%s", usr))
  # your folders/files
  api(sprintf("folders/home?user=%s", usr))
}
```

```R
# Retrieve a specific file
api("files/cpsievert:14681")
```

```R
# change the filename
# (note: this won't work unless you have proper credentials to the relevant account)
api("files/cpsievert:14681", "PATCH", list(filename = "toy file"))
```

```R
# Copy a file
api("files/cpsievert:14681/copy", "POST")
```

```R
# Create a folder
api("folders", "POST", list(path = "/starts/at/root/and/ends/here"))
```

--------------------------------

### Modify trace hoverinfo with style()

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/style

This example demonstrates how to remove hover information from specific traces (line and ribbon) in a Plotly visualization generated by ggplotly(). Use plotly_json() to verify the changes.

```R
library(plotly)

# style() is especially useful in conjunction with ggplotly()
# It allows you to leverage the underlying plotly.js library to change 
# the return result of ggplotly()
(p <- ggplotly(qplot(data = mtcars, wt, mpg, geom = c("point", "smooth"))))

# removes hoverinfo for the line/ribbon traces (use `plotly_json()` to verify!)
style(p, hoverinfo = "none", traces = c(2, 3))
```

--------------------------------

### Convert ggplot2 Plot to Interactive Plotly Graphic

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Converts a static ggplot2 plot to an interactive web-based version using ggplotly(). This example demonstrates creating a 2D density plot.

```r
library(plotly)
g <- ggplot(faithful, aes(x = eruptions, y = waiting)) +
  stat_density_2d(aes(fill = ..level..), geom = "polygon") + 
  xlim(1, 6) + ylim(40, 100)
ggplotly(g)
```

--------------------------------

### signup

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Creates a new Plotly account.

```APIDOC
## signup

### Description
Create a new plotly account.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### Plotting Paths with group2NA and Ordered Data

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/group2NA

Shows how to use group2NA with an 'ordered' argument to sort data by date before plotting paths, ensuring correct path rendering for each city.

```R
tx <- group2NA(txhousing, "city", ordered = "date")
plot_ly(tx, x = ~date, y = ~median) %>% add_paths()
```

--------------------------------

### Grouping and Adding Lines

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/add_trace

Illustrates how to use `group_by()` with `plot_ly()` and `add_lines()` to create separate lines for each group, with a distinct color applied to each.

```R
txhousing %>%
  group_by(city) %>%
  plot_ly(x = ~date, y = ~median) %>%
  add_lines(color = I("black"))
```

--------------------------------

### orca

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Exports static images using orca.

```APIDOC
## orca

### Description
Static image exporting via orca.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### kaleido

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/save_image

Imports kaleido into a reticulated Python session and returns a `$transform()` method for converting R plots into static images.

```APIDOC
## kaleido(...)

### Description
Imports the kaleido python package and provides an environment with methods for converting R plots into static images.

### Arguments
* **...** - Arguments passed to the underlying kaleido scope configuration.

### Value
An environment that contains:
  * `transform()`: A function to convert plots objects into static images. This function has the same signature as `save_image()`.
  * `shutdown()`: A function for shutting down any currently running subprocesses that were launched via `transform()`.
  * `scope`: A reference to the underlying `kaleido.scopes.plotly.PlotlyScope` python object. Modify this object to customize the underlying Chromium subprocess and/or configure other details such as URL to plotly.js, MathJax, etc.
```

--------------------------------

### Basic Partial Bundle Usage

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/partial_bundle

Demonstrates a 3x file size reduction for a single plotly graph using `partial_bundle`. This is safe for individual plots.

```R
library(plotly)

p <- plot_ly(x = 1:10, y = 1:10) %>% add_markers()

save_widget <- function(p, f) {
  owd <- setwd(dirname(f))
  on.exit(setwd(owd))
  htmlwidgets::saveWidget(p, f)
  mb <- round(file.info(f)$size / 1e6, 3)
  message("File is: ", mb, " MB")
}

f1 <- tempfile(fileext = ".html")
f2 <- tempfile(fileext = ".html")

save_widget(p, f1)
save_widget(partial_bundle(p), f2)
```

--------------------------------

### Add Pie Chart

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/add_trace

Adds a pie chart to visualize proportions of a whole. Requires data with labels and corresponding values.

```R
ds <- data.frame(labels = c("A", "B", "C"), values = c(10, 40, 60))
plot_ly(ds, labels = ~labels, values = ~values) %>%
  add_pie() %>%
  layout(title = "Basic Pie Chart using Plotly")
```

--------------------------------

### toWebGL

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Converts trace types to WebGL for Plotly visualizations.

```APIDOC
## toWebGL

### Description
Convert trace types to WebGL.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### Basic Mapbox Plot with Data

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/plot_mapbox

Demonstrates a basic mapbox plot using plot_mapbox() with a data frame. The color aesthetic can be mapped to a variable in the data.

```r
plot_mapbox(res_mn)
plot_mapbox(res_mn, color = ~INDRESNAME)
```

--------------------------------

### api_create() function signature

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/api_create

Shows the different method signatures for `api_create()` based on the type of R object being passed (plotly, ggplot, data.frame).

```R
api_create(
  x = last_plot(),
  filename = NULL,
  fileopt = c("overwrite", "new"),
  sharing = c("public", "private", "secret"),
  ...
)
# S3 method for plotly
api_create(
  x = last_plot(),
  filename = NULL,
  fileopt = "overwrite",
  sharing = "public",
  ...
)
# S3 method for ggplot
api_create(
  x = last_plot(),
  filename = NULL,
  fileopt = "overwrite",
  sharing = "public",
  ...
)
# S3 method for data.frame
api_create(x, filename = NULL, fileopt = "overwrite", sharing = "public", ...)
```

--------------------------------

### Trellis displays with group_by() and subplot()

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/plotly_data

Illustrates creating trellis displays (multiple plots in one) by grouping data with group_by(), plotting with plot_ly(), and arranging with subplot().

```R
# use group_by() + do() + subplot() for trellis displays 
d <- group_by(mpg, drv)
plots <- do(d, p = plot_ly(., x = ~cty, name = ~drv))
subplot(plots[["p"]], nrows = 3, shareX = TRUE)
```

--------------------------------

### print.api

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Print method for a generic API response.

```APIDOC
## print.api

### Description
Print method for a 'generic' API response.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### Basic plotly_data usage

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/plotly_data

Demonstrates how to use plotly_data() to retrieve data from a plotly object, especially after data grouping.

```R
# use group_by() to define groups of visual markings
p <- txhousing %>%
  group_by(city) %>%
  plot_ly(x = ~date, y = ~sales)
p

# plotly objects preserve data groupings 
groups(p)
plotly_data(p)
```

--------------------------------

### Plotly API utility functions

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/api_create

Signatures for `api_download_plot()`, `api_download_grid()`, and the general `api()` function for interacting with the Plotly REST API.

```R
api_download_plot(id, username)
api_download_grid(id, username)
api(endpoint = "/", verb = "GET", body = NULL, ...)
```

--------------------------------

### api

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/api_create

Provides a low-level interface for performing any action at any API endpoint. It returns a list containing the response from the API.

```APIDOC
## General API Interaction

### Description
This function allows for direct interaction with any Plotly REST API endpoint using specified HTTP verbs and request bodies.

### Method
Any HTTP verb (GET, POST, PATCH, etc.)

### Endpoint
Any valid Plotly API endpoint. For a list of available endpoints, call `api()` without arguments.

### Parameters
#### Path Parameters
None

#### Query Parameters
- **endpoint** (string) - Required - The specific API endpoint to interact with. Query parameters can be appended here.

#### Request Body
- **verb** (string) - Required - The HTTP verb to use for the request (e.g., 'GET', 'POST', 'PATCH').
- **body** (object) - Optional - The body of the HTTP request, typically a JSON object. If not already a JSON string, it will be converted using `jsonlite::toJSON()`.
- **...** - Optional - Additional arguments passed to `httr::RETRY()` for request handling.

### Request Example
```json
{
  "endpoint": "/search?q=overdose",
  "verb": "GET"
}
```

### Response
#### Success Response (200)
- **response_data** (list) - A list containing the parsed response from the API.

#### Response Example
```json
{
  "response_data": [
    { ... }
  ]
}
```
```

--------------------------------

### Exporting a Surface Plot with Orca

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/orca

Demonstrates how to export a 3D surface plot using the 'orca' function. It's recommended to set `more_args="--enable-webgl"` in headless environments for correct WebGL rendering. This function is deprecated; use `save_image()` instead.

```R
if (FALSE) {
# NOTE: in a headless environment, you may need to set `more_args="--enable-webgl"`
# to export webgl correctly
p <- plot_ly(z = ~volcano) %>% add_surface()
orca(p, "surface-plot.svg")

#' # launch the server
server <- orca_serve()

# export as many graphs as you'd like
server$export(qplot(1:10), "test1.pdf")
server$export(plot_ly(x = 1:10, y = 1:10), "test2.pdf")

# the underlying process is exposed as a field, so you
# have full control over the external process
server$process$is_alive()

# convenience method for closing down the server
server$close()

# remove the exported files from disk
unlink("test1.pdf")
unlink("test2.pdf")
}
```

--------------------------------

### Upload R objects to Plotly using api_create()

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/api_create

Demonstrates uploading a data frame and a plotly object to your Plotly account using `api_create()`. This function returns metadata about the uploaded file.

```R
# A data frame creates a plotly "grid". Printing one will take you 
# to the it's web address so you can start creating!
(m <- api_create(mtcars))

# A plotly/ggplot2 object create a plotly "plot".
p <- plot_ly(mtcars, x = ~factor(vs))
(r <- api_create(p))
```

```R
# api_create() returns metadata about the remote "file". Here is
# one way you could use that metadata to download a plot for local use:
fileID <- strsplit(r$file$fid, ":")[[1]]
layout(
  api_download_plot(fileID[2], fileID[1]),
  title = sprintf("Local version of this plot", r$file$web_url)
)
```

--------------------------------

### Plotly Image Creation

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/plotly_IMAGE

Demonstrates how to create static images (PNG, JPEG, SVG, PDF) from a Plotly plot object using the plotly_IMAGE function. Specify the desired format and output filename.

```r
if (FALSE) {
p <- plot_ly(x = 1:10)
Png <- plotly_IMAGE(p, out_file = "plotly-test-image.png")
Jpeg <- plotly_IMAGE(p, format = "jpeg", out_file = "plotly-test-image.jpeg")
Svg <- plotly_IMAGE(p, format = "svg",  out_file = "plotly-test-image.svg")
Pdf <- plotly_IMAGE(p, format = "pdf",  out_file = "plotly-test-image.pdf")
}
```

--------------------------------

### config

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Sets the default configuration for Plotly.

```APIDOC
## config

### Description
Set the default configuration for plotly.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### Shiny Bindings for Plotly

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/plotly-shiny

Use `plotlyOutput` to create a placeholder for a Plotly chart in a Shiny UI and `renderPlotly` to render the Plotly chart in a Shiny server. Ensure the outputId matches between the UI and server.

```R
plotlyOutput(
  outputId,
  width = "100%",
  height = "400px",
  inline = FALSE,
  reportTheme = TRUE,
  fill = !inline
)
renderPlotly(expr, env = parent.frame(), quoted = FALSE)
```

--------------------------------

### bbox Function Usage

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/bbox

This snippet shows the basic usage of the bbox function, including its default parameters for text, angle, and size.

```r
bbox(txt = "foo", angle = 0, size = 12)
```

--------------------------------

### api_create

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Tools for working with Plotly's REST API (v2).

```APIDOC
## api_create

### Description
Tools for working with plotly's REST API (v2).

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### Basic Schema Acquisition

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/schema

Acquires the Plotly plot schema. Use `jsonedit = interactive()` to view the schema using `listviewer::jsonedit` if running interactively.

```r
s <- schema()
```

--------------------------------

### print.api_grid_local

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Prints a Plotly grid object.

```APIDOC
## print.api_grid_local

### Description
Print a plotly grid object.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### Efficiently Save Multiple Images with Kaleido Scope

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/save_image

Shows an efficient method for saving multiple images by first obtaining a 'kaleido' scope. The `transform` method of the scope is then used in a loop to save the same plot to the same file multiple times. Remember to clean up the scope using `rm(scope); gc()` afterwards.

```R
scope <- kaleido()
for (i in 1:5) {
  scope$transform(p, tmp)
}
# Remove and garbage collect to remove 
# R/Python objects and shutdown subprocesses
rm(scope); gc()
```

--------------------------------

### Arranging displays by mean with dplyr joins and subplot

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/plotly_data

Demonstrates arranging plots based on calculated means using dplyr::left_join and subplot for visualization.

```R
# arrange displays by their mean
means <- summarise(d, mn = mean(cty, na.rm = TRUE))
means %>%
  dplyr::left_join(plots) %>%
  arrange(mn) %>%
  subplot(nrows = NROW(.), shareX = TRUE)
```

--------------------------------

### Retrieve and Display Mapbox Style Values

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/schema

Retrieves acceptable `layout.mapbox.style` values from the schema and displays two different mapbox styles using `plot_mapbox` and `layout`. Requires a `MAPBOX_TOKEN` environment variable to be set.

```r
# retrieve acceptable `layout.mapbox.style` values
if (!is.na(Sys.getenv('MAPBOX_TOKEN', NA))) {
  styles <- s$layout$layoutAttributes$mapbox$style$values
  subplot(
    plot_mapbox() %>% layout(mapbox = list(style = styles[3])),
    plot_mapbox() %>% layout(mapbox = list(style = styles[5]))
  )
}
```

--------------------------------

### toRGB

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Converts R colors to RGBA hexadecimal color values.

```APIDOC
## toRGB

### Description
Convert R colours to RGBA hexadecimal colour values.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### highlight_key

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Highlights or queries data based on a primary key.

```APIDOC
## highlight_key

### Description
Highlight/query data based on primary key.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### mic

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Handles mic data.

```APIDOC
## mic

### Description
Mic data.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### Specialized add_* Functions

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/add_trace

Illustrates how specialized functions like `add_markers()`, `add_text()`, `add_paths()`, and `add_lines()` are specific cases of trace types, offering a more direct syntax for common plot elements.

```R
add_markers(p)
```

```R
add_text(p, text = "%" )
```

```R
add_paths(p)
```

```R
add_lines(p)
```

--------------------------------

### Plotly Main Interface (Deprecated)

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/plotly

This function is deprecated and was used to store plotly account credentials. Credential storage is now handled via environment variables. Refer to the plotly R documentation for current methods.

```r
plotly(username, key)
```

--------------------------------

### print.api_grid

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Prints a Plotly grid object.

```APIDOC
## print.api_grid

### Description
Print a plotly grid object.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### TeX

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Renders TeX expressions in a Plotly graph using MathJax.

```APIDOC
## TeX

### Description
Render TeX in a plotly graph using MathJax.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### View Colors Formatted by toRGB()

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/showRGB

Use this function to view colors after they have been converted to the plotly.js color format. It requires the `toRGB()` function to format the colors first.

```r
showRGB(toRGB(colors()), labels = FALSE)
```

--------------------------------

### Create Surface Plot with plot_ly()

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Demonstrates using the plot_ly() function for a direct interface to plotly.js, creating a surface plot from the volcano dataset.

```r
plot_ly(z = ~volcano, type = "surface")
```

--------------------------------

### Usage of mutate and related functions

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/mutate

These are the usage signatures for mutate and related functions imported from other packages. They define how to apply transformations and selections to data frames.

```r
mutate(.data, ...)
mutate_(.data, ..., .dots = list())
transmute(.data, ...)
transmute_(.data, ..., .dots = list())
select(.data, ...)
select_(.data, ..., .dots = list())
rename(.data, ...)
rename_(.data, ..., .dots = list())
group_by(.data, ..., .add = FALSE, .drop = group_by_drop_default(.data))
group_by_(.data, ..., .dots = list(), add = FALSE)
groups(x)
ungroup(x, ...)
summarise(.data, ..., .by = NULL, .groups = NULL)
summarise_(.data, ..., .dots = list())
do(.data, ...)
do_(.data, ..., .dots = list())
arrange(.data, ..., .by_group = FALSE)
arrange_(.data, ..., .dots = list())
distinct(.data, ..., .keep_all = FALSE)
distinct_(.data, ..., .dots, .keep_all = FALSE)
slice(.data, ..., .by = NULL, .preserve = FALSE)
slice_(.data, ..., .dots = list())
filter(.data, ..., .by = NULL, .preserve = FALSE)
filter_(.data, ..., .dots = list())
```

--------------------------------

### plot_ly

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Initiates a Plotly visualization.

```APIDOC
## plot_ly

### Description
Initiate a plotly visualization.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### export

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Exports a Plotly graph to a static file.

```APIDOC
## export

### Description
Export a plotly graph to a static file.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### Define Selection Trace Attributes

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/attrs_selected

Use attrs_selected to set the opacity and other attributes for selection traces. The name of the selection trace defaults to the selected values.

```R
attrs_selected(opacity = 1, ...)
```

--------------------------------

### plot_mapbox

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Initiates a Plotly-Mapbox object.

```APIDOC
## plot_mapbox

### Description
Initiate a plotly-mapbox object.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### bbox

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Estimates the bounding box of a rotated string.

```APIDOC
## bbox

### Description
Estimate bounding box of a rotated string.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### print.kaleidoScope

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Print method for kaleidoScope objects.

```APIDOC
## print.kaleidoScope

### Description
Print method for kaleido.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### api_download_grid

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/api_create

Downloads a specific data grid from your Plotly account using its file ID and username.

```APIDOC
## GET /v2/grids/{username}/{fileid}

### Description
Downloads a specific data grid from a Plotly account.

### Method
GET

### Endpoint
/v2/grids/{username}/{fileid}

### Parameters
#### Path Parameters
- **id** (string) - Required - The filename ID of the grid to download.
- **username** (string) - Required - The Plotly username associated with the file.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **grid_data** (object) - The data of the grid in a format suitable for local use.

#### Response Example
```json
{
  "grid_data": { ... }
}
```
```

--------------------------------

### plotly-shiny

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0

Provides Shiny bindings for Plotly.

```APIDOC
## plotly-shiny

### Description
Shiny bindings for plotly.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)
```

--------------------------------

### Display Mic Data

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/mic

This snippet shows how to access and display the 'mic' dataset. The dataset is a data frame with three variables: 'r', 't', and 'nms'.

```R
mic
```

--------------------------------

### Access res_mn Dataset

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/res_mn

This snippet shows how to access the res_mn dataset. The dataset is an sf data frame with 13 features and 5 fields.

```r
res_mn
```

--------------------------------

### Create Subplots with Multiple Plotly Objects

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/subplot

Demonstrates how to arrange multiple plotly objects into a grid using the subplot function. Specify the number of rows and margin for layout customization.

```R
p1 <- plot_ly(economics, x = ~date, y = ~uempmed)
p2 <- plot_ly(economics, x = ~date, y = ~unemploy)
subplot(p1, p2, p1, p2, nrows = 2, margin = 0.05)
```

--------------------------------

### Add 2D Histogram and Contour

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/add_trace

Adds 2D histogram or contour plots to visualize the density of two numerical variables. Requires the 'MASS' package.

```R
library(MASS)
(p <- plot_ly(geyser, x = ~waiting, y = ~duration))
add_histogram2d(p)
add_histogram2dcontour(p)
```

--------------------------------

### Inferring Trace Type with plot_ly()

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/plot_ly

Demonstrates how plot_ly() infers trace types when not explicitly provided. It also shows how to create plots with numeric matrices.

```R
if (FALSE) {

# plot_ly() tries to create a sensible plot based on the information you 
# give it. If you don't provide a trace type, plot_ly() will infer one.
plot_ly(economics, x = ~pop)
plot_ly(economics, x = ~date, y = ~pop)
# plot_ly() doesn't require data frame(s), which allows one to take 
# advantage of trace type(s) designed specifically for numeric matrices
plot_ly(z = ~volcano)
plot_ly(z = ~volcano, type = "surface")

}
```

--------------------------------

### Create a new Plotly account

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/signup

Use this function to create a new Plotly account if you do not already have one. It requires a desired username and email address.

```R
if (FALSE) {
# You need a plotly username and API key to communicate with the plotly API.

# If you don't already have an API key, you can obtain one with a valid
# username and email via signup().

s <- signup('anna.lyst', 'anna.lyst@plot.ly')

# If you already have a username and API key, please create the following
# environment variables:
Sys.setenv("plotly_username" = "me")
Sys.setenv("plotly_api_key" = "mykey")
# You can also change the default domain if you have a plotly server.
Sys.setenv("plotly_domain" = "http://mydomain.com")

# If you want to automatically load these environment variables when you
# start R, you can put them inside your ~/.Rprofile 
# (see help(.Rprofile) for more details)

}

```

--------------------------------

### Highlight Key Function Signature

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/highlight_key

This is the basic usage signature for the highlight_key function. It takes a plotly visualization or a data.frame as input and accepts additional arguments passed to crosstalk::SharedData$new().

```r
highlight_key(x, ...)
```

--------------------------------

### Accessing Wind Data

Source: https://www.rdocumentation.org/packages/plotly/versions/4.12.0/topics/wind

This snippet shows how to access the 'wind' dataset. It is a data frame with three variables: 'r', 't', and 'nms'.

```r
wind
```
Tokens:
Raw