TimeInstantDataFrame {timetools}

Class "TimeInstantDataFrame"

Description

Class to hold time data that ARE 'instantaneous'.

Usage

  TimeInstantDataFrame(when, timezone = "UTC", data = NULL, sort=FALSE, ...)

  as.TimeInstantDataFrame(from, ...)
  ## S3 method for class 'TimeIntervalDataFrame'
as.TimeInstantDataFrame(from, cursor = NULL, ...)

  RegularTimeInstantDataFrame(from, to, by, timezone = "UTC", data = NULL)

  ## S4 method for signature 'TimeInstantDataFrame'
x$name
  ## S4 replacement method for signature 'TimeInstantDataFrame'
x$name <- value
  ## S3 method for class 'TimeInstantDataFrame'
x[i, j, drop=FALSE]
  ## S3 replacement method for class 'TimeInstantDataFrame'
x[i, j] <- value
  ## S4 method for signature 'TimeInstantDataFrame'
x [[i, j, ...]]
  ## S3 replacement method for class 'TimeInstantDataFrame'
x[[i, j]] <- value

  ## S3 method for class 'TimeInstantDataFrame'
rbind(...)
  ## S3 method for class 'TimeInstantDataFrame'
merge(x, y, by, all=TRUE, tz='UTC', sort=TRUE, ...)
  ## S3 method for class 'TimeInstantDataFrame'
split(x, f, drop=FALSE, ...)
  ## S4 method for signature 'TimeInstantDataFrame'
lapply(X, FUN, ...)

  ## S4 method for signature 'TimeInstantDataFrame'
regular(x, ...)
  ## S4 method for signature 'TimeInstantDataFrame'
timezone(object)
  ## S4 replacement method for signature 'TimeInstantDataFrame'
timezone(object) <- value
  ## S4 method for signature 'TimeInstantDataFrame'
when(x, ...)

  ## S4 method for signature 'TimeInstantDataFrame'
dim(x)
  ## S4 method for signature 'TimeInstantDataFrame'
length(x)
  ## S4 method for signature 'TimeInstantDataFrame'
names(x)
  ## S4 replacement method for signature 'TimeInstantDataFrame'
names(x) <- value
  ## S4 method for signature 'TimeInstantDataFrame'
ncol(x)
  ## S4 method for signature 'TimeInstantDataFrame'
nrow(x)
  ## S3 method for class 'TimeInstantDataFrame'
row.names(x)
  ## S3 replacement method for class 'TimeInstantDataFrame'
row.names(x) <- value

  ## S3 method for class 'TimeInstantDataFrame'
print(x, tz=NULL, ...)
  ## S3 method for class 'TimeInstantDataFrame'
summary(object, ...)
  ## S3 method for class 'TimeInstantDataFrame'
head(x, tz, ...)
  ## S3 method for class 'TimeInstantDataFrame'
tail(x, tz, ...)
  ## S4 method for signature 'TimeInstantDataFrame'
show(object)

  ## S3 method for class 'TimeInstantDataFrame'
plot(x, y=NULL, type="p",
	lty=1:6, lwd=1, pch=1:25, col=NULL,
	xlim=NULL, ylim=NULL, log, main, sub, xlab, ylab,
	ann=par("ann"), axes=TRUE, asp=NA, ...)
  ## S3 method for class 'TimeInstantDataFrame'
points(x, y=NULL, type="p",
	lty=1:6, lwd=1, pch=1:25, col=NULL, ...)
  ## S3 method for class 'TimeInstantDataFrame'
lines(x, y=NULL, type="l",
	lty=1:6, lwd=1, pch=1:25, col=NULL, ...)
  ## S3 method for class 'TimeInstantDataFrame'
barplot(height, format='', ...)

Arguments

when

POSIXct or character representing a time with a valid format (see POSIXct). It gives the instant of each row.

timezone

character representing a valid timezone (see timezone).

data

a data.frame with as much rows as needed for the created object. Can be NULL (hence the data.frame has zero column and as much rows as needed).

from

as.TimeInstantDataFrame

object to convert to a TimeInstantDataFrame

RegularTimeInstantDataFrame

POSIXct or character representing a time with a valid format (see POSIXct). It represents the start of the object.

cursor

To convert TimeIntervalDataFrame, it indicates where the TimeInstant must be taken. If 0, start of each intervals is taken as instant ; if 1 end of each intervals is taken as instant. Any other value will determine a weigthed instant between start and end (actually, value higher than 1 or lower than 0 will give instant outside this range).

to

POSIXct or character representing a time with a valid format (see POSIXct). It represents the end of the object. If missing, its value is deduced from ‘from’, ‘by’ and ‘data’.

by

RegularTimeInstantDataFrame

a POSIXctp object indicating the increment to use between instants of the object.

merge

specifications of the columns used for merging.

x

TimeInstantDataFrame object (to modify, to extract or to test)

i

indices specifying elements to extract or replace. (See Extract)

j

indices specifying elements to extract or replace. (See Extract)

name

A litteral character string or a name. (See Extract)

drop

Used for compatibility with data.frame methods.

value

New value for the object designated (data.frame, names, row.names, etc.).

y

TimeInstantDataFrame to merge with x

all

logical; see merge

