You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.Rmd
-7
Original file line number
Diff line number
Diff line change
@@ -13,11 +13,6 @@ output: github_document
13
13
14
14
An R package for creating interactive web graphics via the open source JavaScript graphing library [plotly.js](https://github.com/plotly/plotly.js).
15
15
16
-
## Announcements
17
-
18
-
Learn plotly and shiny during [our 2-day R workshop](https://plotcon.plot.ly/workshops/r-shiny-dash-r)! `r emo::ji("woman_technologist")``r emo::ji("man_technologist")``r emo::ji("chart_with_upwards_trend")`
19
-
20
-
[Read more](https://blog.cpsievert.me/2017/12/04/components-of-a-successful-r-workshop/) about [Carson](https://cpsievert.me)'s philosophy and experiences running the workshop.
21
16
22
17
## Installation
23
18
@@ -33,8 +28,6 @@ Or install the latest development version (on GitHub) via devtools:
33
28
devtools::install_github("ropensci/plotly")
34
29
```
35
30
36
-
**NOTE:** The CRAN version of **plotly** is designed to work with the CRAN version of **ggplot2**, but at least for the time being, we recommend using the development versions of both **plotly** and **ggplot2** (`devtools::install_github("tidyverse/ggplot2")`).
An R package for creating interactive web graphics via the open source JavaScript graphing library [plotly.js](https://github.com/plotly/plotly.js).
8
-
9
-
Announcements
10
-
-------------
4
+
<imgsrc="man/figures/plotly.png"width="200" />
11
5
12
-
Learn plotly and shiny during [our 2-day R workshop](https://plotcon.plot.ly/workshops/r-shiny-dash-r)! 👩💻 👨💻 📈
[Read more](https://blog.cpsievert.me/2017/12/04/components-of-a-successful-r-workshop/) about [Carson](https://cpsievert.me)'s philosophy and experiences running the workshop.
14
+
An R package for creating interactive web graphics via the open source
@@ -28,14 +29,12 @@ Or install the latest development version (on GitHub) via devtools:
28
29
devtools::install_github("ropensci/plotly")
29
30
```
30
31
31
-
**NOTE:** The CRAN version of **plotly** is designed to work with the CRAN version of **ggplot2**, but at least for the time being, we recommend using the development versions of both **plotly** and **ggplot2** (`devtools::install_github("tidyverse/ggplot2")`).
32
-
33
-
Getting started
34
-
---------------
32
+
## Getting started
35
33
36
34
### Web-based ggplot2 graphics
37
35
38
-
If you use [ggplot2](https://github.com/tidyverse/ggplot2), `ggplotly()` converts your static plots to an interactive web-based version!
36
+
If you use [ggplot2](https://github.com/tidyverse/ggplot2), `ggplotly()`
37
+
converts your static plots to an interactive web-based version\!
By default, `ggplotly()` tries to replicate the static ggplot2 version exactly (before any interaction occurs), but sometimes you need greater control over the interactive behavior. The `ggplotly()` function itself has some convenient "high-level" arguments, such as `dynamicTicks`, which tells plotly.js to dynamically recompute axes, when appropriate. The `style()` function also comes in handy for *modifying* the underlying [traces attributes](https://plot.ly/r/reference/#scatter-hoveron) used to generate the plot:
49
+
By default, `ggplotly()` tries to replicate the static ggplot2 version
50
+
exactly (before any interaction occurs), but sometimes you need greater
51
+
control over the interactive behavior. The `ggplotly()` function itself
52
+
has some convenient “high-level” arguments, such as `dynamicTicks`,
53
+
which tells plotly.js to dynamically recompute axes, when appropriate.
54
+
The `style()` function also comes in handy for *modifying* the
55
+
underlying [traces
56
+
attributes](https://plot.ly/r/reference/#scatter-hoveron) used to
Moreover, since `ggplotly()` returns a plotly object, you can apply essentially any function from the R package on that object. Some useful ones include `layout()` (for [customizing the layout](https://cpsievert.github.io/plotly_book/extending-ggplotly.html#customizing-the-layout)), `add_traces()` (and its higher-level `add_*()` siblings, for example `add_polygons()`, for [adding new traces/data](https://cpsievert.github.io/plotly_book/extending-ggplotly.html#leveraging-statistical-output)), `subplot()` (for [combining multiple plotly objects](https://cpsievert.github.io/plotly_book/merging-plotly-objects.html)), and `plotly_json()` (for inspecting the underlying JSON sent to plotly.js).
60
-
61
-
The `ggplotly()` function will also respect some "unofficial" **ggplot2** aesthetics, namely `text` (for [customizing the tooltip](https://cpsievert.github.io/plotly_book/a-case-study-of-housing-sales-in-texas.html#fig:ggsubplot)), `frame` (for [creating animations](https://cpsievert.github.io/plotly_book/key-frame-animations.html)), and `ids` (for ensuring sensible smooth transitions).
66
+
Moreover, since `ggplotly()` returns a plotly object, you can apply
67
+
essentially any function from the R package on that object. Some useful
and `ids` (for ensuring sensible smooth transitions).
62
84
63
85
### Using plotly without ggplot2
64
86
65
-
The `plot_ly()` function provides a more direct interface to plotly.js so you can leverage more specialized chart types (e.g., [parallel coordinates](https://plot.ly/r/parallel-coordinates-plot/) or [maps](https://plot.ly/r/maps/)) or even some visualization that the ggplot2 API won't ever support (e.g., surface, [mesh](https://plot.ly/r/3d-mesh/), [trisurf](https://plot.ly/r/trisurf/), or sankey diagrams). The [cheatsheet](https://images.plot.ly/plotly-documentation/images/r_cheat_sheet.pdf) is a nice quick reference for this interface, but the [plotly cookbook](https://cpsievert.github.io/plotly_book/the-plotly-cookbook.html) has more complete overview of the philosophy behind this "non-ggplot2" approach.
87
+
The `plot_ly()` function provides a more direct interface to plotly.js
88
+
so you can leverage more specialized chart types (e.g., [parallel
89
+
coordinates](https://plot.ly/r/parallel-coordinates-plot/) or
90
+
[maps](https://plot.ly/r/maps/)) or even some visualization that the
91
+
ggplot2 API won’t ever support (e.g., surface,
92
+
[mesh](https://plot.ly/r/3d-mesh/),
93
+
[trisurf](https://plot.ly/r/trisurf/), or sankey diagrams). The
The R package has special support for linking/highlighting/filtering views that is not (yet) available outside of the R package. This functionality is built upon the [**crosstalk** package](https://rstudio.github.io/crosstalk/), which distinguishes between two event classes: *select* and *filter*. The **plotly** package interprets these classes in the following way:
108
+
The R package has special support for linking/highlighting/filtering
109
+
views that is not (yet) available outside of the R package. This
110
+
functionality is built upon the [**crosstalk**
111
+
package](https://rstudio.github.io/crosstalk/), which distinguishes
112
+
between two event classes: *select* and *filter*. The **plotly** package
113
+
interprets these classes in the following way:
77
114
78
-
1.**Select**: add new "selection" trace(s) (i.e., graphical marks) and *dim* the other traces. Some people refer to this as "brushing" or "highlighting".
79
-
2.**Filter**: retain "selection" trace(s), but *remove* other traces, and update the layout accordingly. Some people refer to this as "crossfilter" or "drill-down".
115
+
1.**Select**: add new “selection” trace(s) (i.e., graphical marks) and
116
+
*dim* the other traces. Some people refer to this as “brushing” or
117
+
“highlighting”.
118
+
2.**Filter**: retain “selection” trace(s), but *remove* other traces,
119
+
and update the layout accordingly. Some people refer to this as
120
+
“crossfilter” or “drill-down”.
80
121
81
-
The following gif helps to demonstrate the difference -- see [here](http://rpubs.com/cpsievert/275511) for the code used to generate it.
122
+
The following gif helps to demonstrate the difference – see
123
+
[here](http://rpubs.com/cpsievert/275511) for the code used to generate
Like other [crosstalk enabled widgets](https://rstudio.github.io/crosstalk/widgets.html), **plotly** responds to filter events, but you can't (yet) emit a filter event via direct manipulation of a plotly graph. Unlike (some) other crosstalk enabled widgets, **plotly** has advanced support for select (a much more broad class than filter) events, like [persistent/dynamic brushing](https://cpsievert.github.io/plotly_book/linking-views-without-shiny.html#transient-versus-persistent-selection), [brushing via indirect manipulation](https://cpsievert.github.io/plotly_book/linking-views-without-shiny.html#selection-via-indirect-manipulation), and even ways to [completely control the appearance new selection traces](https://cpsievert.github.io/plotcon17/workshop/day2/#21). In other words, these "special" brushing features work when linking multiple **plotly** graphs, but may not when linking to other crosstalk enabled widgets.
86
-
87
-
To date, [this slide deck](https://cpsievert.github.io/plotcon17/workshop/day2) is the most comprehensive, yet somewhat thorough, walk-through of this framework, but the [linking views without shiny](https://cpsievert.github.io/plotly_book/linking-views-without-shiny.html) chapter of the [plotly book](https://cpsievert.github.io/plotly_book/) provides even more background. There are also numerous demos shipped with the package which provide nice examples (list all the demos via `demo(package = "plotly")`).
88
-
89
-
**plotly**'s **crosstalk** functionality aims to provide tools for interactively exploring subsets of your data with a fixed definition from data to plot. If you need more flexibility, you can always embed **crosstalk** plots within a larger **shiny** app, or even [access and respond to any plotly event within shiny](https://cpsievert.github.io/plotly_book/linking-views-with-shiny.html), but adding **shiny** into the equation comes with a cost -- the result is no longer standalone HTML (harder to share/host) and linking views requires fairly sophicated knowledge/use of shiny's reactive programming framework.
90
-
91
-
Examples and documentation
92
-
--------------------------
93
-
94
-
We have numerous online examples on <https://plot.ly/r/> and <https://plot.ly/ggplot2/>, but a more comprehensive write-up is also available at <https://plotly-book.cpsievert.me/>. The package itself ships with a number of demos (list them by running `demo(package = "plotly")`) and shiny/rmarkdown examples (list them by running `plotly_example("shiny")` or `plotly_example("rmd")`). [Carson](https://cpsievert.me) also keeps numerous [slide decks](https://talks.cpsievert.me) with useful examples and concepts.
95
-
96
-
Contributing
97
-
------------
98
-
99
-
Please read through our [contributing guidelines](https://github.com/ropensci/plotly/blob/master/CONTRIBUTING.md). Included are directions for opening issues, asking questions, contributing changes to plotly, and our code of conduct.
0 commit comments