sugrrants (version 0.1.0)

frame_calendar: Rearrange a temporal data frame to a calendar-based data format using linear algebra

Description

Temporal data of daily intervals or higher frequency levels can be organised into a calendar-based format, which is useful for visually presenting calendar-related activities or multiple seasonality (such as time of day, day of week, day of month). The function only returns a rearranged data frame, and ggplot2 takes care of the plotting afterwards. It allows more flexibility for users to visualise the data in various ways.

Usage

frame_calendar(data, x, y, date, calendar = "monthly", dir = "h",
  sunday = FALSE, nrow = NULL, ncol = NULL, polar = FALSE,
  scale = "fixed", width = 0.95, height = 0.95)
prettify(plot, label = c("label", "text"), locale, abbr = TRUE, ...)

Arguments

data

A data frame or a grouped data frame including a Date variable.

x

A bare (or unquoted) variable mapping to x axis, for example time of day. If integer 1 is specified, it simply returns calendar grids on x without transformation.

y

A bare (or unquoted) variable or more mapping to y axis. More than one variable need putting to vars(). If integer 1 is specified, it returns calendar grids on y without transformation.

date

A Date variable mapping to dates in the calendar.

calendar

Type of calendar. "monthly" calendar (the default) organises the data to a common format comprised of day of week in the column and week of month in the row. "weekly" calendar consists of day of week and week of year. "daily" calendar refers to day of month and month of year.

dir

Direction of calendar: "h" for horizontal (the default) or "v" for vertical.

sunday

FALSE (the default) indicating to starting with Monday in a week, or TRUE for Sunday, when calendar = "monthly".

nrow, ncol

Number of rows and columns defined for "monthly" calendar layout. If NULL, it computes a sensible layout.

polar

FALSE (the default) for Cartesian or TRUE for polar coordinates.

scale

"fixed" (the default) for fixed scale. "free" for scaling conditional on each daily cell, "free_wday" for scaling on weekdays, "free_mday" for scaling on day of month.

width, height

Numerics between 0 and 1 to specify the width/height for each glyph.

plot

ggplot object

label

If "label" is specified, it will add month/week text on the ggplot object, which is actually passed to geom_label(). If "text" is specified, it will add weekday/day of month text on the ggplot object, which is actually passed to geom_text(). By default, both "label" and "text" are used. If "text2" is specified for the "monthly" calendar only, it will add day of month to the ggplot object.

locale

ISO 639 language code. The default is "en" (i.e. US English). See readr::locale for more details.

abbr

Logical to specify if the abbreviated version of label should be used.

...

Extra arguments passed to geom_label() and geom_text()

Value

A data frame or a tibble with newly added columns of .x, .y. .x and .y together give new coordinates computed for different types of calendars. date groups the same dates in a chronological order, which is useful for geom_line or geom_path. The basic use is ggplot(aes(x = .x, y = .y, group = date)) + geom_*. The variable names .x and .y reflect the actual x and y with a prefix ..

Details

The calendar-based graphic can be considered as small multiples of sub-series arranged into many daily cells. For every multiple (or facet), it requires the x variable mapped to be time of day and y to value. New x and y are computed and named with a . prefixed to variable according to x and y respectively, and get ready for ggplot2 aesthetic mappings. In conjunction with group_by(), it allows the grouped variable to have their individual scales. For more details, see vignette("frame-calendar", package = "sugrrants")

Examples

# NOT RUN {
   library(dplyr)
   # compute the calendar layout for the data frame
   calendar_df <- pedestrian %>%
     filter(Sensor_ID == 13) %>% 
     frame_calendar(x = Time, y = Hourly_Counts, date = Date, nrow = 4)

   # ggplot
   p1 <- calendar_df %>% 
     ggplot(aes(x = .Time, y = .Hourly_Counts, group = Date)) +
     geom_line()
   prettify(p1)
   
   # use in conjunction with group_by()
   grped_calendar <- pedestrian %>% 
     filter(Year == "2017", Month == "March") %>% 
     group_by(Sensor_Name) %>% 
     frame_calendar(
       x = Time, y = Hourly_Counts, date = Date, sunday = TRUE
     )
   
   p2 <- grped_calendar %>% 
     ggplot(aes(x = .Time, y = .Hourly_Counts, group = Date)) +
     geom_line() +
     facet_wrap(~ Sensor_Name, nrow = 2)
   prettify(p2)
   
# }
# NOT RUN {
     # allow for different languages
     # below gives the simplief chinese label along with STKaiti font family 
     # if this font is installed in user's local system
     prettify(p2, locale = "zh", family = "STKaiti")
   
# }
# NOT RUN {
# }