timeDateMethods {fBasics}R Documentation

timeDate Methods

Description

A collection of methods for objects of class 'timeDate'. Included are S3 methods for mathematical operations and for transformations between different representations of date/time objects.

IMPORTANT:
The timeDate and timeSeries classes are so far tested only under MS Windows XP operating system. Note, that your time zone environment variable must be set to "GMT". The reason for this is, that the functions work internally with "GMT" POSIX date and time objects whereas the Daylight Saving Time is added on top of this through the information in the Ical Calendar Library.

The methods are:

Math Operations with 'timeDate' Objects:
1 [.timeDate Extracts, replaces subsets from 'timeDate' objects,
2 +.timeDate Performs arithmetic + ops on 'timeDate' objects,
3 -.timeDate Performs arithmetic - ops on 'timeDate' objects,
4 Ops.timeDate 'Ops' generic functions for 'timeDate' objects,
5 diff.timeDate Returns suitably lagged and iterated differences,
6 difftimeDate Returns a difference of two 'timeDate' objects,
7 c.timeDate Concatenates objects of class 'timeDate',
8 rep.timeDate Replicates objects of class 'timeDate',
9 start.timeDate Extracts the first object of a 'timeDate' vector,
10 end.timeDate Extracts the last object of a 'timeDate' vector,
11 modify.timeDate Sorts, rounds or truncates a 'timeDate' object,
12 rev.timeDate Reverts a 'timeDate' vector object.
Transformations of 'timeDate' Objects:
1 as.character.timeDate Returns a 'timeDate' object as character string,
2 as.data.frame.timeDate Returns a 'timeDate' object as data frame,
3 as.POSIXct.timeDate Returns a 'timeDate' object as POSIXct object,
4 as.POSIXlt As POSIXlt, Use Method (Overwrite),
5 as.POSIXlt.default Default method for POSIXlt,
6 julian.timeDate Returns Julian day counts since 1970-01-01,
7 julian.POSIXt A Julian Patch,
8 atoms.timeDate Returns date/time atoms from a 'timeDate' object,
9 atoms Extract atoms, Use Method,
10 atoms.default Default method for atoms,
11 months.timeDate Extract months atom from a 'timeDate' object.

Usage

\method{[}{timeDate}(x, ..., drop = TRUE)
\method{+}{timeDate}(e1, e2)
\method{-}{timeDate}(e1, e2)
## S3 method for class 'timeDate':
Ops(e1, e2)
## S3 method for class 'timeDate':
diff(x, lag = 1, differences = 1, ...)
difftimeDate(time1, time2, 
        units = c("auto", "secs", "mins", "hours", "days", "weeks"))

## S3 method for class 'timeDate':
c(..., recursive = FALSE)
## S3 method for class 'timeDate':
rep(x, times, ...)
## S3 method for class 'timeDate':
start(x, ...)
## S3 method for class 'timeDate':
end(x, ...)
## S3 method for class 'timeDate':
modify(x, method = c("sort", "round", "trunc", 
        units = c("secs", "mins", "hours", "days"))
## S3 method for class 'timeDate':
rev(x)

## S3 method for class 'timeDate':
as.character(x, ...)
## S3 method for class 'timeDate':
as.data.frame(x, ...)
## S3 method for class 'timeDate':
as.POSIXct(x, tz = "")
## S3 method for class 'timeDate':
julian(x, ...)
## S3 method for class 'timeDate':
atoms(x, ...)
## S3 method for class 'timeDate':
months(x, abbreviate = NULL)

Arguments

abbreviate [months] -
currently not used.
differences [lag] -
an integer indicating the order of the difference.
e1, e2 ["+"][["-"]["Ops"] -
usually objects of class timeDate, in the case of addition and subtraction e2 may be of class numeric.
lag [lag] -
an integer indicating which lag to use.
recursive [c] -
a logical. If recursive is set to TRUE, the function recursively descends through lists combining all their elements into a vector.
time1, time2 [difftime] -
two objects objects of class timeDate.
times [rep] -
an optional non-negative integer. A vector giving the number of times to repeat each element if of length length(x), or to repeat the whole vector if of length 1.
tz inputs the time zone to POSIX objects, i.e. the time zone, zone, or financial center string, FinCenter, as used by timeDate objects.
units a character string denoting the date/time units in which the results are desired.
x an object of class timeDate.
... arguments passed to other methods.

Value

"["
returns a subset from a timeDate object.

"+"
"-"
the plus operator "+" performs arithmetic "+" operation on timeDate objects, and the minus operator "-" returns a difftime object if both arguments e1 and e2 are timeDate objects, or returns a timeDate object e2 seconds earlier than e1.

Ops.timeDate
returns the Ops grouped object.

diff
difftimeDate
For the first function, diff.timeDate, if x is a vector of length n and differences=1, then the computed result is equal to the successive differences x[(1+lag):n] - x[1:(n-lag)]. If difference is larger than one this algorithm is applied recursively to x. Note that the returned value is a vector which is shorter than x. The second function, difftimeDate, takes a difference of two timeDate objects and returns an object of class difftime with an attribute indicating the units.

c
rep
c returns all its arguments to be coerced to a timeDate object which is the type of the returned value, and rep returns a vector of repeated elements belonging to the same class as x.

start
end
return from x the earliest or latest entry as an object of class timeDate, respectively.

modify
rev
modify returns x as a sorted, rounded or truncated object of the same class, depending on the method selection, and rev returns x as a timeDate object in reversed order.

as.character
as.data.frame
return a timeDate object trnasformed into a character or a data frame formatted object.

as.POSIXct
return a timeDate object trnasformed into a POSIX type formatted object.

julian
return a timeDate object as a Julian count.

atoms
months.timeDate
extrac from a timeDate object the calendar atoms, i.e, the year, month, day, and optionally hour, minute and second.

Author(s)

Diethelm Wuertz for this R-port.

Examples

## c -
   xmpBasics("\nStart: Create Character Vectors > ") 
   dts = c("1989-09-28", "2001-01-15", "2004-08-30", "1990-02-09")
   tms = c(  "23:12:55",   "10:34:02",   "08:30:00",   "11:18:23")
   dts; tms
   
## "+/-" - 
   xmpBasics("\nStart: Add One Day to a Given timeDate Object > ")
   GMT = timeDate(dts, FinCenter = "GMT")
   ZUR = timeDate(dts, FinCenter = "Europe/Zurich")
   GMT + 24*3600
   ZUR[2] - ZUR[1]
  
## "[" - 
   xmpBasics("\nNext: Subsets from and Lops for timeDate Objects > ")
   GMT[GMT < GMT[2]]
   ZUR[ZUR < ZUR[3]] == ZUR[1:3]

## diff - 
   xmpBasics("\nNext: Suitably Lagged and Iterated Differences > ")
   diff(GMT)
   diff(GMT, lag = 2)
   diff(GMT, lag = 1, diff = 2)
   difftimeDate(GMT[1:2], GMT[-(1:2)])
   
## c | rep - 
   xmpBasics("\nNext: Concatenate and Replicate timeDate Objects > ") 
   c(GMT[1:2], ZUR[1:2])
   c(ZUR[1:2], GMT[1:2])
   rep(ZUR[2], times = 3)
   rep(ZUR[2:3], times = 2) 

## round | truncate -
   xmpBasics("\nNext: Round and Truncate timeDate Objects > ")
   modify(GMT, "round", "days")
   modify(ZUR, "round", "days")
   modify(GMT, "trunc", "days")
   modify(ZUR, "trunc", "days")

## start | end | sort - 
   xmpBasics("\nNext: Extract First/Last, Sort timeDate Objects > ")
   c(start(ZUR), end(ZUR))
   modify(ZUR, "sort") 

## as -
   xmpBasics("\nNext: Convert timeDate Objects to Other Objects > ")
   as.character(ZUR)
   as.data.frame(ZUR)
   as.POSIXct(ZUR)
   
## julian - 
   xmpBasics("\nNext: Julian Time in Days Since 1970-01-01 > ")
   julian(ZUR)  
   as.integer(julian(ZUR))
   julian(ZUR, "days")  
   as.integer(julian(ZUR, "days"))
    
## atoms - 
   xmpBasics("\nNext: Atoms from a timeDate Object > ")
   atoms(ZUR)
   atoms(ZUR)[,3]
   atoms(ZUR)[, "d"]

[Package Contents]