TimeWarp (version 1.0.15)

dateWarp: Date vector shifting and alignment

Description

Perform multiple shifts and alignments on Date vectors. dateWarp() is a generic, with methods for character, factor, Date, POSIXct, and POSIXlt.

Usage

dateWarp(date, spec, holidays = NULL, by = NULL, direction = 1,
         duplicates.keep = TRUE, optimize.dups=TRUE)
dateWarpAppend(date, ..., where = c("sorted", "start", "end"), empty.ok = FALSE,
               duplicates.ok = FALSE)

Arguments

date

a Date vector, or a character vector that can be converted to Date by dateParse.

spec

a specification of shifts and alignment tranformations. See ‘Details’.

holidays

a character string naming the holiday series (see holidays).

by

how to warp. Can be one of "days", "bizdays", "weeks", "months", or "years". "bizdays" can contain a holiday specification like: "bizdays@NYSEC"

direction

which direction to warp. a numeric value of 1 for the future, and -1 for the past (be careful about using variables for this value, for if it's value is negative and you place a minus sign in front of the variable, you'll go back to the future).

duplicates.keep

logical indicating whether or not to keep duplicate dates.

…

arguments to pass to dateWarp.

where

character string. can be "sorted" to sort the result instead of append, "start" to prepend, or "end" to append.

empty.ok

is it okay for the dates argument to be empty?

duplicates.ok

logical indicating whether or not to keep duplicate dates.

optimize.dups

If TRUE, internally optimize by not performing the same computation multiple times for duplicates. This does not change the return value.

Value

A date vector that is a transformed version of the input dates. Multiple shift or alignment transformations can be specified. If more that one is given, each vill be applied in turn to the result of the previous one. The class of the returned value is the same as the class of date for character, Date, POSIXct, and POSIXlt. For date of other classes, the class of the returned value is Date, but this may change in the future.

Details

spec specify tranformations in several ways:

• integer vector by which to shift the current Date object. The units of the shift are specified by the by argument. If the shift contains more than one element, this will transform a single Date object into a multiple-element Date object. It is an error to apply a multiple-element shift to a multiple element Date object.

• character data of the form "+3 bizdays@NYSEC", "+3 bizdays", or "+3". 'by' and 'holidays' specifications are extracted from the string as appropriate, and override any previously specified or given in arguments.

• a named list of elements. The elements can be lists or vectors. The names on the elements specify instructions:

  unique

  the actual value of the list element is ignored. The action is to remove duplicates from the results, i.e., make the dates unique.

  latest

  the value of the list element is a Date or a character that can be converted to a Date with dateParse. The dates will be clipped to be no later than the specified Date.

  earliest

  the value of the list element is a Date or a character that can be converted to a Date with dateParse. The dates will be clipped to be no earlier than the specified Date.

  shift

  the spec list element is a list that will be used as arguments to a call of dateShift. If any are not specified in the list, the values of the by, holidays, and direction arguments given to dateWarp() are passed to dateShift.

  align

  the spec list element is a list that will be used as arguments to a call of dateAlign. If any are not specified in the list, the values of the by, holidays, and direction arguments given to dateWarp() are passed to dateShift.

  If not all arguments are not provided, the dateWarp arguments will be used instead.

See Also

dateAlign, dateShift, dateMatch, dateParse, and dateSeq

The Holidays package contains holidays data, which is registered with the TimeWarp package when the Holidays package is loaded.

Examples

# NOT RUN {
library(Holidays)
dates <- dateSeq("2001/12/20", by = 'bizdays', len = 9, holidays = "NYSEC")
dateWarp(dates, -1:1, by = "bizdays", holidays = "NYSEC", duplicates.keep = FALSE)
dateWarp(dates, "+1 bizdays@NYSEC")
dateWarp(dates, list(0:6), by = "bizdays@NYSEC")
dateWarp(dates, list(-1:1, unique = TRUE), by = "bizdays")
dateWarp(dates, list(latest = "2001/12/25"))
x <- dateSeq("2001/01/01", len = 4, by = "weeks")
dateWarp(dates, list(align = list(to = x, how = "after")))
dateWarp(dates, list(shift = list(by = "bizdays", k.by = 2, direction = 1, holidays = "NYSEC"),
                     shift = 2),
         by = "days", direction = -1,
holidays = "NONE")
dateWarp(dates, hol = "NYSEC",
         list(shift = list(k.by = 1, by = "months"),
         shift=list(k.by = -1, by = "bizdays")))
dateWarp(dates, list(align = list(by = "bizdays"),
                     shift = list(by = "months", k.by = 2), holidays = "JPNEX"))

# Options expirations dates in 2008
(d1 <- dateSeq('2008-01-01', len=12, by='months'))
(d2 <- dateAlign(d1, by='months', dir=-1))
(d3 <- dateAlign(d2, by='weeks', week.align=5))
(d4 <- dateWarp(d3, 14, by='days'))
(d5 <- dateAlign(d4, by='bizdays@NYSEC', dir=-1))
# Version that uses a list 'spec' to dateWarp
dateWarp(d1, list(align=list(by='months', dir=-1),
                  align=list(by='weeks', week.align=5),
                  shift=list(by='days', 14),
                  align=list(by='bizdays@NYSEC', dir=-1)))
# In 2008 the March options expiration is a Thursday because Friday was a holiday
dateDow(d5)
# }