# Getting Started

    library(ddplot)

Start.R

`D3.js` is a famous JavaScript library that allows one to create extremely flexible SVG graphics however `D3` has (at least according to me) a pretty steep learning curve. Further, in order to understand some core concepts, one need to have some basics in `HTML`, `CSS` and `JavaScript`. `ddplot` aims to simply the process using a set of functions that render several graphics using a simple `R` API. Finally, `ddplot` is built upon the amazing `r2d3` package which makes it a breeze to interface `D3.js` with `R`, so a big thanks to the developers.

# `scatterPlot()`

Let’s work with the `mpg` data frame from the `ggplot2` package.

    library(ggplot2) # needed for the mpg data frame

    scatterPlot(
      data = mpg,
      x = "hwy",
      y = "cty",
      xtitle = "hwy variable",
      ytitle = "cty variable",
      title = "cty and hwy relationship",
      titleFontSize = 20
    )

Start.R

In comparison to `ggplot2`, graphics’ customization in `ddplot` is limited nonetheless you get a fully vectorized SVG which is cool.

    scatterPlot(
      data = mpg,
      x = "displ",
      y = "cty",
      col = "tomato",
      bgcol = "pink",
      size = 3,
      stroke = "royalblue",
      strokeWidth = 1,
      xtitle = "displ variable",
      ytitle = "cty variable",
      xticks = 3,
      yticks = 3)

Start.R

# `histogram()`

The `histogram()` function allows you to visualize the distribution of a vector of data:

    histogram(
      x = mpg$hwy,
      bins = 20,
      fill = "crimson",
      stroke = "white",
      strokeWidth = 1,
      title = "Distribution of the hwy variable",
      width = "20",
      height = "10"
    )

Start.R

# `animatedHistogram()`

This function allows you to create a one-click histogram animation. Useful for presentation purposes. Click on the following empty plot and see what happens:

    animatedHistogram(
      x = mpg$hwy,
      duration = 2000,
      delay = 100,
      fill = "lime",
      stroke = "white",
      bgcol = "white"
      )

Start.R

Note that you can customize the animation using the two parameters `duration` and `delay`.

# `flower()`

The `flower()` function allows you to plot a simple flowers with a defined number of petals. You can also define the width/length of the petals and rotate them if needed:

    flower(
      petalCount = 7,
      petalColor = "plum",
      rotationSpeed = 0
    )

Start.R

    flower(
      petalCount = 15,
      petalWidth = 20,
      petalColor = "plum",
      rotationSpeed = 1.5
    )

Start.R

# `heart_fill`

The `heart_fill` function allows you to display a heart indicator which will be filled according to a numerical value from 0 to 1:

    heart_fill(fill_level = 0.8, titleText = NULL, renderFillLabel = FALSE)

Start.R

# `glass_fill`

The `glass_fill` function works the same way as the `heart_fill` above:

    glass_fill(fill_level = 0.8, titleText = "Glass of water", renderFillLabel = TRUE)

Start.R

# `plant_growth`

The `plant_growth` function can also be used as a visual clue:

    plant_growth(0.4)

Start.R

    plant_growth(1)

Start.R

# `flame`

You can create cool `flames` using the `flame` function, useful if you want to display the state of a critical information that yields a numerical values (for example, the number of errors encountered in a specific process):

    flame(
      intensity = 20,
      flameGradientColors = c("yellow", "orange", "darkred"),
      flameOutline = "darkred",
      bgcol = "#fefefe"
    )

Start.R

    flame(
      intensity = 80,
      flameGradientColors = c("green", "darkgreen", "darkblue"),
      flameOutline = "#fefefe",
      bgcol = "black"
    )

Start.R # `parliament_chart()`

You can easily create a `Parliamant chart` using the `parliamant_chart()` function, consider the following example:

    # The data is a toy example and does not reflect the reality
    vote_results_germany <- data.frame(
        political_party = c("SDP", "CDU", "Linke", "Grüne"),
        number_of_seats = c(200, 40, 30, 20)
    )
    parliament_chart(
      data = vote_results_germany,
      categorical_column = "political_party",
      numerical_column = "number_of_seats",
      title = "German Bundestag",
      seatSize = 10,
      bgcol = "#fefefe"
    )

Start.R

# `barChart()`

The `barChat()` function allows you to create bar charts however you need to make the aggregation beforehand. In the following example, we will plot the average `cty` for each `manufacturer` using the `dplyr` package.

    library(dplyr)

    mpg %>% group_by(manufacturer) %>%
      summarise(mean_cty = mean(cty)) %>%
      barChart(
        x = "manufacturer",
        y = "mean_cty",
        xFontSize = 10,
        yFontSize = 10,
        fill = "orange",
        strokeWidth = 2,
        ytitle = "average cty value",
        title = "Average City Miles per Gallon by manufacturer"
      )

