Repository files navigation

{timevis} lets you create rich andfully interactive timelinevisualizations in R. Timelines can be included in Shiny apps or Rmarkdown documents.{timevis} includes an extensive API to manipulate a timeline aftercreation, and supports getting data out of the visualization into R.This package is based on thevisjs TimelineJavaScript library.

Need Shiny help?I'm available for consulting.
If you find {timevis} useful, please considersupporting my work! ❤

This package is part of a larger ecosystem of packages with a shared vision: solving common Shiny issues and improving Shiny apps with minimal effort, minimal code changes, and clear documentation. Other packages for your Shiny apps:

Click here to view aninteractive demo of many {timevis} features.

If you create a cool timeline with {timevis}, I’d lovetohear about it!

There are no sponsors yet

Become the first sponsor for{timevis}!

• Installation
• How to use
• Slightly more advanced examples
• Interactivity
• Groups
• Functions to manipulate a timeline
• In a Shiny app
  • Retrieving data from the widget
• Crosstalk support

For most users: To install the stable CRAN version:

install.packages("timevis")

For advanced users: To install the latest development version from GitHub:

install.packages("remotes")remotes::install_github("daattali/timevis")

You can view a minimal timeline without any data by simply running

library(timevis)timevis()

You can add data to the timeline by supplying a data.frame

data<-data.frame(id=1:4,content= c("Item one"  ,"Item two"  ,"Ranged item","Item four"),start= c("2016-01-10","2016-01-11","2016-01-20","2016-02-14 15:00:00"),end= c(NA          ,NA,"2016-02-04",NA))timevis(data)

Every item must have acontent and astart variable. If the item isa time range rather than a single point in time, you can supply anend aswell.id is only required if you want to access or manipulate an item.

There are more variables that can be used in the data.frame – they areall documented in the help file for?timevis() under theDataformat section.

By default, a timeline will show the current date as a red vertical lineand will have zoom in/out buttons. You can supply many customizationoptions totimevis() in order to get it just right (see?timevis()for details).

The content of an item can even include HTML, which makes it easy toshow any kind of data in a timeline, such as the matches of the 2014World Cup:

If you know some CSS, you can completely customize the look of thetimeline:

The timeline lets the user interact with it seamlessly. You can click onthe zoom in/out buttons or drag the timeline left/right in order to moveto past/future dates.

If you set theeditable = TRUE option, then the user will be able toadd new items by double clicking, modify items by dragging, and deleteitems by selecting them.

You can use the groups feature to group together multiple items into"buckets". When using groups, all items with the same groupare placed on one line. A vertical axis is displayed showing the groupnames. Grouping items can be useful for a wide range of applications,for example when showing availability of multiple people, rooms, orother resources next to each other. You can also think of groups as"adding a Y axis".

Here is an example of a timeline that has four groups: "Gym", "Pool", "Sauna", "Hot Tub":

In order to use groups, items in the data need to have group ids, and aseparate dataframe containing the group information needs to beprovided. More information about using groups is available in the help file for?timevis() under theGroupssection.

Groups can also contain nested groups. The next example is similar to the previous one, except"Sauna" and "Hot Tub" are now nested under "Pool":

Refer to thevisjs Timeline documentation to see all the options that are supported.

There are many functions that allow programmatic manipulation of atimeline. For example:addItem() programmatically adds a new item,centerItem() moves the timeline so that a given item is centered,setWindow() sets the start and end dates of the timeline,setOptions() updates the configuration options, and many morefunctions are available.

There are two ways to call these timeline manipulation functions:

You can manipulate a timeline widget during its creation by chainingfunctions to thetimevis() call. For example:

timevis() %>%  addItem(list(id = "item1", content = "one", start = "2016-08-01")) %>%  centerItem("item1")

This method of manipulating a timeline is especially useful whencreating timeline widgets in the R console or in R markdown documentsbecause it can be used directly when initializing the widget.

In Shiny apps, you can manipulate a timeline widget at any point afterits creation by referring to its ID. For example:

library(shiny)ui <- fluidPage(  timevisOutput("mytime"),  actionButton("btn", "Add item and center"))server <- function(input, output, session) {  output$mytime <- renderTimevis(timevis())  observeEvent(input$btn, {    addItem("mytime", list(id = "item1", content = "one", start = "2016-08-01"))    centerItem("mytime", "item1")  })}shinyApp(ui = ui, server = server)

You can even chain these functions and use this manipulation codeinstead of the bold code:

addItem("mytime", list(id = "item1", content = "one", start = "2016-08-01")) %>%  centerItem("item1")

Technical note: If you’re trying to understand how both methods oftimeline manipulation work, it might seem very bizarre to you. Thereason they work is that every manipulation function accepts either atimevis object or the ID of one. In order to make chaining work, thereturn value from these functions depend on the input: if atimevisobject was given, then an updatedtimevis object is returned, and ifan ID was given, then the same ID is returned.

If you need to perform any actions on the timeline object that are not supported by the {timevis} API, you may be able to do so by manipulating the timeline's JavaScript object directly. The timeline object is available viadocument.getElementById("id").widget.timeline (replaceid with the timeline's id).

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

You can add a timeline to a Shiny app by addingtimevisOutput() to theUI andrenderTimevis(timevis()) to the server.

It is possible to retrieve data from a timeline in a Shiny app. When atimeline widget is created in a Shiny app, there are four pieces ofinformation that are always accessible as Shiny inputs. These inputshave special names based on the timeline’s id. Suppose that a timelineis created with anoutputId of"mytime", then the following fourinput variables will be available:

• input$mytime_data - will return a data.frame containing thedata of the items in the timeline. The input is updated every timean item is modified, added, or removed.
• input$mytime_ids - will return the IDs (a vector) of all theitems in the timeline. The input is updated every time an item isadded or removed from the timeline.
• input$mytime_selected - will return the IDs (a vector) of theselected items in the timeline. The input is updated every time anitem is selected or unselected by the user. Note that this will notget updated if an item is selected programmatically using the APIfunctions.
• input$mytime_window - will return a 2-element vector containingthe minimum and maximum dates currently visible in the timeline. Theinput is updated every time the viewable window of dates is updated(by zooming or moving the window).
• input$mytime_visible - will return a list of IDs of itemscurrently visible in the timeline.

{timevis} is fully compatible withcrosstalk. This means that you can provide it with a crosstalkSharedData object to select/filter data across multiple Shiny widgets.

Here is a simple example:

df<-data.frame(start= c(Sys.Date(), Sys.Date()-1, Sys.Date()-2),content=1:3)shared_df<-crosstalk::SharedData$new(df)crosstalk::bscols(  timevis(shared_df,options=list(multiselect=TRUE),showZoom=FALSE,width="100%"),DT::datatable(shared_df))

If you select any events in the timeline (usectrl orshift to select multiple events), then the table will automatically select those as well, and vice versa.

You can view examples of many of the features supported by checking outthedemo Shiny app. If youwant to see how those examples were created, the full code for theexamples is insideinst/example.

Lastly, if you want to learn how to develop an htmlwidget to havesimilar features as this package, you can check out thetimevisBasic package ormy tutorial on htmlwidgetstips.

Logo design byAlfredo Hernández.