• Stars
    star
    648
  • Rank 67,714 (Top 2 %)
  • Language
    R
  • License
    Other
  • Created almost 8 years ago
  • Updated 10 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

๐Ÿ“… Create interactive timeline visualizations in R

timevis

๐Ÿ“… Create interactive timeline visualizations in R

Demo ยท by Dean Attali

R build status CRAN version


{timevis} lets you create rich and fully interactive timeline visualizations in R. 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. This package is based on the visjs Timeline JavaScript library.

Need Shiny help? I'm available for consulting.
If you find {timevis} useful, please consider supporting 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:

Package Description Demo
shinyjs ๐Ÿ’ก Easily improve the user experience of your Shiny apps in seconds ๐Ÿ”—
shinyalert ๐Ÿ—ฏ๏ธ Easily create pretty popup messages (modals) in Shiny ๐Ÿ”—
shinyscreenshot ๐Ÿ“ท Capture screenshots of entire pages or parts of pages in Shiny apps ๐Ÿ”—
shinycssloaders โŒ› Add loading animations to a Shiny output while it's recalculating ๐Ÿ”—
colourpicker ๐ŸŽจ A colour picker tool for Shiny and for selecting colours in plots ๐Ÿ”—
shinybrowser ๐ŸŒ Find out information about a user's web browser in Shiny apps ๐Ÿ”—
shinydisconnect ๐Ÿ”Œ Show a nice message when a Shiny app disconnects or errors ๐Ÿ”—
shinytip ๐Ÿ’ฌ Simple flexible tooltips for Shiny apps WIP
shinymixpanel ๐Ÿ” Track user interactions with Mixpanel in Shiny apps or R scripts WIP
shinyforms ๐Ÿ“ Easily create questionnaire-type forms with Shiny WIP

Demo

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

If you create a cool timeline with {timevis}, Iโ€™d love to hear about it!

Sponsors ๐Ÿ†

There are no sponsors yet

Become the first sponsor for {timevis}!

Table of contents

Installation

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

How to use

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

library(timevis)
timevis()

Minimal timeline

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)

Basic timeline

Every item must have a content and a start variable. If the item is a time range rather than a single point in time, you can supply an end as well. 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 are all documented in the help file for ?timevis() under the Data format section.

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

Slightly more advanced examples

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

World cup timeline

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

Custom style timeline

Interactivity

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

If you set the editable = TRUE option, then the user will be able to add new items by double clicking, modify items by dragging, and delete items by selecting them.

Groups

You can use the groups feature to group together multiple items into "buckets". 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".

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

Groups timeline

In order to use groups, items in the data need to have group ids, and a separate dataframe containing the group information needs to be provided. More information about using groups is available in the help file for ?timevis() under the Groups section.

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

Nested groups timeline

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

Functions to manipulate a timeline

There are many functions that allow programmatic manipulation of a timeline. 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 more functions are available.

There are two ways to call these timeline manipulation functions:

1. Timeline manipulation using %>% on timevis()

You can manipulate a timeline widget during its creation by chaining functions to the timevis() 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 when creating timeline widgets in the R console or in R markdown documents because it can be used directly when initializing the widget.

2. Timeline manipulation using a timelineโ€™s ID

In Shiny apps, you can manipulate a timeline widget at any point after its 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 code instead 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 of timeline manipulation work, it might seem very bizarre to you. The reason they work is that every manipulation function accepts either a timevis object or the ID of one. In order to make chaining work, the return value from these functions depend on the input: if a timevis object was given, then an updated timevis object is returned, and if an ID was given, then the same ID is returned.

Extending timevis

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

In a Shiny app

You can add a timeline to a Shiny app by adding timevisOutput() to the UI and renderTimevis(timevis()) to the server.

Retrieving data from the widget

It is possible to retrieve data from a timeline in a Shiny app. 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:

  • input$mytime_data - will return a data.frame containing the data of the items in the timeline. The input is updated every time an item is modified, added, or removed.
  • input$mytime_ids - will return the IDs (a vector) of all the items in the timeline. The input is updated every time an item is added or removed from the timeline.
  • input$mytime_selected - will return the IDs (a vector) of the selected items in the timeline. The input is updated every time an item is selected or unselected by the user. Note that this will not get updated if an item is selected programmatically using the API functions.
  • input$mytime_window - will return a 2-element vector containing the minimum and maximum dates currently visible in the timeline. The input 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 items currently visible in the timeline.

Crosstalk support

