Shift time stamps in ts-boxable time series, either by a number of periods or by a fixed amount of time.

ts_lag(x, by = 1)



ts-boxable time series, an object of class ts, xts, zoo, data.frame, data.table, tbl, tbl_ts, tbl_time, or timeSeries.


integer or character, either the number of shifting periods (integer), or an absolute amount of time (character). See details.


a ts-boxable time series, with the same class as the input. If time stamp shifting causes the object to be irregular, a data frame is returned.


The lag order, by, is defined the oposite way as in R base. Thus, -1 is a lead and +1 a lag.

If by is integer, the time stamp is shifted by the number of periods. This requires the series to be regular.

If by is character, the time stamp is shifted by a specific amount of time. This can be one of one of "sec", "min", "hour", "day", "week", "month", "quarter" or"year", optionally preceded by a (positive or negative) integer and a space, or followed by plural "s". This is passed to base::seq.Date(). This does not require the series to be regular.


ts_plot(AirPassengers, ts_lag(AirPassengers), title = "Illustrating the need for glasses")
head(ts_lag(AirPassengers, "1 month"))
#> Feb Mar Apr May Jun Jul #> 1949 112 118 132 129 121 135
head(ts_lag(AirPassengers, "1 year"))
#> Jan Feb Mar Apr May Jun #> 1950 112 118 132 129 121 135
head(ts_lag(ts_df(AirPassengers), "2 day"))
#> time value #> 1 1949-01-03 112 #> 2 1949-02-03 118 #> 3 1949-03-03 132 #> 4 1949-04-03 129 #> 5 1949-05-03 121 #> 6 1949-06-03 135
# head(ts_lag(ts_df(AirPassengers), "2 min")) not yet working