---
title: "Get started"
output: html_document
vignette: >
%\VignetteIndexEntry{Start}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
message = FALSE,
warning = FALSE
)
```
`D3.js` can draw almost any chart, but it has a steep learning curve and asks for some `HTML`, `CSS` and `JavaScript`. `ddplot` wraps a collection of `D3` charts in plain `R` functions: you pass a data frame and column names, and you get an interactive SVG graphic that works in the RStudio viewer, R Markdown, Quarto and Shiny.
`ddplot` is built on the [r2d3](https://rstudio.github.io/r2d3/) package, which does the heavy lifting of connecting `R` and `D3`. Thanks to its developers.
## Installation
```{r, eval = FALSE}
# From CRAN
install.packages("ddplot")
# Development version from GitHub
remotes::install_github("feddelegrand7/ddplot")
```
```{r setup}
library(ddplot)
```
## Your first charts
Every function takes a data frame and the names of the columns to plot, as strings.
### A time series
`line_chart()` accepts a `ts` object directly. Hover over the chart to read the values, drag on it to zoom, or use the range buttons and the navigator below it:
```{r}
line_chart(AirPassengers, y = "passengers", title = "Airline passengers, 1949-1960")
```
A multivariate `ts` gives one line per column. With a data frame, give the date column as `x` and one or several value columns as `y` (or a single value column and a `group` column):
```{r}
line_chart(
EuStockMarkets,
transform = "index",
title = "European stock indices",
subtitle = "Rebased to 100 at the first visible date; zoom in to move the base"
)
```
### Comparing categories
Bar charts expect one row per category. Aggregate first, for instance with `dplyr`:
```{r}
library(dplyr)
library(ggplot2) # for the mpg data
mpg %>%
group_by(manufacturer) %>%
summarise(mean_cty = mean(cty)) %>%
bar_chart(
x = "manufacturer",
y = "mean_cty",
sort = "descending",
fill = "#4269d0",
ytitle = "Average city miles per gallon",
title = "City fuel economy by manufacturer"
)
```
### A relationship
```{r}
scatter_plot(
data = mpg,
x = "displ",
y = "hwy",
col = "#4269d0",
size = 4,
xtitle = "Engine displacement (litres)",
ytitle = "Highway miles per gallon",
title = "Bigger engines, fewer miles"
)
```
## Arguments shared by most charts
The functions share a common vocabulary, so what you learn on one chart carries over to the others:
| Argument | What it does |
|---|---|
| `data`, `x`, `y` | The data frame and the columns to plot, given as strings |
| `title`, `titleFontSize` | Chart title and its size in pixels |
| `xtitle`, `ytitle` | Axis titles |
| `fill`, `stroke`, `strokeWidth`, `col` | Colours and outlines of the marks |
| `bgcol`, `axisCol` | Background and axis colours |
| `font` | Font family, for example `"Georgia, serif"` |
| `xticks`, `yticks` | Approximate number of ticks on each axis |
| `width`, `height` | Size of the widget, passed to `r2d3::r2d3()` |
Each function's help page lists its full set of options, for example `?line_chart`.
## Find the right chart
`ddplot` has more than 40 chart types. The [gallery](https://feddelegrand7.github.io/ddplot/articles/gallery.html) shows all of them, and the guides below walk through each one with examples, starting with the charts you are most likely to need:
| Guide | Charts |
|---|---|
| [Time series and trends](https://feddelegrand7.github.io/ddplot/articles/time-series.html) | `line_chart()`, `area_chart()`, `stacked_area_chart()`, `area_band()`, `streamgraph()`, `calendar_heatmap()`, `anim_line_chart()` |
| [Comparing categories](https://feddelegrand7.github.io/ddplot/articles/comparisons.html) | `bar_chart()`, `horz_bar_chart()`, `lollipop_chart()`, `horz_lollipop()`, `dumbbell_chart()`, `slope_chart()`, `bump_chart()`, `waterfall_chart()`, `radar_chart()`, `radial_bar_chart()`, `bar_chart_race()` |
| [Distributions](https://feddelegrand7.github.io/ddplot/articles/distributions.html) | `histogram()`, `violin_plot()`, `beeswarm_plot()`, `ridgeline_plot()`, `animated_histogram()` |
| [Relationships and flows](https://feddelegrand7.github.io/ddplot/articles/relationships.html) | `scatter_plot()`, `hexbin_plot()`, `chord_diagram()` |
| [Part-to-whole and hierarchies](https://feddelegrand7.github.io/ddplot/articles/composition.html) | `pie_chart()`, `treemap_chart()`, `waffle_chart()`, `sunburst_chart()`, `mosaic_chart()`, `rose_chart()`, `parliament_chart()` |
| [KPIs and monitoring](https://feddelegrand7.github.io/ddplot/articles/kpis.html) | `gauge_chart()`, `bullet_chart()`, `liquid_chart()`, `pulse_grid()` |
| [Playful indicators](https://feddelegrand7.github.io/ddplot/articles/playful.html) | `heart_fill()`, `glass_fill()`, `plant_growth()`, `flame()`, `flower()` |
## Using `ddplot` in Shiny
Every `ddplot` chart is an `r2d3` htmlwidget, so in a `Shiny` app you can use `r2d3::d3Output()` in the UI and `r2d3::renderD3()` in the server. When an input changes, the chart is redrawn in place with the new data and options. Interactive state, such as the zoom of a `line_chart()` or the series hidden from its legend, is kept between updates.
```{r, eval = FALSE}
library(shiny)
library(ddplot)
library(r2d3)
ui <- fluidPage(
h2("Example ddplot application"),
selectInput(
inputId = "colors",
label = "Point color",
choices = colors(),
selected = "springgreen3"
),
sliderInput(
inputId = "slider",
label = "Point size",
min = 1,
max = 10,
value = 3
),
d3Output("scatter", height = "450px")
)
server <- function(input, output) {
output$scatter <- renderD3({
scatter_plot(
data = iris,
x = "Sepal.Length",
y = "Sepal.Width",
size = input$slider,
col = input$colors
)
})
}
shinyApp(ui = ui, server = server)
```
## Saving a chart
A chart is an htmlwidget, so it can be saved as a standalone HTML file:
```{r, eval = FALSE}
chart <- line_chart(AirPassengers, y = "passengers")
htmlwidgets::saveWidget(chart, "airpassengers.html")
```
.