Interactive timeline plots with hc_vistime()

Oktober 2023

Buy Me A Coffee

Feedback welcome: sa.ra.online@posteo.de

1. Basic example

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

hc_vistime(timeline_data)
Created with Highcharts 9.3.1Event 1Event 1Event 2Event 2My EventsMay '20Jun '20Jul '20Aug '20Sep '20Oct '20Nov '20Dec '20Jan '21Feb '21Feb…

2. Installation

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

install.packages("vistime")

For interactive hc_vistime() plots, you need to install the highcharter package. This package is free for non-commercial and non-governmental use:

install.packages("highcharter")

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, title and label visibility.

hc_vistime(data,
           col.event = "event",
           col.start = "start",
           col.end = "end", 
           col.group = "group", 
           col.color = "color", 
           optimize_y = TRUE,
           title = NULL, 
           show_labels = TRUE)

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.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.
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.

5. Value

  • hc_vistime returns an object of class highchart 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"))
                  
hc_vistime(pres, 
           col.event = "Position", 
           col.group = "Name", 
           title = "Presidents of the USA") %>% 
  hc_size(width = 700, height = 300)
Created with Highcharts 9.3.1Presidents of the USAPresidentPresidentViceVicePresidentPresidentViceVicePresidentPresidentViceViceWashingtonAdamsJeffersonBurr178817901792179417961798180018021804180618081810181218…

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")
                           
hc_vistime(data)
Created with Highcharts 9.3.1Phase 1Phase 1Phase 2Phase 2Phase 3Phase 3Phase 4Phase 4Room 334Room 334Room 335Room 335Room 335Room 335Group 1Group 1Group 2Group 23-2003-2003-3303-3303-2233-2233-2253-2253-2263-2263-3303-3303-2263-2261-217.01-217.04-399.74-399.78-831.08-831.09-984.19-984.1F01.9F01.9Z71Z71B95.7B95.7T82.7T82.7ProjectTeam 1Team 2category 1category 2moon risingsundowner drinkbirthday partyMeetings19. Dec26. Dec2. Jan9. Jan16. Jan23. Jan30. Jan6. Feb

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")
        
hc_vistime(data, optimize_y = TRUE)
Created with Highcharts 9.3.1Phase 1Phase 1Phase 2Phase 2Phase 3Phase 3Phase 4Phase 47. Dec14. Dec21. Dec28. Dec4. Jan11. Jan18. Jan25. Jan1. Feb8. Feb

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

hc_vistime(data, optimize_y = FALSE)
Created with Highcharts 9.3.1Phase 1Phase 1Phase 2Phase 2Phase 3Phase 3Phase 4Phase 47. Dec14. Dec21. Dec28. Dec4. Jan11. Jan18. Jan25. Jan1. Feb8. Feb

8. Usage in Shiny apps

  • hc_vistime() objects can be integrated into Shiny via highchartOutput() and renderHighchart()
library(vistime)

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 = highcharter::highchartOutput("myVistime"),
  server = function(input, output) {
    output$myVistime <- highcharter::renderHighchart({
      vistime(pres, col.event = "Position", col.group = "Name")
    })
  }
)

9. Customization

Since every hc_vistime() output is a highchart object, you can customize and override literally everything using its functions. See ?hc_xAxis, ?hc_chart etc. and the official Highcharts API reference for details.

library(highcharter)

p3 <- hc_vistime(data,
                 optimize_y = T, 
                 col.group = "event",
                 title = "Highcharts customization example")

p3 %>% hc_title(style = list(fontSize = 30)) %>% 
       hc_yAxis(labels = list(style = list(fontSize=30, color="violet"))) %>% 
       hc_xAxis(labels = list(style = list(fontSize=30, color="red"), rotation=30)) %>% 
       hc_chart(backgroundColor = "lightgreen") %>% 
  hc_size(width = 700, height = 300)
Created with Highcharts 9.3.1Highcharts customization examplePhase 1Phase 1Phase 2Phase 2Phase 3Phase 3Phase 4Phase 4Phase 27. Dec14. Dec21. Dec28. Dec4. Jan11. Jan18. Jan25. Jan1. Feb8. Feb