Supporting Graphs for Analysing Time Series

Provides 'ggplot2' graphics for analysing time series data. It aims to fit into the 'tidyverse' and grammar of graphics framework for handling temporal data.

Travis-CI BuildStatus CoverageStatus CRAN_Status_Badge Downloads

The goal of sugrrants is to provide supporting graphs with R for analysing time series data. It aims to fit into the tidyverse and grammar of graphics framework for handling temporal data.


You could install the stable version on CRAN:


You could also install the development version from Github using:

# install.packages("devtools")
devtools::install_github("earowang/sugrrants", build_vignettes = TRUE)


Calendar-based graphics

The fully-fledged faceting calendar facet_calendar() unlocks day-to-day stories.

pedestrian %>%
  filter(Date < as.Date("2016-05-01")) %>% 
  ggplot(aes(x = Time, y = Hourly_Counts, colour = Sensor_Name)) +
  geom_line() +
  facet_calendar(~ Date) + # a variable contains dates
  theme(legend.position = "bottom")

On the other hand, the frame_calendar() provides tools for re-structuring the data into a compact calendar layout, without using the faceting method. It is fast and light-weight, although it does not preserve the values.

p <- pedestrian %>%
  filter(Sensor_ID == 9, Year == 2016) %>%
  mutate(Weekend = if_else(Day %in% c("Saturday", "Sunday"), "Weekend", "Weekday")) %>%
  frame_calendar(x = Time, y = Hourly_Counts, date = Date) %>% 
  ggplot(aes(x = .Time, y = .Hourly_Counts, group = Date, colour = Weekend)) +
  geom_line() +
  theme(legend.position = "bottom")

Google Summer of Code 2017

This package is part of the project—Tidy data structures and visual methods to support exploration of big temporal-context data, which has been participated in Google Summer of Code 2017 (gsoc), for R project for statistical computing.

A new function frame_calendar() [here and here] in the sugrrants package has been developed and documented for calendar-based graphics. I have also written a vignette [source and reader view], which introduces and demonstrates the usage of the frame_calendar() function. Many unit tests have been carried out to ensure the expected performance of this function. The function implements non-standard evaluation and highlights the tidy evaluation in action. The initial release (v0.1.0) of the package has been published on CRAN during the gsoc summer time.

I have initialised a new R package tsibble for tidy temporal data, as part of the project. The tsibble() function constructs a new tbl_ts class for temporal data, and the as_tsibble() helps to convert a few ts objects into the tbl_ts class. Some key verbs (generics) from the dplyr package, such as mutate(), summarise(), filter(), have been defined and developed for the tbl_ts data class. The tsibble package was highly experimental over the period of the gsoc [commits], and these functions are very likely to be changed or improved in the future.

A new package rwalkr has been created and released on CRAN during the gsoc summer. This package provides API to Melbourne pedestrian sensor data and arrange the data in tidy temporal data form. Two functions including walk_melb() and shine_melb(), have been written and documented as the v0.1.0 and v0.2.0 releases on CRAN. The majority of the code for the function run_melb() has been done, but the interface needs improving after the gsoc.


The acronym of sugrrants is SUpporting GRaphs with R for ANalysing Time Series, pronounced as “sugar ants” that are a species of ant endemic to Australia.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.


sugrrants 0.2.4

  • Started to issue an warning when the deprecated argument sunday is present in frame_calendar().
  • Fixed week day labels in prettify() inconsistent with user-specified week_start.
  • Added ... to frame_calendar() S3 generic.

sugrrants 0.2.3

This is a patch release for the changes in tsibble.

sugrrants 0.2.2

This is a maintenance release.

  • facet_calendar() now accepts calls in the argument date. (#14)

sugrrants 0.2.1

This is a patch release for the changes in tsibble.

sugrrants 0.2.0

  • Added a new faceting method facet_calendar().
  • Added new argument week_start into frame_calendar()
  • Soft-deprecated sunday argument in frame_calendar() and will start issuing warnings in the next release.

sugrrants 0.1.6

  • Removed dependency on tidyr.
  • Improved default margin between monthly grids in frame_calendar().

sugrrants 0.1.5

  • Avoid strong dependency on tsibble & readr.

sugrrants 0.1.4

  • Retired au_holiday(), since tsibble offers a complete version in holiday_aus().
  • Made prettify() S3 generic, and added support for plotly object. (#9)
  • Removed purrr dependency.
  • Added plotly as Suggests.

sugrrants 0.1.3

  • Deprecated au_holiday(), as a complete function holiday_aus() is available in the tsibble package.
  • Fixed grouped_df issue to be compatible with ggplot2 v3.0.0.

sugrrants 0.1.2

  • Added a new argument margin = NULL to allow users for margin adjustment between month panels.
  • Fixed variable scoping issues in frame_calendar().
  • frame_calendar() added support to tsibble or tbl_ts.
  • Added tsibble as Imports.
  • Improved frame_calendar() in conjunction with group_by() for incomplete time series (#3).
  • Fixed y axis limits only depending on the first variable when using multiple variables (#5).

sugrrants 0.1.1

Dropped functions

  • dropped an internal function wday2() since the lubridate v1.7.1 added a new argument week_start in the wday().


  • frame_calendar(): arguments x and y support factor and hms class.
  • Added a note on AFL holiday for the documentation of au_holiday(state = "VIC").

sugrrants 0.1.0

  • Initial release
  • Added a file to track changes to the package.
  • Added the frame_calendar() function to compute calendar grids for visual representation of temporal data, coupled with a vignette.
  • Added the geom_acf() and stat_acf() functions to incorporate ACF/PACF plots into the grammar of graphics framework.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


0.2.8 by Earo Wang, a year ago

Report a bug at

Browse source code at

Authors: Earo Wang [aut, cre] , Di Cook [aut, ths] , Rob Hyndman [aut, ths]

Documentation:   PDF Manual  

Task views: Time Series Analysis

GPL (>= 3) license

Imports dplyr, grid, gtable, lubridate, rlang

Depends on ggplot2

Suggests covr, knitr, plotly, readr, rmarkdown, testthat, tidyr, tsibble, viridis

Imported by packageRank.

See at CRAN