Start.R

The bars can be easily sorted in `ascending` or `descending` order using the `sort` parameter:

    mpg %>% group_by(manufacturer) %>%
      summarise(mean_cty = mean(cty)) %>%
      barChart(
        x = "manufacturer",
        y = "mean_cty",
        sort = "ascending",
        xFontSize = 10,
        yFontSize = 10,
        fill = "orange",
        strokeWidth = 1,
        ytitle = "average cty value",
        title = "Average City Miles per Gallon by manufacturer",
        titleFontSize = 16
      )

Start.R

# `horzBarChart()`

If you’ve many categories, it might be a good idea to go for a horizontal bar chart. It has the same parameters as the `barChart()` function except that the x-axis parameter is named `value` and the y-axis parameter named `label`, this naming convention aims to mitigate some confusion that can arise.

If we want to replicate the above graphic in a horizontal way, we can do:

    mpg %>% group_by(manufacturer) %>%
      summarise(mean_cty = mean(cty)) %>%
      horzBarChart(
        label = "manufacturer",
        value = "mean_cty",
        sort = "ascending",
        labelFontSize  = 10,
        valueFontSize = 10,
        fill = "orange",
        stroke = "crimson",
        strokeWidth = 1,
        valueTitle  = "average cty value",
        title = "Average City Miles per Gallon by manufacturer",
        titleFontSize = 16
      )

Start.R

As in `barChart()`, we can aslo sort in descending order:

    mpg %>% group_by(manufacturer) %>%
      summarise(mean_cty = mean(cty)) %>%
      horzBarChart(
        label = "manufacturer",
        value = "mean_cty",
        sort = "descending",
        labelFontSize  = 10,
        valueFontSize = 10,
        bgcol = "black",
        axisCol = "white",
        fill = "white",
        stroke = "white",
        strokeWidth = 1,
        valueTitle  = "average cty value",
        labelTitle = "Manufacturers",
        title = "Average City Miles per Gallon by manufacturer",
        titleFontSize = 16
      )

Start.R

# `lollipopChart()`

lollipop chart follows the same behavior as bar charts but instead of bars you get lollipops, hence the name. Below an example of a lollipop chart with `ddplot`:

    mpg %>% group_by(drv) %>%
      summarise(median_cty = median(cty)) %>%
      lollipopChart(
        x = "drv",
        y = "median_cty",
        sort = "ascending",
        xtitle = "drv variable",
        ytitle = "median cty",
        title = "Median cty per drv",
        xFontSize = 20
      )

Start.R

It’s possible to grasp the distribution of some variable according to a specific categorical variable using the same function:

    mpg %>% filter(year == 2008) %>%
    lollipopChart(
        x = "manufacturer",
        y = "hwy",
        circleFill = 'red',
        circleStroke = 'orange',
        circleRadius = 5,
        sort = "none",
        xFontSize = 10
      )

Start.R

From above, it’s quite easy to notice that although Toyota has two cars with high highway miles per galon (hwy), it also produces many other vehicles with poor hwy.

# `horzLollipop()`

Same with bar charts, if you have a variable that has many categorical values, you can work with the reversed version of `lollipopChart()` which is `horzLollipop()`:

    mpg %>% group_by(manufacturer) %>%
      summarise(median_cty = median(cty)) %>%
      horzLollipop(
        label = "manufacturer",
        value = "median_cty",
        sort = "descending")

Start.R You can also do:

    mpg %>% filter(year == 2008) %>%
    horzLollipop(
        label = "manufacturer",
        value = "hwy",
        circleFill = 'red',
        circleStroke = 'orange',
        circleRadius = 5,
        sort = "none"
      )

Start.R

# `pieChart()`

Pie charts and donut charts are pretty straightforward to set up. We’ll use a sample from the `starwars` data frame to plot a simple pie chart.

    # starwars is part of the dplyr data frame
    mini_starwars <- starwars %>% tidyr::drop_na(mass) %>%
      sample_n(size = 5) # getting 5 random values

    pieChart(
      data = mini_starwars,
      value = "mass",
      label = "name"
    )

Start.R

Using the `padRadius`, `padAngle` and `cornerRadius` parameters, one can get fanciers pie charts:

    pieChart(
      data = mini_starwars,
      value = "mass",
      label = "name",
      padRadius = 200,
      padAngle = 0.1,
      cornerRadius = 50,
      innerRadius = 10
    )

Start.R If you need a donut chart, you just need to play with the `innerRadius` parameter:

    pieChart(
      data = mini_starwars,
      value = "mass",
      label = "name",
      innerRadius = 120,
      cornerRadius = 20,
      title = "5 Starwars characters ranked by their mass",
      titleFontSize = 16,
      bgcol = "yellow"
    )

