fBasics (version 200.10058)

TimeDateMethods: timeDate Methods

Description

A collection and description 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 for Math Operations with 'timeDate' Objects are: ll{ [.timeDate Extracts, replaces subsets from 'timeDate' objects, +.timeDate Performs arithmetic + ops on 'timeDate' objects, -.timeDate Performs arithmetic - ops on 'timeDate' objects, Ops.timeDate 'Ops' generic functions for 'timeDate' objects, diff.timeDate Returns suitably lagged and iterated differences, difftimeDate Returns a difference of two 'timeDate' objects, c.timeDate Concatenates objects of class 'timeDate', rep.timeDate Replicates objects of class 'timeDate', start.timeDate Extracts the first object of a 'timeDate' vector, end.timeDate Extracts the last object of a 'timeDate' vector, modify.timeDate Sorts, rounds or truncates a 'timeDate' object, rev.timeDate Reverts a 'timeDate' vector object. } The methods for Transformations of 'timeDate' Objects are: ll{ as.character.timeDate Returns a 'timeDate' object as character string, as.data.frame.timeDate Returns a 'timeDate' object as data frame, as.POSIXct.timeDate Returns a 'timeDate' object as POSIXct object, as.POSIXlt As POSIXlt, Use Method (Overwrite), as.POSIXlt.default Default method for POSIXlt, julian.timeDate Returns Julian day counts since 1970-01-01, julian.POSIXt A Julian Patch, atoms.timeDate Returns date/time atoms from a 'timeDate' object, atoms Extract atoms, Use Method, atoms.default Default method for atoms, months.timeDate Extract months atom from a 'timeDate' object. }

Usage

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

## S3 method for class 'timeDate':
c(\dots, recursive = FALSE)
## S3 method for class 'timeDate':
rep(x, times, \dots)
## S3 method for class 'timeDate':
start(x, \dots)
## S3 method for class 'timeDate':
end(x, \dots)
## 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, \dots)
## S3 method for class 'timeDate':
as.data.frame(x, \dots)
## S3 method for class 'timeDate':
as.POSIXct(x, tz = "")
## S3 method for class 'timeDate':
julian(x, \dots)
## S3 method for class 'timeDate':
atoms(x, \dots)
## 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.

Details

Mathematical Operations: This is a collection of S3 methods for objects of class timeDate to perform mathematical operations. Included are methods to extracts or replace subsets from timeDate objects, to perform arithmetic "+" and "-" operations, to group 'Ops' generic functions, to return suitably lagged and iterated differences, to return differences of two timeDate objects, to concatenate objects, to replicate objects, to rounds objects, to truncates objects, to extract the first or last entry of a vector, to sort the objects of the elements of a date/time vector, and to revert timeDate vector objects. Transformation of Objects: This is a collection of S3 methods for objects of class timeDate to transform those objects between different representations. Included are methods to transform timeDate objects to character strings, to data frames, to POSIXct or POSIXlt objects, to Julian counts, to extract date/time atoms from calendar dates, and to extract the months atom from a timeDate object.

References

Bateman R., (2000); Time Functionality in the Standard C Library, Novell AppNotes, September 2000 Issue, 73--85. ISO-8601, (1988); Data Elements and Interchange Formats - Information Interchange, Representation of Dates and Time, International Organization for Standardization, Reference Number ISO 8601, 14 pages. James D.A., Pregibon D. (1992), Chronological Objects for Data Analysis, Reprint. Ripley B.D., Hornik K. (2001); Date-Time Classes, R-News, Vol. 1/2 June 2001, 8--12. Zivot, E., Wang J. (2003); Modeling Financial Time Series with S-Plus, Springer, New-York.

Examples

## c -
   xmpBasics("Start: 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("Start: 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("Next: Subsets from and Lops for timeDate Objects > ")
   GMT[GMT < GMT[2]]
   ZUR[ZUR < ZUR[3]] == ZUR[1:3]

## diff - 
   xmpBasics("Next: 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("Next: 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("Next: 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("Next: Extract First/Last, Sort timeDate Objects > ")
   c(start(ZUR), end(ZUR))
   modify(ZUR, "sort") 

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