mutate_by_time: Mutate (for Time Series Data)

View source: R/dplyr-mutate_by_time.R

mutate_by_timeR Documentation

Mutate (for Time Series Data)


mutate_by_time() is a time-based variant of the popular dplyr::mutate() function that uses .date_var to specify a date or date-time column and .by to group the calculation by groups like "5 seconds", "week", or "3 months".


  .by = "day",
  .type = c("floor", "ceiling", "round")



A tbl object or data.frame


A column containing date or date-time values to summarize. If missing, attempts to auto-detect date column.


A time unit to summarise by. Time units are collapsed using lubridate::floor_date() or lubridate::ceiling_date().

The value can be:

  • second

  • minute

  • hour

  • day

  • week

  • month

  • bimonth

  • quarter

  • season

  • halfyear

  • year

Arbitrary unique English abbreviations as in the lubridate::period() constructor are allowed.


Name-value pairs. The name gives the name of the column in the output.

The value can be:

  • A vector of length 1, which will be recycled to the correct length.

  • A vector the same length as the current group (or the whole data frame if ungrouped).

  • NULL, to remove the column.

  • A data frame or tibble, to create multiple columns in the output.


One of "floor", "ceiling", or "round. Defaults to "floor". See lubridate::round_date.


A tibble or data.frame

See Also

Time-Based dplyr functions:

  • summarise_by_time() - Easily summarise using a date column.

  • mutate_by_time() - Simplifies applying mutations by time windows.

  • pad_by_time() - Insert time series rows with regularly spaced timestamps

  • filter_by_time() - Quickly filter using date ranges.

  • filter_period() - Apply filtering expressions inside periods (windows)

  • slice_period() - Apply slice inside periods (windows)

  • condense_period() - Convert to a different periodicity

  • between_time() - Range detection for date or date-time sequences.

  • slidify() - Turn any function into a sliding (rolling) function


# Libraries

# First value in each month
m4_daily_first_by_month_tbl <- m4_daily %>%
    group_by(id) %>%
        .date_var = date,
        .by       = "month", # Setup for monthly aggregation
        # mutate recycles a single value
        first_value_by_month  = first(value)

# Visualize Time Series vs 1st Value Each Month
m4_daily_first_by_month_tbl %>%
    tidyr::pivot_longer(value:first_value_by_month) %>%
    plot_time_series(date, value, name,
                     .facet_scale = "free", .facet_ncol = 2,
                     .smooth = FALSE, .interactive = FALSE)

timetk documentation built on Nov. 2, 2023, 6:18 p.m.