+```{r}
+f <- plotly_POST(p, filename = "r-docs/midwest-boxplots")
+class(f)
+f
```
-[Learn more about embedding graphs in HTML pages, blogs, and websites in our tutorial](http://help.plot.ly/embed-graphs-in-websites/).
+If you want more control over embedding graphs hosted on -If you want to overwrite the plot and keep the graph served from the same plotly URL, specify a filename. -This implicitly overwrites your plotly graph. -View your Plotly graphs at [https://plot.ly/organize](https://plot.ly/organize). - -```{r, message=FALSE} -plot_ly(x = c(1, 2), y = c(1, 2), filename="name-of-my-plotly-file") -``` -Overwriting your graph works a bit differently when using ```subplots```. -To update a graph with ```subplots``` use ```plotly_build()``` and then assign the ```filename```. +If you don't include a filename, a new plot will be made on your online plotly account. If you want to overwrite a plot (i.e., keep the graph served from the same plotly URL), specify a filename. This implicitly overwrites your plotly graph. -```{r, message=FALSE} -p <- plotly_build(subplot( - plot_ly(x = c(1, 2), y = c(1, 2)), - plot_ly(x = c(1, 2), y = c(2, 1)), - margin = 0.05 - ) -) -p$filename <- "overwrite_subplots" +```{r} +plotly_POST(p, filename = "name-of-my-plotly-file") ``` -Add modifications then see the updated graph at the same plotly URL: - -```{r, message=FALSE} -p <- layout(showlegend = FALSE, title = "Overwrite Subplots") -p$filename <- "overwrite_subplots" -p -``` - -
If the filename contains "/", it will automatically create a plotly folder. -```{r, message=FALSE} -plot_ly(x = c(1, 2), y = c(1, 2), filename="r-docs/name-of-my-plotly-file") +```{r} +plotly_POST(p, filename="r-docs/name-of-my-plotly-file") ``` + +View your Plotly graphs at [https://plot.ly/organize](https://plot.ly/organize). diff --git a/_posts/r/2015-07-30-get-requests.Rmd b/_posts/r/2015-07-30-get-requests.Rmd index a0cb5fcc20f2..153beff20178 100644 --- a/_posts/r/2015-07-30-get-requests.Rmd +++ b/_posts/r/2015-07-30-get-requests.Rmd @@ -19,11 +19,11 @@ Sys.setenv("plotly_username"="RPlotBot") Sys.setenv("plotly_api_key"="q0lz6r5efr") ``` -Download Plotly figures directly into R with `get_figure`. This takes the `username` and the `plot_id` as arguments. +Download Plotly figures directly into R with `get_figure()`. This takes the `username` and the `plot_id` as arguments. For example, to download [https://plot.ly/~cpsievert/559](https://plot.ly/~cpsievert/559) into R, call: -```{r, message=FALSE} +```{r} library(plotly) fig <- get_figure("cpsievert", "559") ``` @@ -31,13 +31,13 @@ fig <- get_figure("cpsievert", "559")
Once the figure is downloaded, you can edit it like any plotly object. This will create a new figure unless you specify the same filename as the figure that you downloaded. -```{r, message=FALSE} +```{r} layout(fig, title = paste("Modified on ", Sys.time())) ``` -### Adding Traces with `get_figure` and `subplot`. +### Adding Traces with `get_figure()` and `subplot()`. -After downloading a figure with subplots, use `plotly_build` to build the figure. +After downloading a figure with subplots, use `plotly_build()` to build the figure. ```{r, message=FALSE} fig <- get_figure("chelsea_lyn", "6343") diff --git a/_posts/r/2015-07-30-getting-started.Rmd b/_posts/r/2015-07-30-getting-started.Rmd index 92f198b9f961..ac0fce4bd52a 100644 --- a/_posts/r/2015-07-30-getting-started.Rmd +++ b/_posts/r/2015-07-30-getting-started.Rmd @@ -16,7 +16,7 @@ Sys.setenv("plotly_api_key"="q0lz6r5efr") # Plotly for R -Plotly is R package for creating interactive web-based graphs via [plotly](https://plot.ly/)'s JavaScript graphing library, `plotly.js`. +Plotly is R package for creating interactive web-based graphs via [plotly.js](http://plot.ly/javascript).
@@ -24,14 +24,18 @@ Plotly is R package for creating interactive web-based graphs via [plotly](https
#### Installation
-__plotly__ is not (yet) available on CRAN, but you can install it via [devtools](http://cran.r-project.org/web/packages/devtools/):
+__plotly__ is now available on CRAN!
```r
-install.packages("viridis") # dependency
-install.packages("devtools")
-devtools::install_github("ropensci/plotly")
+install.packages("plotly")
```
+You can also install the latest development version ([on GitHub](https://github.com/ropensci/plotly)) via [devtools](http://cran.r-project.org/web/packages/devtools/):
+
+```r
+# install.packages("devtools")
+devtools::install_github("ropensci/plotly")
+```
#### Signup
@@ -57,7 +61,7 @@ Save these commands in your [.Rprofile](http://www.statmethods.net/interface/cus
#### Special Instructions for Plotly On-Premise Users
-Your API key for account on the public cloud will be different than the API key in [Plotly On-Premise](https://plot.ly/product/enterprise/). Visit https://plotly.your-company.com/settings/api/ to find your Plotly On-Premise API key. Remember to replace "your-company.com" with the URL of your Plotly On-Premise server.
+Your API key for account on the public cloud will be different than the API key in [Plotly On-Premise](https://plot.ly/product/enterprise/). Visit Edit chart link on the bottom right of the chart.
-
-
+As of version 2.0, plotly's R package utilizes the [htmlwidgets](http://www.htmlwidgets.org/) framework. As a result, it's easy to embed plotly graphs in [shiny](http://shiny.rstudio.com/) apps.
-
-
### Example 1 - Plotly's Native Syntax
+The key idea is to pass a plotly object to `renderPlotly()` on the server and place it in the UI with `plotlyOutput()`.
+
#### `ui.R`
-```{r, message=FALSE}
+```{r}
library(shiny)
library(plotly)
@@ -51,7 +47,7 @@ shinyUI(fluidPage(
```
#### `server.R`
-```{r, message=FALSE}
+```{r}
library(shiny)
library(plotly)
@@ -77,8 +73,10 @@ shinyServer(function(input, output) {
### Example 2 - Render `ggplotly`
+You can also convert ggplot2 objects to plotly objects with `ggplotly()`
+
#### `ui.R`
-```{r, message=FALSE}
+```{r}
library(shiny)
library(plotly)
@@ -94,7 +92,7 @@ shinyUI(fluidPage(
```
#### `server.R`
-```{r, message=FALSE}
+```{r}
library(shiny)
library(plotly)
diff --git a/_posts/r/2015-07-30-user-guide.Rmd b/_posts/r/2015-07-30-user-guide.Rmd
index 43686930d110..f9c1443ee9b7 100644
--- a/_posts/r/2015-07-30-user-guide.Rmd
+++ b/_posts/r/2015-07-30-user-guide.Rmd
@@ -9,65 +9,96 @@ page_type: example_index
has_thumbnail: false
---
-
-```{r, echo = FALSE, message=FALSE}
-knitr::opts_chunk$set(message = FALSE)
-Sys.setenv("plotly_username"="RPlotBot")
-Sys.setenv("plotly_api_key"="q0lz6r5efr")
+```{r, echo = FALSE}
+knitr::opts_chunk$set(message = FALSE, warning = FALSE)
```
-# Plotly UseR Guide
-Version 1.0.0 of the [plotly R package](https://github.com/ropensci/plotly) introduces a new high-level interface for working with plotly's JavaScript graphing library from R. The aim of this vignette is to explain the semantics of this interface, but I also recommend perusing [plotly's R homepage](https://plot.ly/r/) for more examples.
+To create a plotly visualization, start with `plot_ly()`.
-To initiate a plotly object, use `plot_ly()`. Here we turn the `economics` data frame (from the ggplot2 package) into a plotly visualization and store it as the object `p`.
+```{r}
+library(plotly)
+plot_ly(economics, x = date, y = unemploy / pop)
+```
-```{r, message=FALSE}
+A plotly visualization is composed of one (or more) trace(s), and every trace has a `type` (the default type is 'scatter'). The arguments/properties that a trace will respect ([documented here](https://plot.ly/r/reference)) depend on it's type. A scatter trace respects `mode`, which can be any combination of "lines", "markers", "text" joined with a "+":
+
+```{r}
library(plotly)
-p <- plot_ly(economics, x = date, y = uempmed)
+plot_ly(economics, x = date, y = unemploy / pop,
+ type = "scatter", mode = "markers+lines")
+```
+
+You can manually add a trace to an existing plot with `add_trace()`. In that case, you'll want to either `name` your traces, or hide the legend by setting `showlegend = FALSE`
+
+```{r}
+m <- loess(unemploy / pop ~ as.numeric(date), data = economics)
+p <- plot_ly(economics, x = date, y = unemploy / pop, name = "raw")
+add_trace(p, y = fitted(m), name = "loess")
+```
+
+__plotly__ was designed with a [pure, predictable, and pipeable interface](https://dl.dropboxusercontent.com/u/41902/pipe-dsls.pdf) in mind, so you can also use the `%>%` operator to modify your plots:
+
+```{r}
+economics %>%
+ plot_ly(x = date, y = unemploy / pop) %>%
+ add_trace(y = fitted(m)) %>%
+ layout(showlegend = F)
```
-If you have a plotly account, printing plotly objects in the R console will create a new plotly figure, and open it in your web browser. If you're using knitr/R Markdown with HTML output (like [this vignette](https://github.com/ropensci/plotly/tree/master/vignettes/intro.Rmd)), printing not only creates the plot, but also embeds it as an HTML iframe.
+Furthermore, `plot_ly()`, `add_trace()`, and `layout()`, all accept a data frame as their first argument and output a data frame. As a result, we can inter-weave data manipulations and visual mappings in a single pipeline.
+
+```{r}
+economics %>%
+ transform(rate = unemploy / pop) %>%
+ plot_ly(x = date, y = rate) %>%
+ subset(rate == max(rate)) %>%
+ layout(
+ showlegend = F,
+ annotations = list(x = date, y = rate, text = "Peak", showarrow = T)
+ )
+```
-```{r, message=FALSE}
-p
+Although these functions output special "plotly data frames", `plot_ly()` doesn't require a data frame for input. This makes chart types that accept a `z` argument especially easy to use if you have a numeric matrix:
+
+```{r}
+plot_ly(z = volcano, type = "surface")
+plot_ly(z = volcano, type = "contour")
```
-`plot_ly()` has a number of arguments which are unique to the R package and make common visualizations a bit easier. These arguments are very much inspired by the semantics of ggplot2's `qplot()` in the sense that a scales are automatically applied these variables (i.e., they map data to visual properties).
+## Special arguments
+
+The __plotly__ function arguments used thus far are documented in [the figure reference](https://plot.ly/r/reference), but there are a handful of additional arguments not described in the reference that make common visualizations a bit easier. These arguments are very much inspired by the semantics of ggplot2's `qplot()` in the sense that a scales are automatically applied these variables.
+
+### The color argument
#### Qualitative color mappings
If a ordinal variable (aka a non-ordered factor variable) is assigned to color, then a qualitative color palette is used by default.
-```{r, message=FALSE}
-plot_ly(iris, x = Petal.Length, y = Petal.Width,
+```{r}
+plot_ly(iris, x = Petal.Length, y = Petal.Width,
color = Species, mode = "markers")
```
If you want to change the default palette, it's recommended that you provide a
-
- 
-
-
-
If you'd like more control over the mapping, you can provide a vector of colors (of appropriate length).
-```{r, message=FALSE}
+```{r}
cols <- RColorBrewer::brewer.pal(nlevels(iris$Species), "Set1")
-plot_ly(iris, x = Petal.Length, y = Petal.Width,
+plot_ly(iris, x = Petal.Length, y = Petal.Width,
color = Species, colors = cols, mode = "markers")
```
@@ -75,23 +106,23 @@ plot_ly(iris, x = Petal.Length, y = Petal.Width,
If either a numeric or an ordered factor is mapped to color, `plot_ly()` applies a sequential color scale by default.
-```{r, message=FALSE}
-plot_ly(iris, x = Petal.Length, y = Petal.Width,
+```{r}
+plot_ly(iris, x = Petal.Length, y = Petal.Width,
color = as.ordered(Species), mode = "markers")
```
In the case of continuous numeric variables, `plot_ly()` performs a linear mapping between the data and an interpolated color pallette.
-```{r, message=FALSE}
-plot_ly(iris, x = Petal.Length, y = Petal.Width,
+```{r}
+plot_ly(iris, x = Petal.Length, y = Petal.Width,
color = Sepal.Length, mode = "markers")
```
The colors argument takes arbitrary color codes of arbitrary length. Here is how we could use it to replicate the default mapping in ggplot2.
-```{r, message=FALSE}
-plot_ly(iris, x = Petal.Length, y = Petal.Width,
- color = Sepal.Length, colors = c("#132B43", "#56B1F7"),
+```{r}
+plot_ly(iris, x = Petal.Length, y = Petal.Width,
+ color = Sepal.Length, colors = c("#132B43", "#56B1F7"),
mode = "markers")
```
@@ -99,39 +130,40 @@ plot_ly(iris, x = Petal.Length, y = Petal.Width,
To obtain a diverging color mapping, just provide a diverging palette to the colors argument.
-```{r, message=FALSE}
-plot_ly(iris, x = Petal.Length, y = Petal.Width,
+```{r}
+plot_ly(iris, x = Petal.Length, y = Petal.Width,
color = Sepal.Length, colors = "PuOr", mode = "markers")
```
-#### The symbol argument
+### The symbol argument
To encode values using symbols, use the symbol argument.
-```{r, message=FALSE}
-plot_ly(iris, x = Petal.Length, y = Petal.Width,
+```{r}
+plot_ly(iris, x = Petal.Length, y = Petal.Width,
symbol = Species, mode = "markers")
```
-To change the default symbols used, use the symbols argument. [View all of the available symbol](https://plot.ly/r/reference/#marker).
+To change the default symbols used, use the symbols argument. All the valid symbol types are listed [here](https://plot.ly/r/reference/#marker).
-```{r, message=FALSE}
+```{r}
plot_ly(iris, x = Petal.Length, y = Petal.Width, mode = "markers",
symbol = Species, symbols = c("cross", "square", "triangle-down"))
```
+
### The group argument and `subplot()`
Using the group argument splits the data into different plotly "traces".
-```{r, message=FALSE}
-plot_ly(iris, x = Petal.Length, y = Petal.Width,
+```{r}
+plot_ly(iris, x = Petal.Length, y = Petal.Width,
group = Species, mode = "markers")
```
Although we haven't specified a coloring scheme, plotly will employ one on it's own default scheme. The group argument is quite powerful when used in conjunction with `subplot()` in order to anchor traces onto different axes.
-```{r, message=FALSE}
+```{r}
iris$id <- as.integer(iris$Species)
p <- plot_ly(iris, x = Petal.Length, y = Petal.Width, group = Species,
xaxis = paste0("x", id), mode = "markers")
@@ -140,62 +172,24 @@ subplot(p)
Since `subplot()` does not assume x/y axes are on a common scale, it does not impose any restrictions on the range by default. However, you can change this by pre-specifying the range of the [axis objects](https://plot.ly/r/reference/#xaxis) via the `layout()` function.
-```{r, message=FALSE}
+```{r}
p2 <- layout(
- p,
+ p,
xaxis = list(range = range(Petal.Length) + c(-0.1, 0.1)),
yaxis = list(range = range(Petal.Width) + c(-0.1, 0.1))
)
subplot(p2)
```
-The `subplot()` function creates "xaxis[0-9]" objects which inherit pre-specified properties, but you can also customize each subplot by referencing these objects in the layout
+Part of the magic of `subplot()` is that it generates axis objects with appropriate anchor and domain properties. After generating a subplot, you can always reference these axis objects to customize each plot.
-```{r, message=FALSE}
+```{r}
layout(
subplot(p2),
- yaxis2 = list(title = ""),
+ yaxis2 = list(title = ""),
yaxis3 = list(title = "")
)
```
-[See here](https://plot.ly/r/map-subplots-and-small-multiples/) for another example of using the group argument to make small multiples (with maps!).
-
-### Manually adding traces
-
-Sometimes you may want multiple traces on a plot, but have different traces from different data sources. In this case, the `add_trace()` function and it's (optional) `data` argument come in handy.
-
-```{r, message=FALSE}
-m <- loess(uempmed ~ as.numeric(date), economics)
-efit <- data.frame(date = economics$date, yhat = fitted(m))
-
-plot_ly(economics, x = date, y = uempmed, name = "observed") %>%
- add_trace(y = yhat, name = "estimated", data = efit)
-```
-
-Note that the date information carries over from the first trace to the second. In fact, by default, information from the first trace carries over to all subsequent traces unless the property is overwritten or if we set `inherit = FALSE` in `plot_ly()` (this helps [avoid repeating yourself](http://en.wikipedia.org/wiki/Don%27t_repeat_yourself)).
-
-### Mixing data manipulation and visualization verbs
-
-If you look at the structure of plotly objects, they are actually data frames with a class of plotly and a special environment attached (this environment tracks the mapping from data to visual properties).
-```{r, eval = TRUE}
-str(p <- plot_ly(economics, x = date, y = uempmed))
-```
-
-Doing this allows us to mix data manipulation and visualization verbs in a [pure(ly) functional, predictable and pipeable](https://dl.dropboxusercontent.com/u/41902/pipe-dsls.pdf) manner. Here, we take advantage of [dplyr](http://cran.r-project.org/web/packages/dplyr/index.html)'s `filter()` verb to label the highest peak in the time series:
-
-```{r, message = FALSE, warning = FALSE}
-p %>%
- add_trace(y = fitted(loess(uempmed ~ as.numeric(date)))) %>%
- layout(title = "Median duration of unemployment (in weeks)",
- showlegend = FALSE) %>%
- dplyr::filter(uempmed == max(uempmed)) %>%
- layout(annotations = list(x = date, y = uempmed, text = "Peak", showarrow = T))
-```
-
-Although data frames can be thought of as the central object in this package, plotly visualizations don't actually _require_ a data frame. This makes chart types that accept a `z` argument especially easy to use if you have a numeric matrix:
-
-```{r, message=FALSE}
-plot_ly(z = volcano, type = "surface")
-```
+[See here](https://plot.ly/r/map-subplots-and-small-multiples/) for another example of using the group argument to make small multiples (with maps!).
diff --git a/_posts/r/2015-08-10-knitr.Rmd b/_posts/r/2015-08-10-knitr.Rmd
deleted file mode 100644
index 8fd849c65578..000000000000
--- a/_posts/r/2015-08-10-knitr.Rmd
+++ /dev/null
@@ -1,52 +0,0 @@
----
-title: Using Plotly with knitr
-name: Using Plotly with knitr
-permalink: r/knitr/
-description: How to embed Plotly graphs in knitr documents.
-layout: base
-language: r
-page_type: example_index
-has_thumbnail: true
-display_as: file_settings
-order: 5
----
-
-## Embedding plotly graphs in knitr documents
-
-
-```{r, echo = FALSE, message=FALSE}
-knitr::opts_chunk$set(message = FALSE)
-Sys.setenv("plotly_username"="RPlotBot")
-Sys.setenv("plotly_api_key"="q0lz6r5efr")
-```
-
-Simply printing `plotly` objects in the R console will create a new plotly figure in your online plotly account and open your web-browser to view it.
-
-```{r, message=FALSE, height=800}
-library(plotly)
-p <- plot_ly(economics, x = date, y = uempmed, filename="r-docs/knitr-example")
-```
-
-If you are using knitr/R Markdown with HTML output, printing the `plotly` object will not only create the plot but embed it in the HTML as an iframe. This document itself is written with R Markdown, so printing `p` embeds the figure.
-
-
-```{r, message=FALSE}
-p
-```
-
-You can set the width and the height of the plot with `width` and `height` code chunk parameters. For example:
-
-`{r, height=800}`
-
-```{r, height=800}
-p
-```
-
-If you are using [Plotly Offline with R Studio](https://purchasing.plot.ly/plotly-offline-r), then printing the plotly object in knitr will also include the necessary `plotly.js` files to draw the graph: the graph is rendered locally inside the document.
-
-To convert the knitr document to a standalone HTML file, use `knitr::knit` and `markdown::markdownToHTML`. For example:
-
-```
-knitr::knit('plotly-report.Rmd', 'plotly-report.md')
-markdown::markdownToHTML('plotly-report.md', 'plotly-report.html')
-```
diff --git a/_posts/r/2015-08-10-knitr.md b/_posts/r/2015-08-10-knitr.md
deleted file mode 100644
index 36db193a4574..000000000000
--- a/_posts/r/2015-08-10-knitr.md
+++ /dev/null
@@ -1,55 +0,0 @@
----
-title: Using Plotly with knitr
-name: Using Plotly with knitr
-permalink: r/knitr/
-description: How to embed Plotly graphs in knitr documents.
-layout: base
-language: r
-page_type: example_index
-has_thumbnail: true
-display_as: file_settings
-order: 5
----
-
-## Embedding plotly graphs in knitr documents
-
-
-
-
-Simply printing `plotly` objects in the R console will create a new plotly figure in your online plotly account and open your web-browser to view it.
-
-
-```r
-library(plotly)
-p <- plot_ly(economics, x = date, y = uempmed, filename="r-docs/knitr-example")
-```
-
-If you are using knitr/R Markdown with HTML output, printing the `plotly` object will not only create the plot but embed it in the HTML as an iframe. This document itself is written with R Markdown, so printing `p` embeds the figure.
-
-
-
-```r
-p
-```
-
-
-
-You can set the width and the height of the plot with `width` and `height` code chunk parameters. For example:
-
-`{r, height=800}`
-
-
-```r
-p
-```
-
-
-
-If you are using [Plotly Offline with R Studio](https://purchasing.plot.ly/plotly-offline-r), then printing the plotly object in knitr will also include the necessary `plotly.js` files to draw the graph: the graph is rendered locally inside the document.
-
-To convert the knitr document to a standalone HTML file, use `knitr::knit` and `markdown::markdownToHTML`. For example:
-
-```
-knitr::knit('plotly-report.Rmd', 'plotly-report.md')
-markdown::markdownToHTML('plotly-report.md', 'plotly-report.html')
-```
diff --git a/_posts/r/2015-08-10-plotly-offline.html b/_posts/r/2015-08-10-plotly-offline.html
deleted file mode 100644
index 21affa86cf08..000000000000
--- a/_posts/r/2015-08-10-plotly-offline.html
+++ /dev/null
@@ -1,39 +0,0 @@
----
-permalink: /r/offline
-description: Plotly offline using the Plotly R client, ggplot2, and RStudio
-name: Plotly Offline for Plotlys R Library
-has_thumbnail: false
-thumbnail: /images/static-image
-layout: user-guide
-page_type: u-guide
-language: r
----
-{% raw %}
-
-
-
-
-{% endraw %}
-
-
-
-
-
-
- -
-Plotly Offline for RStudio and Shiny¶
NEW: Plotly's R library v.1.0 renders Plotly graphs offline in RStudio.
- -
-- -
-
-
- Since November 2 2015, Plotly R figures now appear interactively within RStudio's graphics viewer without any calls to Plotly's server by default. -
-
-
- Plotly graphics in RStudio sit on top of the HTML widgets framework. -
-
-
- When you're ready to share, you can publish your Plotly R figures to the Plotly Cloud or to your company's internal Plotly On-Premise server. -
-
-
To get started with Plotly offline in RStudio, download Plotly's free R client.
-