timevis {timevis}R Documentation

Create a timeline visualization

Description

timevis lets you create rich and fully interactive timeline visualizations. Timelines can be included in Shiny apps or R markdown documents. timevis Includes an extensive API to manipulate a timeline after creation, and supports getting data out of the visualization into R. Based on the 'visjs' Timeline JavaScript library.

View a demo Shiny app or see the full README on GitHub.

Important note: This package provides a way to use the visjs Timeline JavaScript library within R. The visjs Timeline library has too many features that cannot all be documented here. To see the full details on what the timeline can support, please read the official documentation of visjs Timeline.

Usage

timevis(
  data,
  groups,
  showZoom = TRUE,
  zoomFactor = 0.5,
  fit = TRUE,
  options,
  width = NULL,
  height = NULL,
  elementId = NULL,
  loadDependencies = TRUE,
  timezone = NULL
)

Arguments

data

A dataframe containing the timeline items. Each item on the timeline is represented by a row in the dataframe. start and content are the only two required columns. See the Data format section below for more details. For a full list of all supported columns, see the Data Format section in the official visjs Timeline documentation.

groups

A dataframe containing the groups data (optional). See the Groups section below for more details.

showZoom

If TRUE (default), then include "Zoom In"/"Zoom Out" buttons on the widget.

zoomFactor

How much to zoom when zooming out. A zoom factor of 0.5 means that when zooming out the timeline will show 50% more content. For example, if the timeline currently shows 20 days, then after zooming out with a zoomFactor of 0.5, the timeline will show 30 days, and zooming out again will show 45 days. Similarly, zooming out from 20 days with a zoomFactor of 1 will results in showing 40 days.

fit

If TRUE, then fit all the data on the timeline when the timeline initializes. Otherwise, the timeline will be set to show the current date.

options

A named list containing any extra configuration options to customize the timeline. All available options can be found in the official Timeline documentation. Note that any options that define a JavaScript function must be wrapped in a call to htmlwidgets::JS(). See the examples section below to see example usage.

width

Fixed width for timeline (in css units). Ignored when used in a Shiny app – use the width parameter in timevisOutput. It is not recommended to use this parameter because the widget knows how to adjust its width automatically.

height

Fixed height for timeline (in css units). It is recommended to not use this parameter since the widget knows how to adjust its height automatically.

elementId

Use an explicit element ID for the widget (rather than an automatically generated one). Ignored when used in a Shiny app.

loadDependencies

Whether to load JQuery and bootstrap dependencies (you should only set to FALSE if you manually include them)

timezone

By default, the timevis widget displays times in the local time of the browser rendering it. You can set timevis to display times in another time zone by providing a number between -15 to 15 to specify the number of hours offset from UTC. For example, use 0 to display in UTC, and use -4 to display in a timezone that is 4 hours behind UTC.

Value

A timeline visualization htmlwidgets object

Data format

The data parameter supplies the input dataframe that describes the items in the timeline. The following is a subset of the variables supported in the items dataframe. The full list of supported variables can be found in the official visjs documentation.

start and content are the only required variables for each item, while the rest of the variables are optional. If you include a variable that is only used for some rows, you can use NA for the rows where it's not used. The items data of a timeline can either be set by supplying the data argument to timevis(), or by calling the setItems function.

Groups

The groups parameter must be provided if the data items have groups (ie. if any of the items have a group variable). When using groups, all items with the same group are placed on one line. A vertical axis is displayed showing the group names. Grouping items can be useful for a wide range of applications, for example when showing availability of multiple people, rooms, or other resources next to each other. You can also think of groups as "adding a Y axis".

The following is a subset of the variables supported in the groups dataframe. The full list of supported variables can be found in the official visjs documentation.

id and content are the only required variables for each group, while the rest of the variables are optional. If you include a variable that is only used for some rows, you can use NA for the rows where it's not used. The groups data of a timeline can either be set by supplying the groups argument to timevis(), or by calling the setGroups function.

Getting data out of a timeline in Shiny

When a timeline widget is created in a Shiny app, there are four pieces of information that are always accessible as Shiny inputs. These inputs have special names based on the timeline's id. Suppose that a timeline is created with an outputId of "mytime", then the following four input variables will be available:

All four inputs will return a value upon initialization of the timeline and every time the corresponding value is updated.

Extending timevis

