Create a Sequence or Range of Times

A function to create a vector of time-based objects suitable for indexing an xts object, given a string conforming to the ISO 8601 time and date standard for range-based specification. The resultant series can be of any class supported by xts, including POSIXct, Date, chron, timeDate, yearmon, and yearqtr.

timeBasedRange creates a vector of length 1 or 2 as seconds since the epoch (1970-01-01) for use internally.

timeBasedSeq(x, retclass = NULL, length.out = NULL)

timeBasedRange(x, ...)


a string representing the time-date range desired


the return class desired


passed to seq internally



Designed to provide uniform creation of valid time-based objects for use within xts, the interface conforms (mostly) to the ISO recommended format for specifying ranges.

In general, the format is a string specifying a time and/or date from, to, and optionally by delineated by either ‘"/"’ or ‘"::"’.

The first argument need not be quoted, as it is converted internally if need be.

The general form is from/to/by or from::to::by, where to and by are optional if the length.out arg is specified.

The from and to elements of the string must be left-specified with respect to the standard CCYYMMDD HHMMSS form. All dates-times specified will be set to either the earliest point (from) or the latest (to), given the level of specificity.

For example ‘1999’ in the from field would set the start to the beginning of 1999. The opposite occurs in the to field.

The level of detail in the request is interpretted as the level of detail in the result. The maximum detail of either from or to is the basis of the sequence, unless the optional by element is specified, which will be covered later.

To request a yearly series, it is only necessary to use ‘"1999/2008"’. Alternately, one could request a monthly series (returned by default as class yearmon) with ‘"199901/2008"’ or ‘"1999-01/2008"’, or even ‘"1999/2008-01"’. As the level of granularity increases, so does the resultant sequence granularity - as does its length.

Using the optional third by field (the third delimited element to the string), will override the granularity intepretation and return the requested periodicity. The acceptable arguments include Y for years, m for months, d for days, H for hours, M for minutes and S for seconds.


A sequence or range of time-based objects.

If retclass is NULL, the result is a named list of from, to, by and length.out.


International Organization for Standardization: ISO 8601 http://www.iso.org

See Also

timeBased, xts

  • timeBasedSeq
  • timeBasedRange
library(xts) # NOT RUN { timeBasedSeq('1999/2008') timeBasedSeq('199901/2008') timeBasedSeq('199901/2008/d') timeBasedSeq('20080101 0830',length=100) # 100 minutes timeBasedSeq('20080101 083000',length=100) # 100 seconds # }
Documentation reproduced from package xts, version 0.9-7, License: GPL (>= 2)

Community examples

harlananelson@gmail.com at Apr 2, 2018 xts v0.10-1

## timeBasedSeq Example Create a sequence starting at `from` of length `length.out`. The first argument `x` indicates the `from`, `to`, and `BY` parameters. These are split using `/` or `::`. The function `strsplit(x,"/")` is used to parse. So you need all three pieces even if you aren't specifying an end point. The granularity is determined by the input: `2000` is year, `200001` is month. The `by` part, which is parced from the `x` parameter can have values in `list('Y','m','d','H','M','S')` ```{r} # 100 dates by month, result is of class "Date" dates <- timeBasedSeq('200002//',length.out = 100,retclass = "Date") dates <- timeBasedSeq('2000//m',length.out = 100,retclass = "Date") # 100 dates by year dates <- timeBasedSeq('2000//',length.out = 100,retclass = "Date") dates <- timeBasedSeq('2000//Y',length.out = 100,retclass = "Date") # 100 dates by second. You can use anything that a `as.*` method like as.POSIXct. dates <- timeBasedSeq('2000//S',length.out = 100,retclass = "POSIXct") ```