Start.R

# `lineChart()`

The `lineChart()` function is used to plot time series data. The use must provide a `date` variable that has the `yyyy-mm-dd` format. In the following example, we’ll use the `Air Passenger` built-in `ts` data and convert it to a classical data frame:

    # 1. converting AirPassengers to a tidy data frame
    airpassengers <- data.frame(
      passengers = as.matrix(AirPassengers),
      date= zoo::as.Date(time(AirPassengers))
    )

    # 2. plotting the line chart
    lineChart(
      data = airpassengers,
      x = "date",
      y = "passengers"
    )

Start.R

You can modify the line interpolation using the `curve` parameter:

    lineChart(
      data = airpassengers,
      x = "date",
      y = "passengers",
      curve = "curveStep"
    )

Start.R

    lineChart(
      data = airpassengers,
      x = "date",
      y = "passengers",
      curve = "curveCardinal"
    )

Start.R

    lineChart(
      data = airpassengers,
      x = "date",
      y = "passengers",
      curve = "curveBasis"
    )

Start.R

# `animLineChart()`

Heavily inspired from Jure Stabuc’s example, the `animLineChart()` function create an empty SVG but when each time you click on it a line chart animation starts. Note that the line lasts after the end of the animation. Go ahead, click on the empty graphic below:

    animLineChart(
      data = airpassengers,
      x = "date",
      y = "passengers",
      duration = 10000, # in milliseconds (10 seconds)
      curve = "curveCardinal"
      )

Start.R

# `areaChart()`

`areaChart()` works similarly except that instead of a line you get an area.

    # 1. converting AirPassengers to a tidy data frame
    airpassengers <- data.frame(
      passengers = as.matrix(AirPassengers),
      date= zoo::as.Date(time(AirPassengers))
    )

    # 2. plotting the area chart
    areaChart(
      data = airpassengers,
      x = "date",
      y = "passengers",
      fill = "purple",
      bgcol = "white"
    )

Start.R

# `areaBand()`

`areaBand()` lets you plot a filled area between two y-values. For the sake of the example, let’s create an additional column `passengers_upper` that has an additional 40 passengers for each observation:

    airpassengers <- data.frame(
      passengers_lower = as.matrix(AirPassengers),
      passengers_upper = as.matrix(AirPassengers) + 40,
      date= zoo::as.Date(time(AirPassengers))
    )

    areaBand(
      data = airpassengers,
      x = "date",
      yLower = "passengers_lower",
      yUpper = "passengers_upper",
      fill = "yellow",
      stroke = "black"
    )

Start.R

# `stackedAreaChart()`

This function allows you to create a stacked area chart. You need two components:

- A data frame in wide format (see an example below). If it’s in wide format, you can still use `pivot_wider()` from the `tidyr` package to make wider.
- A date variable in `yyyy-mm-dd` format that will plotted in the x-axis.

Let’s work with the following data frame (shortened) provided by Mike Bostock in his stacked area chart example:

    data <- data.frame(
      date = c(
        "2000-01-01", "2000-02-01", "2000-03-01", "2000-04-01",
        "2000-05-01", "2000-06-01", "2000-07-01",
        "2000-08-01", "2000-09-01", "2000-10-01"
      ),
      Trade = c(
        2000,1023, 983, 2793, 1821, 1837, 1792, 1853, 791, 739
      ),
      Manufacturing = c(
        734, 694, 739, 736, 685, 621, 708, 685, 667, 693
      ),
      Leisure = c(
        1782, 1779, 1789, 658, 675, 833, 786, 675, 636, 691
      ),
      Agriculture = c(
        655, 587,623, 517, 561, 2545, 636, 584, 559, 2504
      )
    )

    data
    #>          date Trade Manufacturing Leisure Agriculture
    #> 1  2000-01-01  2000           734    1782         655
    #> 2  2000-02-01  1023           694    1779         587
    #> 3  2000-03-01   983           739    1789         623
    #> 4  2000-04-01  2793           736     658         517
    #> 5  2000-05-01  1821           685     675         561
    #> 6  2000-06-01  1837           621     833        2545
    #> 7  2000-07-01  1792           708     786         636
    #> 8  2000-08-01  1853           685     675         584
    #> 9  2000-09-01   791           667     636         559
    #> 10 2000-10-01   739           693     691        2504

Start.R

Note that when running `stackedAreaChart()` all the variables available within the considered data frame will be plotted. If you want to restrict the plotting to only specific variables, just drop the unneeded columns:

    stackedAreaChart(
      data = data,
      x = "date",
      legendTextSize = 14
      )

