Introduction - basic use

Victor Perrier

2024-09-09

This package allow you to use billboard.js, a re-usable easy interface JavaScript chart library, based on D3 v4+.

Supported chart types:

The main function is billboarder, all charts begin with. You can add layer to your charts with function bb_*, these functions correspond to a billboard option define in the API docs. There are helpers functions to quickly create a type of chart (bb_barchart, bb_linechart, bb_piechart, bb_donutchart, bb_gauge, bb_scatterplot), they have to be called after billboarder.

Bar chart

You can create a simple bar chart by passing a data.frame to bb_barchart, the first column will be used as the x-axis, and the second one as the y-axis :

library("billboarder")

df <- as.data.frame(table(sample(letters[1:5], 50, TRUE)))
df
#>   Var1 Freq
#> 1    a   12
#> 2    b   12
#> 3    c    9
#> 4    d    8
#> 5    e    9

billboarder() %>% 
  bb_barchart(data = df)

If you want to create a grouped bar chart, first option is to put your data in a “wide” format. Here we use stats::reshape, but I recommend to use tidyr::spread or data.table::dcast.

df <- as.data.frame(table(
  sample(letters[1:5], 50, TRUE),
  sample(LETTERS[1:5], 50, TRUE)
))
df.r <- reshape(data = df, idvar = "Var1", timevar = "Var2", direction = "wide")
df.r
#>   Var1 Freq.A Freq.B Freq.C Freq.D Freq.E
#> 1    a      2      2      1      1      3
#> 2    b      2      3      2      0      2
#> 3    c      5      0      1      2      5
#> 4    d      3      1      2      2      4
#> 5    e      0      5      1      0      1

billboarder() %>% 
  bb_barchart(data = df.r)

Second option is to define a mapping of your variable with function bbaes (for more example of mapping, see vignette billboarder-mapping).

billboarder() %>% 
  bb_barchart(
    data = df,
    mapping = bbaes(x = Var1, y = Freq, group = Var2)
  )

Line chart

You can pass to the function bb_linechart a vector, in that case x-axis will be the index of that vector :

billboarder() %>% 
  bb_linechart(data = sin(seq(-pi, pi, length.out = 10)))

You can change the type of line with argument type, for example an area-step :

billboarder() %>% 
  bb_linechart(data = sin(seq(-pi, pi, length.out = 10)), type = "area-step")

If want to specify a variable to map to the x-axis, you had to pass a data.frame to the function :

df <- data.frame(
  var_x = seq(-pi, pi, length.out = 10),
  sin = sin(seq(-pi, pi, length.out = 10))
)
df
#>         var_x           sin
#> 1  -3.1415927 -1.224647e-16
#> 2  -2.4434610 -6.427876e-01
#> 3  -1.7453293 -9.848078e-01
#> 4  -1.0471976 -8.660254e-01
#> 5  -0.3490659 -3.420201e-01
#> 6   0.3490659  3.420201e-01
#> 7   1.0471976  8.660254e-01
#> 8   1.7453293  9.848078e-01
#> 9   2.4434610  6.427876e-01
#> 10  3.1415927  1.224647e-16

billboarder() %>% 
  bb_linechart(data = df, x = "var_x")

If the first variable of the data.frame is a Date or a POSIX, it will be automatically mapped to the x-axis :

df <- data.frame(
  date = seq.Date(from = as.Date("2017-06-12"), by = "day", length.out = 10),
  var = rnorm(10)
)
df
#>          date         var
#> 1  2017-06-12 -0.05960369
#> 2  2017-06-13  0.32426261
#> 3  2017-06-14 -0.96574298
#> 4  2017-06-15  1.14550069
#> 5  2017-06-16  0.45642031
#> 6  2017-06-17 -0.09075055
#> 7  2017-06-18  0.14248854
#> 8  2017-06-19 -0.41866594
#> 9  2017-06-20  1.88434874
#> 10 2017-06-21  0.20214119

billboarder() %>% 
  bb_linechart(data = df)

Scatter plot

For scatter plot, use a two column data.frame with function bb_scatterplot, or specify the x variable and the y variable (you can also specify a grouping variable) :

billboarder() %>% 
  bb_scatterplot(data = iris[, 1:2])

billboarder() %>% 
  bb_scatterplot(data = iris, x = "Petal.Length", y = "Petal.Width", group = "Species")

Pie chart

For pie chart, use bb_piechart with a two column data.frame :

df <- data.frame(
  var = c("A", "B"),
  count = c(457, 987)
)

billboarder() %>% 
  bb_piechart(data = df)

Donut chart

Donut charts works the same as pie charts :

df <- data.frame(
  var = c("A", "B"),
  count = c(687, 246)
)

billboarder() %>% 
  bb_donutchart(data = df)

Note : pie and donut are automatically sorted, you can change that with bb_data(order = NULL).

Gauge chart

Gauge only need one value :

billboarder() %>% 
  bb_gaugechart(value = 64)