If you need to perform any actions on the timeline object that are not supported by this package's API, you may be able to do so by manipulating the timeline's JavaScript object directly. The timeline object is available via document.getElementById("id").widget.timeline (replace id with the timeline's id).

This timeline object is the direct widget that vis.js creates, and you can see the visjs documentation to see what actions you can perform on that object.

Customizing the timevis look and style using CSS

To change the styling of individual items or group labels, use the className and style columns in the data or groups dataframes.

When running a Shiny app, you can use CSS files to apply custom styling to other components of the timevis widget. When using timevis outside of a Shiny app, you can use CSS in the following way:

tv <- timevis(
  data.frame(
    content = "Today",
    start = Sys.Date()
  )
)

style <- "
.vis-timeline {
  border-color: #269026;
  background-color: lightgreen;
  font-size: 15px;
  color: green;
}

.vis-item {
  border: 2px solid #5ace5a;
  font-size: 12pt;
  background: #d9ffd9;
  font-family: cursive;
  padding: 5px;
}
"

tv <- tagList(tags$style(style), tv)
htmltools::html_print(tv)

See Also

Demo Shiny app

Examples

## Not run: 
# For more examples, see https://daattali.com/shiny/timevis-demo/

#----------------------- Most basic -----------------
timevis()

#----------------------- Minimal data -----------------
timevis(
  data.frame(id = 1:2,
             content = c("one", "two"),
             start = c("2016-01-10", "2016-01-12"))
)

#----------------------- Hide the zoom buttons, allow items to be editable -----------------
timevis(
  data.frame(id = 1:2,
             content = c("one", "two"),
             start = c("2016-01-10", "2016-01-12")),
  showZoom = FALSE,
  options = list(editable = TRUE, height = "200px")
)

#----------------------- You can use %>% pipes to create timevis pipelines -----------------
timevis() %>%
  setItems(data.frame(
    id = 1:2,
    content = c("one", "two"),
    start = c("2016-01-10", "2016-01-12")
  )) %>%
  setOptions(list(editable = TRUE)) %>%
  addItem(list(id = 3, content = "three", start = "2016-01-11")) %>%
  setSelection("3") %>%
  fitWindow(list(animation = FALSE))

#------- Items can be a single point or a range, and can contain HTML -------
timevis(
  data.frame(id = 1:2,
             content = c("one", "two<br><h3>HTML is supported</h3>"),
             start = c("2016-01-10", "2016-01-18"),
             end = c("2016-01-14", NA),
             style = c(NA, "color: red;")
  )
)

#----------------------- Alternative look for each item -----------------
timevis(
  data.frame(id = 1:2,
             content = c("one", "two"),
             start = c("2016-01-10", "2016-01-14"),
             end = c(NA, "2016-01-18"),
             type = c("point", "background"))
)

#----------------------- Using a function in the configuration options -----------------
timevis(
  data.frame(id = 1,
             content = "double click anywhere<br>in the timeline<br>to add an item",
             start = "2016-01-01"),
  options = list(
    editable = TRUE,
    onAdd = htmlwidgets::JS('function(item, callback) {
      item.content = "Hello!<br/>" + item.content;
      callback(item);
    }')
  )
)


#----------------------- Using a custom format for hours ------------------
timevis(
  data.frame(
    id = 1:2,
    content = c("one", "two"),
    start = c("2020-01-10", "2020-01-10 04:00:00")
  ),
  options = list(
    format = htmlwidgets::JS("{ minorLabels: { minute: 'h:mma', hour: 'ha' }}")
  )
)

#----------------------- Allowing editable items to "snap" to round hours only -------------
timevis(
  data.frame(
    id = 1:2,
    content = c("one", "two"),
    start = c("2020-01-10", "2020-01-10 04:00:00")
  ),
  options = list(
    editable = TRUE,
    snap = htmlwidgets::JS("function (date, scale, step) {
         var hour = 60 * 60 * 1000;
         return Math.round(date / hour) * hour;
     }")
  )
)

#----------------------- Using groups -----------------
timevis(data = data.frame(
  start = c(Sys.Date(), Sys.Date(), Sys.Date() + 1, Sys.Date() + 2),
  content = c("one", "two", "three", "four"),
  group = c(1, 2, 1, 2)),
  groups = data.frame(id = 1:2, content = c("G1", "G2"))
 )

#----------------------- Using nested groups --------------------
timevis(
  data = data.frame(
    start = c("2022-01-01", "2022-01-02", "2022-01-03", "2022-01-04", "2022-01-05"),
    content = c("item 1", "item 2", "item 3", "item 4", "item 5"),
    group = 1:5
  ),
  groups = data.frame(
    id = 1:5,
    content = c("John", "Lee", "Clean", "Cook", "Shop"),
    nestedGroups = I(list(c(3, 4), 5, NA, NA, NA))
  )
)

## End(Not run)
#----------------------- Getting data out of the timeline into Shiny -----------------
if (interactive()) {
library(shiny)

data <- data.frame(
  id = 1:3,
  start = c("2015-04-04", "2015-04-05 11:00:00", "2015-04-06 15:00:00"),
  end = c("2015-04-08", NA, NA),
  content = c("<h2>Vacation!!!</h2>", "Acupuncture", "Massage"),
  style = c("color: red;", NA, NA)
)

ui <- fluidPage(
  timevisOutput("appts"),
  div("Selected items:", textOutput("selected", inline = TRUE)),
  div("Visible window:", textOutput("window", inline = TRUE)),
  tableOutput("table")
)

server <- function(input, output) {
  output$appts <- renderTimevis(
    timevis(
      data,
      options = list(editable = TRUE, multiselect = TRUE, align = "center")
    )
  )

  output$selected <- renderText(
    paste(input$appts_selected, collapse = " ")
  )

  output$window <- renderText(
    paste(input$appts_window[1], "to", input$appts_window[2])
  )

  output$table <- renderTable(
    input$appts_data
  )
}
shinyApp(ui, server)
}
[Package timevis version 2.1.0 Index]