--- 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") ``` .