index.Rmd

--- 
title: "plotly for R"
author: "Carson Sievert"
description: "An overview of the R package plotly"
knit: "bookdown::render_book"
bibliography: [book.bib, packages.bib]
biblio-style: apalike
link-citations: yes
url: 'http\://ropensci.github.io/plotly/'
github-repo: ropensci/plotly
twitter-handle: cpsievert
cover-image: images/plotly.png
site: bookdown::bookdown_site
documentclass: book
always_allow_html: yes
---

# Overview {-}

```{r setup, include=FALSE}
library(knitr)
opts_chunk$set(
  message = FALSE, 
  warning = FALSE, 
  comment = "#>",
  collapse = TRUE,
  cache = TRUE,
  fig.width = 6, 
  fig.asp = 0.618,
  fig.show = "hold"
)
switch(
  knitr:::pandoc_to(),
  html = opts_chunk$set(out.width = 700, out.extra = 'align:"center"'),
  pdf = opts_chunk$set(out.width = "0.5\\textwidth", fig.width = 8)
)

options(
  dplyr.print_min = 6, dplyr.print_max = 6, 
  digits = 3, htmltools.dir.version = FALSE
)
```

```{r, echo=FALSE, include=identical(knitr:::pandoc_to(), 'html'), out.width=220, out.height=245}
include_graphics('images/plotly.png')
```

This website explains and partially documents the R package **plotly**, a high-level interface to the open source JavaScript graphing library [plotly.js](https://github.com/plotly/plotly.js) (which powers [plot.ly](https://plot.ly/)). The R package already has numerous examples and documentation on <https://plot.ly/r> and <https://plot.ly/ggplot2>, but this website provides more of a cohesive narrative to help explain fundamental concepts and recent developments. By reading from start to finish, readers new to R and plotly should be able to get up and running fairly quickly. That being said, advanced R and plotly users should still find the majority of this material useful and informative. I highly recommend copying/pasting examples into your R console, and modifying them as you read along, to aid the learning process.

This work is licensed under the [Creative Commons Attribution-NonCommercial-NoDerivs 3.0](http://creativecommons.org/licenses/by-nc-nd/3.0/us/) United States License. 

## Installation {-}

If you have [R](https://cran.r-project.org/) installed, you can install the stable release of **plotly** by typing this in your R console:

```{r, eval = FALSE}
install.packages("plotly")
```

Or you can install the development release via the devtools package:

```{r, eval = FALSE}
if (!require("devtools")) install.packages("devtools")
devtools::install_github("ropensci/plotly")
```

The version of the R package used to build this site is:

```{r}
packageVersion("plotly")
```

## Get started {-}

To ensure plotly is installed correctly, try loading the package and creating this example by pasting the code inside your R console.

```{r}
library(plotly)
plot_ly(z = ~volcano)
```

```{block, type='rmdtip'}
**plotly** uses the [htmlwidget](http://www.htmlwidgets.org/) framework, which allows plots to work seamlessly and consistently in various contexts (e.g., R Markdown documents, shiny apps, inside RStudio, or any other R command prompt) without an internet connection. IPython/Jupyter notebook users should wrap plots with the `embed_notebook()` function to embed them inline inside a notebook.
```


## plot.ly for collaboration {-}

[plot.ly](https://plot.ly/) subscribers can use the `plotly_POST()` function to publish plots from R onto plotly's web platform. This platform makes it very easy to host/share your graphs, collaborate with others, and is free to use for public graphs.^[If you need privacy or customer support, [pricing options](https://plot.ly/products/cloud/)] Once a plot is hosted on your account, others may copy/fork your graph to their account (with the right permissions) using a friendly user-interface. Here is a quick demonstration of that workflow from inside RStudio:

```{block, type='rmdtip'}
As long as you can view a plot hosted on <http://plot.ly>, you can bring the data behind with plot into R via the `get_figure()` function. This makes it easy to access and modify plots created with _any_ plotly.js interface (e.g., Python, MATLAB, Julia, Scala, etc) from your R console.
```

```{r, echo = FALSE, include=identical(knitr:::pandoc_to(), 'html')}
knitr::include_graphics("http://i.imgur.com/4406JoA.gif")
```

<br />
<br />

Not only is this web-based user-interface to plotly.js useful for collaborating with others, but it is also useful for completing tasks that are cumbersome to do at the command-line. For instance, annotations can be added to any plot via a point-and-click interface:

<br />
<br />

```{r, echo = FALSE, include=identical(knitr:::pandoc_to(), 'html')}
knitr::include_graphics("http://i.imgur.com/hl5hsq2.gif")
```