tz

character representing a valid timezone (see timezone).

sort

logical; if TRUE the resulting built/merged TimeInstantDataFrame is ordered according to 'when' values.

f

a 'factor' in the sense that ‘as.factor(f)’ defines the grouping, or a list of such factors in which case their interaction is used for the grouping. See split.

X

a TimeInstantDataFrame on which the FUN must be applied.

FUN

function to apply over eahc columns of X.

object

TimeInstantDataFrame object (to modify, to extract or to test)

type

plotting argument, see plot.default

lty

plotting argument, see plot.default

lwd

plotting argument, see plot.default

pch

plotting argument, see plot.default

col

plotting argument, see plot.default

xlim

plotting argument, see plot.default

ylim

plotting argument, see plot.default

log

plotting argument, see plot.default

main

plotting argument, see plot.default

sub

plotting argument, see plot.default

xlab

plotting argument, see plot.default

ylab

plotting argument, see plot.default

ann

plotting argument, see plot.default

axes

plotting argument, see plot.default

asp

plotting argument, see plot.default

height

plotting argument, see barplot

format

plotting argument, see barplot

...

More arguments.

Objects from the Class

Formally, the class consists of a data.frame and, for each row, a POSIXct. This class is provided to deal with punctual time data. Many of such classes are defined in other packages. This one is defined mainly to provide a ‘punctual’ class compatible with TimeIntervalDataFrame and SubtimeDataFrame.

The construction of the class allows to manipulate objects as if they were data.frame (see ‘Access to data’ and ‘Access to data properties’).

Slots

instant:

Object of class "POSIXct" corresponding to the instant of each row of the data.frame.

timezone:

Object of class "character" indicating the timezone of data both for representation and calculation.

data:

Object of class "data.frame" data contained by the object.

TimeInstantDataFrame constructors

Objects can be created by calls of the form

• new("TimeInstantDataFrame", ...) ... argument must be replaced by named arguments coresponding to slots of a TimeInstantDataFrame (see below). See also new.

• TimeInstantDataFrame (when, timezone='UTC', data=NULL, ...) Arguments of the function correspond to object slots.

• RegularTimeInstantDataFrame (from, to, by, timezone='UTC', data=NULL), Wrapper to construct TimeInstantDataFrame with specific properties. Instants of the TimeInstantDataFrame go from 'from' to 'to' regularly spaced by 'by', which is a POSIXctp or an object which can be coerced to.

• as.TimeInstantDataFrame (from, ...) Converting object to TimeInstantDataFrame.

Math

Every functions defined in the Ops group (see Ops) can be used width a TimeInstantDataFrame and numeric :

• tidf * 2

• 2 * tidf

• 2:10 == tidf

• 2^tidf

• tidf^2

Accessing to and manipulating data

The TimeInstantDataFrame class is defined to works like the data.frame class with the difference that a time instant (POSIXct) is attached to each rows of the data.frame. Thus to access and manipulate data of a TimeInstantDataFrame the following methods are defined : '$', '$<-', '[', '[<-', '[[', '[[<-'. See Extract for details.

With ‘[’ operator, a selection by dates is also available. If ‘i’ and or ‘j’ are POSIXt or strings that can be converted to POSIXct (see below), they are considered as the minimal and maximal time limits : all datas between those are selected. A string that can be converted to a POSIXct is (in this case only) a string composed of 3 parts separated by white space : 'YYYY-MM-DD HH:MM:SS tz'. The second and third parts are options, thus accepted format are :

• 'YYYY-MM-DD'

• 'YYYY-MM-DD tz'

• 'YYYY-MM-DD HH:MM:SS'

• 'YYYY-MM-DD HH:MM:SS tz'

. If timezone is not given, it is assumed to be the same as the one of the object on which the selection is done.

Other methods have been defined to allow some operations over TimeInstantDataFrame :

• rbind and merge to join two (or more) TimeInstantDataFrame (see rbind and merge),

• a TimeInstantDataFrame can be splitted exactly the same way that a data.frame can (see split in the base package),

• a function can be applied over each column of a TimeInstantDataFrame via the lapply function. If the function returns one value, the resulting value is a TimeIntervalDataFrame beginning at the first instant of the object and ending at the latest one ; else if the function returns as much values as the number of rows of the object, the TimeInstantDataFrame given in argument is returned with the new calculated values ; on others cases, a non-TimeInstantDataFrame object is returned.

Because a TimeInstantDataFrame works more or less like a data.frame, the following methods work on a TimeInstantDataFrame : dim, length, names, names<-, ncol, nrow, row.names, row.names<-.

Access to time properties

A TimeInstantDataFrame can be tested for a few time properties :

regular

TRUE if all time instants are equally spaced ;

timezone

gives or sets the timezone of the TimeInstantDataFrame ;

when

returns a POSIXct object with the time instant of the TimeInstantDataFrame.

Graphic representation

To plot a TimeInstantDataFrame available functions are plot, lines, points and barplot.

These functions works more or less like their generic definition.

Text representation

To represent a TimeInstantDataFrame available functions are print, summary, head, tail and show.

See Also

TimeIntervalDataFrame, SubtimeDataFrame

Examples

showClass("TimeInstantDataFrame")