Start.R

You can modify the color scheme using the `colorCategory` parameter:

    stackedAreaChart(
      data = data,
      x = "date",
      legendTextSize = 14,
      curve = "curveCardinal",
      colorCategory = "Accent",
      bgcol = "white",
      stroke = "black",
      strokeWidth = 1
      )

Start.R

    stackedAreaChart(
      data = data,
      x = "date",
      legendTextSize = 14,
      curve = "curveBasis",
      colorCategory = "Set3",
      bgcol = "black",
      axisCol = "white",
      xticks = 4,
      stroke = "black"
      )

Start.R

You can find list of D3 categorical color schemes here

Finally, if you hover over the chart you’ll notice a tooltip that identified the different area categories.

# `barChartRace()`

This function allows you to create an animated bar chart race. `barChartRace()` is similar to `barChart()` but takes a third variable mapped to the time dimension, with options for styling transitions.

Let’s make a bar chart race of population growth among various countries using a subset of the `gapminder` dataset from the {gapminder} package:

    gapminder_subset <- gapminder::gapminder %>%
      select(country, year, pop) %>%
      filter(country %in% c("Japan", "Mexico", "Germany", "Brazil", "Philippines", "Vietnam")) %>%
      mutate(pop = pop/1e6)

    gapminder_subset %>%
      slice_sample(n = 10)

    #>    year       pop     country
    #> 1  2007  91.07729 Philippines
    #> 2  1997  76.04900     Vietnam
    #> 3  1972 107.18827       Japan
    #> 4  1967  39.46391     Vietnam
    #> 5  1952  30.14432      Mexico
    #> 6  1987 142.93808      Brazil
    #> 7  1997 168.54672      Brazil
    #> 8  1962  41.12148      Mexico
    #> 9  1952  69.14595     Germany
    #> 10 1957  91.56301       Japan

Start.R

Start.R

In this example, we simply pass call `barChartRace()` like `barChart()`, but with an additional variable mapped to the time dimension specified with `time = year`:

    gapminder_subset %>%
      barChartRace(
        x = "pop",
        y = "country",
        time = "year",
        ytitle = "Country",
        xtitle = "Population (in millions)",
        title = "Bar chart race of country populations"
      )

Start.R

You can also stylize transitions with the `frameDur`, `transitionDur`, and `ease` arguments. For example, setting the time spent pausing on each frame to zero with `frameDur = 0` will create a smooth animation:

    gapminder_subset %>%
      barChartRace(
        x = "pop",
        y = "country",
        time = "year",
        transitionDur = 1000,
        frameDur = 0,
        ytitle = "Country",
        xtitle = "Population (in millions)",
        title = "Bar chart race of country populations"
      )

Start.R

As you might have noticed, the value of the column passed to the `time` argument is automatically labelled at the bottom-right corner of the plot panel. We can stylize this with a list of options passed to the `timeLabelOpts` argument (or turn it off with `timeLabel = FALSE`). We also give the bars a little bounce here with `ease = "BackInOut"` for fun.

    gapminder_subset %>%
      barChartRace(
        x = "pop",
        y = "country",
        time = "year",
        ease = "BackInOut",
        ytitle = "Country",
        xtitle = "Population (in millions)",
        title = "Bar chart race of country populations",
        timeLabelOpts = list(
          size = 40,
          prefix = "Year: ",
          xOffset = 0.2
        )
      )

Start.R

# Using `ddplot` in `Shiny`

If you want to add reactivity to your `ddplot` plots, use the `uiOutput` and `renderUI` in order to render a frame, note that you’ll need to have a `www` folder, below an example:

    library(shiny)
    library(ddplot)
    library(r2d3)

    ui <- fluidPage(

      shiny::h2("Example ddplot application"),

      shiny::selectInput(
        inputId = "colors",
        label = NULL,
        choices = colors(),
        selected = "springgreen3"
      ),

      shiny::br(),

      shiny::sliderInput(
        inputId = "slider",
        label = NULL,
        min = 1,
        max = 10,
        value = 3
      ),
      shiny::br(),
      mainPanel(
        uiOutput("ddplot_ui")
      )
    )

    server <- function(input, output) {
      output$ddplot_ui <- renderUI({
        widget <- ddplot::scatterPlot(
          data = iris,
          x = "Sepal.Length",
          y = "Sepal.Width",
          size = input$slider,
          col = input$colors
        )
        htmlwidgets::saveWidget(widget, "www/temp_ddplot.html", selfcontained = TRUE)
        tags$iframe(src = "temp_ddplot.html", width = "100%", height = "400px", frameborder = 0)
      })
    }

    shinyApp(ui = ui, server = server)

Start.R