In shosaco/vistime: Pretty Timelines in R

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(vistime)

Feedback welcome: [e-mail]

1. Basic example

vistime() produces Plotly charts. For interactive Highcharts output, see hc_vistime(), for static ggplot2 charts, see gg_vistime().

library(vistime)

timeline_data <- data.frame(event = c("Event 1", "Event 2"), 
                            start = c("2020-06-06", "2020-10-01"), 
                            end = c("2020-10-01", "2020-12-31"), 
                            group = "My Events")

vistime(timeline_data)

2. Installation

To install the package from CRAN, type the following in your R console:

install.packages("vistime")

3. Usage and default arguments

The simplest way to create a timeline is by providing a data frame with event and start columns. If your columns are named otherwise, you need to tell the function. You can also tweak the y positions, linewidth, title, label visibility and number of lines in the background.

vistime(data, 
        col.event = "event", 
        col.start = "start",
        col.end = "end", 
        col.group = "group", 
        col.color = "color", 
        col.fontcolor = "fontcolor",
        col.tooltip = "tooltip", 
        optimize_y = TRUE, 
        linewidth = NULL, 
        title = NULL, 
        show_labels = TRUE, 
        background_lines = NULL)

4. Arguments

parameter | optional? | data type | explanation --------- |----------- | -------- | ----------- data | mandatory | data.frame | data.frame that contains the data to be visualized col.event | optional | character | the column name in data that contains event names. Default: event col.start | optional | character | the column name in data that contains start dates. Default: start col.end | optional | character | the column name in data that contains end dates. Default: end col.group | optional | character | the column name in data to be used for grouping. Default: group col.color | optional | character | the column name in data that contains colors for events. Default: color, if not present, colors are chosen via RColorBrewer. col.fontcolor | optional | character | the column name in data that contains the font color for event labels. Default: fontcolor, if not present, color will be black. col.tooltip | optional | character | the column name in data that contains the mouseover tooltips for the events. Default: tooltip, if not present, then tooltips are build from event name and date. Basic HTML is allowed. optimize_y | optional | logical | distribute events on y-axis by smart heuristic (default) or use order of input data. linewidth | optional | numeric | override the calculated linewidth for events. Default: heuristic value. title | optional | character | the title to be shown on top of the timeline. Default: empty. show_labels | optional | logical | choose whether or not event labels shall be visible. Default: TRUE. background_lines | optional | integer | the number of vertical lines to draw in the background to demonstrate structure. Default: heuristic. source | optional | character | Information for Plotly to identify plot in Shiny Apps. Default: A. customdata | optional | character | Custom data passed to click or hover event in Shiny.

5. Value

• vistime returns an object of class plotly and htmlwidget

6. Examples

Ex. 1: Presidents

pres <- data.frame(Position = rep(c("President", "Vice"), each = 3),
                   Name = c("Washington", rep(c("Adams", "Jefferson"), 2), "Burr"),
                   start = c("1789-03-29", "1797-02-03", "1801-02-03"),
                   end = c("1797-02-03", "1801-02-03", "1809-02-03"),
                   color = c('#cbb69d', '#603913', '#c69c6e'),
                   fontcolor = c("black", "white", "black"))

vistime(pres, 
        col.event = "Position", 
        col.group = "Name", 
        title = "Presidents of the USA")

Ex. 2: Project Planning

