diff --git a/r/2015-07-30-getting-started.Rmd b/r/2015-07-30-getting-started.Rmd index 2f12eabc..04619dd1 100644 --- a/r/2015-07-30-getting-started.Rmd +++ b/r/2015-07-30-getting-started.Rmd @@ -1,7 +1,7 @@ --- name: Getting Started with Plotly permalink: r/getting-started/ -description: Get started with Plotly's graphing library +description: How to get started making charts with Plotly's R graphing library. page_type: example_index layout: base language: r @@ -16,130 +16,48 @@ knitr::opts_chunk$set(message = FALSE, warning=FALSE) # Getting Started with Plotly for R -Plotly is an R package for creating interactive web-based graphs via the open source JavaScript graphing library [plotly.js](http://plot.ly/javascript). -As of version 2.0 (November 17, 2015), Plotly graphs are rendered *locally* through the [htmlwidgets](http://www.htmlwidgets.org/) framework. +[`plotly`](https://github.com/ropensci/plotly) is an R package for creating interactive web-based graphs via the open source JavaScript graphing library [`plotly.js`](http://plot.ly/javascript). +As of version 2.0 (November 17, 2015), graphs created with the `plotly` R package are rendered *locally* through the [`htmlwidgets`](http://www.htmlwidgets.org/) framework. -#### Installation +## Installation -Plotly is now on CRAN! +### Download from CRAN -```r -install.packages("plotly") -``` - -Or install the latest development version (on GitHub) via devtools: +Use the `install.package()` function to install the [`plotly R package`](https://cran.r-project.org/web/packages/plotly/index.html) from [CRAN](https://cran.r-project.org/! ```r -devtools::install_github("ropensci/plotly") +install.packages("plotly") ``` -
-RStudio users should download the latest [RStudio release](https://www.rstudio.com/products/rstudio/download/) for compatibility with htmlwidgets. +### Download from GitHub -#### Initialization for Offline Plotting - -By default, Plotly for R runs locally in your web browser or in the R Studio viewer. +Alternatively, you can install the latest development version of `plotly` from GitHub via the [`devtools`](https://cran.r-project.org/web/packages/devtools/index.html) R package: ```r -library(plotly) -p <- plot_ly(midwest, x = ~percollege, color = ~state, type = "box") -p +devtools::install_github("ropensci/plotly") ``` -Simply printing the Plotly object will render the chart locally in your web browser or in the R Studio viewer. +### Note For `RStudio` Users - +`RStudio` users should ensure that they are using the latest [RStudio release](https://www.rstudio.com/products/rstudio/download/) in order to ensure compatibility with the `htmlwidgets` R package. -Plotly graphs are interactive. Click on legend entries to toggle traces, click-and-drag on the chart to zoom, double-click to autoscale, shift-and-drag to pan. +## Rendering Charts -#### Initialization for Online Plotting +By default, the `plotly` R package runs locally in your web browser or in the `RStudio` viewer. -You can publish your charts to the web with Plotly's web service. - -1 - [Create a free Plotly account](https://plot.ly/api_signup):
-A Plotly account is required to publish charts online. It's free to get started, and you control the privacy of your charts. - -2 - Save your authentication credentials
-Find your authentication API keys [in your online settings](https://plot.ly/settings/api). Set them in your R session with: - -```r -Sys.setenv("plotly_username"="your_plotly_username") -Sys.setenv("plotly_api_key"="your_api_key") -``` - -Save these commands in your [.Rprofile](http://www.statmethods.net/interface/customizing.html) file to be run every time you start R. - -3 - Publish your graphs to Plotly with `api_create` - -Use `filename` to title the file in your Plotly account. - -```r +```{r} library(plotly) p <- plot_ly(midwest, x = ~percollege, color = ~state, type = "box") -api_create(p, filename = "r-docs-midwest-boxplots") -``` - -4 (optional) - Suppress auto open - -When following the instructions above, `api_create(p)` will auto open the created URL in the browser. To suppress this behavior, you can update your browser options in R: - -```r -options(browser = 'false') -api_create(p, filename = "r-docs-midwest-boxplots") -``` - -#### Special Instructions for Chart Studio Enterprise Users - -Your API key for account on the public cloud will be different than the API key in [Chart Studio Enterprise](https://plot.ly/product/enterprise/). Visit to find your Chart Studio Enterprise API key. Remember to replace "your-company.com" with the URL of your Chart Studio Enterprise server. - -If your company has a Chart Studio Enterprise server, change the R API endpoint so that it points to your company's Plotly server instead of Plotly's cloud. - -In your .RProfile write: - -```r -Sys.setenv("plotly_domain"="https://plotly.your-company.com") +p ``` -Remember to replace "your-company" with the URL of your Chart Studio Enterprise server. - -
- Make your first graph -
- -#### Online Plot Privacy - -Plots can be set to three different type of privacies: public, private or secret. - -* **public:** +Simply printing the plot object will render the chart locally in your web browser or in the `RStudio` viewer. - Anyone can view this graph. It will appear in your profile - and can appear in search engines. You do not need to be - logged in to Plotly to view this chart. +Graphs created with the `plotly` R package are interactive! -* **private:** +Click on legend entries to hide/show traces, click-and-drag on the chart to zoom, double-click to autoscale, shift-and-drag to pan. - Only you can view this plot. It will not appear in the - Plotly feed, your profile, or search engines. You must be - logged in to Plotly to view this graph. You can privately - share this graph with other Plotly users in your online - Plotly account and they will need to be logged in to - view this plot. This option is only available for Personal - and Professional subscribers. +## Next Steps -* **secret:** - - Anyone with this secret link can view this chart. It will - not appear in the Plotly feed, your profile, or search - engines. If it is embedded inside a webpage or an IPython - notebook, anybody who is viewing that page will be able to - view the graph. You do not need to be logged in to view - this plot. This option is only available for Personal - and Professional subscribers. - -By default all plots are set to public. Users with a free account are limited to creating public plots. If you have private storage needs, please visit [Plotly products page](https://plot.ly/products). If you're a [Personal or Professional USER](https://plot.ly/settings/subscription/?modal=true&utm_source=api-docs&utm_medium=support-oss) and would like the setting for your plots to be private, you can specify sharing as private: - -```r -api_create(filename = "private-graph", sharing = "private") -``` -For more examples on privacy settings please visit [R privacy documentation](https://plot.ly/r/privacy/) +Once you have installed the `plotly` R package, learn more about the [fundamentals of making charts](https://plot.ly/r/plotly-fundamentals/) and start making [basic charts](https://plot.ly/r/basic-charts/). \ No newline at end of file