{timevis} is fully compatible with crosstalk. This means that you can provide it with a crosstalk SharedData 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 (use ctrl or shift 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 out the demo Shiny app. If you want to see how those examples were created, the full code for the examples is inside inst/example.

Lastly, if you want to learn how to develop an htmlwidget to have similar features as this package, you can check out the timevisBasic package or my tutorial on htmlwidgets tips.

Credits

Logo design by Alfredo Hernรกndez.

More Repositories

1

beautiful-jekyll

โœจ Build a beautiful and simple website in literally minutes. Demo at https://beautifuljekyll.com
HTML
5,204
star
2

advanced-shiny

๐Ÿคน Shiny tips & tricks for improving your apps and solving common problems
R
1,184
star
3

addinslist

๐Ÿ“œ Discover and install useful RStudio addins
R
834
star
4

shinyjs

๐Ÿ’ก Easily improve the user experience of your Shiny apps in seconds
R
725
star
5

shinycssloaders

โŒ› Add loading animations to a Shiny output while it's recalculating
CSS
393
star
6

ggExtra

๐Ÿ“Š Add marginal histograms to ggplot2, and more ggplot2 enhancements
R
376
star
7

shiny-server

My personal Shiny server
R
249
star
8

shinyalert

๐Ÿ—ฏ๏ธ Easily create pretty popup messages (modals) in Shiny
R
238
star
9

oldschool-github-extension

Revert GitHub's UI back to its classic look (before the June 23, 2020 update that has a flat, rounded and more whitespaced design).
CSS
227
star
10

colourpicker

๐ŸŽจ A colour picker tool for Shiny and for selecting colours in plots (in R)
JavaScript
210
star
11

shinyforms

๐Ÿ“ Easily create questionnaire-type forms with Shiny
R
162
star
12

shinyscreenshot

๐Ÿ“ท Capture screenshots of entire pages or parts of pages in Shiny apps
R
68
star
13

shinydisconnect

๐Ÿ”Œ Show a nice message when a Shiny app disconnects or errors
R
65
star
14

ddpcr

๐Ÿ”ฌ Analysis and visualization of Droplet Digital PCR data in R and on the web
R
60
star
15

daattali.github.io

Dean Attali's website - R/Shiny Consultant
HTML
57
star
16

shinybrowser

๐ŸŒ Find out information about a user's web browser in Shiny apps
R
40
star
17

lightsout

๐Ÿ”ฆ Lights Out game implemented in R
R
39
star
18

rsalad

A mix of useful R functions that are good for you
R
26
star
19

UBC-STAT545

My first 12 months with R, mostly through a UBC course and my own experiments
HTML
23
star
20

timevisBasic

Helper package to learn advanced 'htmlwidgets' tips
R
22
star
21

statsTerrorismProject

Final project for STAT545A - Terrorist activity data analysis
HTML
21
star
22

gslides-betternotes-extension

The slide previews in the Speaker Notes window of Google Slides are tiny and unreadable. This extension automatically resizes the slides when the window is resized, and allows the user to drag the sidebar to select a size.
JavaScript
21
star
23

github-diff-navigator-extension

Chrome/Firefox extension that allows you to easily navigate through the changes in a file that has been edited on GitHub.
JavaScript
19
star
24

shinytip

๐Ÿ’ฌ Simple flexible tooltips for Shiny apps
R
17
star
25

shinyfilebrowser

๐Ÿ“ Simple file browser and list selector for Shiny apps
R
16
star
26

rasperry-pi-gaming-console-setup

How to set up raspberry pi as a portable oldies gaming console
13
star
27

cranalerts

Get email alerts when a CRAN package gets updated
R
11
star
28

shinymixpanel

๐Ÿ” Track user interactions with Mixpanel in Shiny apps or R scripts
R
11
star
29

shiny-mini-workshop

Shiny Mini Workshop
R
9
star
30

settlers-catan-turn-analyzer

Settlers of Catan Turn Analyzer - a simple app to teach myself ReactJS
JavaScript
8
star
31

single-page-amazon-return-labels-extension

Print Amazon return labels as a single page
JavaScript
8
star
32

shinycodeviewer

๐Ÿ“ View and edit a series of code chunks with syntax highlighting in Shiny
R
7
star
33

undomanager

๐Ÿ”„ Generic undo/redo manager for R
R
7
star
34

shiny-colour-gradient-input

Colour gradient input for R-Shiny
R
6
star
35

shiny-workshop-odsc2019

Shiny Workshop at ODSC 2019 (visualizing NBA 2018/19 player stats)
R
5
star
36

cashflow-calculation-extension

Cashflow Calculator extension for Zillow, Trulia, and Redfin (works in Chrome/Firefox/Edge)
JavaScript
5
star
37

smileyfy-my-facebook-extension

Chrome extension that adds infinite happiness to your Facebook browsing, plus a little bonus rickrolling :)
JavaScript
5
star
38

shinyHelpers

R
5
star
39

modularize-addin

RStudio addin to help modularize Shiny app code
R
4
star
40

useR2017

Analysis of useR2017 attendance information
R
3
star
41

bingo

Generate Bingo cards with R.
R
3
star
42

Rlist

Easy way to navigate and explore list structures in R (abandoned project)
R
2
star
43

dash2

R
2
star
44

shiny-training-rstudioconf-2018

R
2
star
45

presentations

A place for me to keep my presentations/papers/etc organized
2
star
46

pftv-ad-bypass-extension

Project Free TV shows an interstitial ad page before allowing users to continue to the video - this extension bypasses that page
JavaScript
2
star
47

attalitech

AttaliTech Ltd
CSS
1
star
48

shinywc

R
1
star
49

shiny-conf-nyr-2022

R
1
star
50

stat540-2014-attali-dean

Lab work for UBC STAT540
R
1
star
51

htmldependencybug

JavaScript
1
star
52

genes-track-demo

HTML
1
star