data <- read.csv(text="event,group,start,end,color
                       Phase 1,Project,2016-12-22,2016-12-23,#c8e6c9
                       Phase 2,Project,2016-12-23,2016-12-29,#a5d6a7
                       Phase 3,Project,2016-12-29,2017-01-06,#fb8c00
                       Phase 4,Project,2017-01-06,2017-02-02,#DD4B39
                       Room 334,Team 1,2016-12-22,2016-12-28,#DEEBF7
                       Room 335,Team 1,2016-12-28,2017-01-05,#C6DBEF
                       Room 335,Team 1,2017-01-05,2017-01-23,#9ECAE1
                       Group 1,Team 2,2016-12-22,2016-12-28,#E5F5E0
                       Group 2,Team 2,2016-12-28,2017-01-23,#C7E9C0
                       3-200,category 1,2016-12-25,2016-12-25,#1565c0
                       3-330,category 1,2016-12-25,2016-12-25,#1565c0
                       3-223,category 1,2016-12-28,2016-12-28,#1565c0
                       3-225,category 1,2016-12-28,2016-12-28,#1565c0
                       3-226,category 1,2016-12-28,2016-12-28,#1565c0
                       3-226,category 1,2017-01-19,2017-01-19,#1565c0
                       3-330,category 1,2017-01-19,2017-01-19,#1565c0
                       1-217.0,category 2,2016-12-27,2016-12-27,#90caf9
                       4-399.7,moon rising,2017-01-13,2017-01-13,#f44336
                       8-831.0,sundowner drink,2017-01-17,2017-01-17,#8d6e63
                       9-984.1,birthday party,2016-12-22,2016-12-22,#90a4ae
                       F01.9,Meetings,2016-12-26,2016-12-26,#e8a735
                       Z71,Meetings,2017-01-12,2017-01-12,#e8a735
                       B95.7,Meetings,2017-01-15,2017-01-15,#e8a735
                       T82.7,Meetings,2017-01-15,2017-01-15,#e8a735")

vistime(data)

Ex. 3: Gantt Charts

The argument optimize_y can be used to change the look of the timeline. TRUE (the default) will find a nice heuristic to save y-space, distributing the events:

data <- read.csv(text="event,start,end
                       Phase 1,2020-12-15,2020-12-24
                       Phase 2,2020-12-23,2020-12-29
                       Phase 3,2020-12-28,2021-01-06
                       Phase 4,2021-01-06,2021-02-02")

vistime(data, optimize_y = TRUE, linewidth = 25)

FALSE will plot events as-is, not saving any space:

vistime(data, optimize_y = FALSE, linewidth = 25)

7. Export of vistime as PDF or PNG

Once created, you can use plotly::export() for saving your vistime chart as PDF, PNG or JPEG:

# webshot::install_phantomjs()
chart <- vistime(pres, col.event = "Position")
plotly::export(chart, file = "presidents.pdf")

Note that export requires the webshot package and phantomjs on your OS. Additional arguments like width or height can be used (?webshot for the details). You can also download the plot as PNG by using the toolbar on the upper right side of the generated plot.

8. Usage in Shiny apps

• vistime() objects can be integrated into Shiny via plotlyOutput() and renderPlotly(). Using the arguments source and customdata, information can be passed to the click event.

library(vistime)
library(shiny)
library(plotly)

pres <- data.frame(Position = rep(c("President", "Vice"), each = 3),
                   Name = c("Washington", rep(c("Adams", "Jefferson"), 2), "Burr"),
                   start = c("1789-03-29", "1797-02-03", "1801-02-03"),
                   end = c("1797-02-03", "1801-02-03", "1809-02-03"),
                   color = c('#cbb69d', '#603913', '#c69c6e'),
                   fontcolor = c("black", "white", "black"))

shinyApp(
  ui = basicPage("",
                 mainPanel(plotlyOutput("my_plot"),
                           verbatimTextOutput("clicked_info"))),
  server = function(input, output) {
    output$my_plot <- plotly::renderPlotly({
      vistime(pres, col.event = "Position", col.group = "Name", source = "my_plot", customdata = "some_information")
    })

    output$clicked_info <- renderPrint({
            click_data <- event_data("plotly_click", source = "my_plot")
            req(click_data)
            message("CLICK!")
            click_data
        })
  }
)

9. Customization

Using plotly::layout()

See ?plotly::layout and the official Plotly API reference for details.

library(plotly)

p2 <- vistime(data,
              optimize_y = T, 
              col.group = "event",
              title = "Plotly customization example")

p2 %>% layout(xaxis=list(fixedrange=TRUE, tickfont=list(size=30, color="violet")), 
              yaxis=list(fixedrange=TRUE, tickfont=list(size=30, color="red"), tickangle=30,
                         mirror = FALSE, range = c(0.7, 3.5), showgrid = T),
              plot_bgcolor = "lightgreen") 

List manipulation

Changing x-axis tick font size

The following example creates the presidents example and manipulates the font size of the x axis ticks:

pres <- data.frame(Position = rep(c("President", "Vice"), each = 3),
                   Name = c("Washington", rep(c("Adams", "Jefferson"), 2), "Burr"),
                   start = c("1789-03-29", "1797-02-03", "1801-02-03"),
                   end = c("1797-02-03", "1801-02-03", "1809-02-03"),
                   color = c('#cbb69d', '#603913', '#c69c6e'),
                   fontcolor = c("black", "white", "black"))

p <- vistime(pres, 
             col.event = "Position",
             col.group = "Name", 
             title = "Presidents of the USA")

# step 1: transform into a list
pp <- plotly::plotly_build(p)

# step 2: change the font size
pp$x$layout$xaxis$tickfont <- list(size = 28)

pp

Changing y-axis tick font size

We need to change the font size of the y-axis:

pp$x$layout[["yaxis"]]$tickfont <- list(size = 28)
pp

Changing events font size

The following example creates the presidents example and manipulates the font size of the events:

pres <- data.frame(Position = rep(c("President", "Vice"), each = 3),
                    Name = c("Washington", rep(c("Adams", "Jefferson"), 2), "Burr"),
                    start = c("1789-03-29", "1797-02-03", "1801-02-03"),
                    end = c("1797-02-03", "1801-02-03", "1809-02-03"),
                    color = c('#cbb69d', '#603913', '#c69c6e'),
                    fontcolor = c("black", "white", "black"))

p <- vistime(pres, 
             col.event = "Position",
             col.group = "Name", 
             title = "Presidents of the USA",
             linewidth=30)

# step 1: transform into a list
pp <- plotly::plotly_build(p)

# step 2: loop over pp$x$data, and change the font size of all text elements to 28
for(i in seq_along(pp$x$data)){
    if(pp$x$data[[i]]$mode == "text") pp$x$data[[i]]$textfont$size <- 28
}

#' # or, using purrr:
#' text_idx <- which(purrr::map_chr(pp$x$data, "mode") == "text")
#' for(i in text_idx) pp$x$data[[i]]$textfont$size <- 28
#' pp

pp

Changing marker size

The following example a simple example using markers and manipulates the size of the markers:

dat <- data.frame(event = 1:4, start = c("2019-01-01", "2019-01-10"))

p <- vistime(dat)

# step 1: transform into a list
pp <- plotly::plotly_build(p)

# step 2: loop over pp$x$data, and change the marker size of all text elements to 50px
for(i in seq_along(pp$x$data)){
    if(pp$x$data[[i]]$mode == "markers") pp$x$data[[i]]$marker$size <- 20
}

# or, using purrr:
# marker_idx <- which(purrr::map_chr(pp$x$data, "mode") == "markers")
# for(i in marker_idx) pp$x$data[[i]]$marker$size <- 20
# pp

pp

shosaco/vistime documentation built on March 30, 2024, 1:49 a.m.