TimeIntervalDataFrame {timetools}

Class "TimeIntervalDataFrame"

Description

Class to hold time data that are NOT 'punctual'.

Usage

  TimeIntervalDataFrame(start, end = NULL,
    timezone = "UTC", data = NULL, period = NULL, sort=FALSE, ...)

  as.TimeIntervalDataFrame(from, ...)
  ## S3 method for class 'TimeInstantDataFrame'
as.TimeIntervalDataFrame(from, period, ...)

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

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

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

  ## S4 method for signature 'TimeIntervalDataFrame'
tapply(X, INDEX, FUN, ...,
       min.coverage=1, weights.arg=NULL, merge.X=TRUE, split.X=FALSE,
       keep.INDEX=TRUE, simplify=TRUE)
  ## S4 method for signature 'TimeIntervalDataFrame'
changeSupport(from, to,
       min.coverage, FUN=NULL, weights.arg=NULL,
       split.from=FALSE, merge.from=TRUE, ...)

  ## S4 method for signature 'TimeIntervalDataFrame'
continuous(x, ...)
  ## S4 replacement method for signature 'TimeIntervalDataFrame'
continuous(x) <- value
  ## S4 method for signature 'TimeIntervalDataFrame'
homogeneous(x, ...)
  ## S4 method for signature 'TimeIntervalDataFrame'
period(x, ...)
  ## S4 method for signature 'TimeIntervalDataFrame'
overlapping(x, ...)
  ## S4 method for signature 'TimeIntervalDataFrame'
regular(x, ...)
  ## S4 method for signature 'TimeIntervalDataFrame'
timezone(object)
  ## S4 replacement method for signature 'TimeIntervalDataFrame'
timezone(object) <- value
  ## S3 method for class 'TimeIntervalDataFrame'
start(x, ...)
  ## S3 method for class 'TimeIntervalDataFrame'
end(x, ...)
  ## S4 method for signature 'TimeIntervalDataFrame'
when(x, ...)
  ## S4 method for signature 'TimeIntervalDataFrame'
interval(x, ...)

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

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

  ## S3 method for class 'TimeIntervalDataFrame'
plot(x, y=NULL, cursor=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 'TimeIntervalDataFrame'
points(x, y=NULL, cursor=NULL, type='p',
    lty=1:6, lwd=1, pch=1:25, col=NULL, ...)
  ## S3 method for class 'TimeIntervalDataFrame'
lines(x, y=NULL, cursor=NULL, type='l',
    lty=1:6, lwd=1, pch=1:25, col=NULL, ...)
  ## S3 method for class 'TimeIntervalDataFrame'
barplot(height, format='', ...)

Arguments

start

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

end

POSIXct or character representing a time with a valid format (see POSIXct). It gives the end of each interval. If NULL, see ‘Details’.

timezone

character representing a valid timezone (see timezone).

data

a data.frame with as much rows as the length of ‘start’ and end, or with one row less than the length of ‘start’ if ‘end’ is NULL. Can be NULL (hence the data.frame has zero column and as much rows as needed).

period

TimeIntervalDataFrame

if not NULL, a POSIXctp or a character that can be converted to a POSIXctp (see argument ‘unit’ of POSIXctp function). See Details to know how to use this argument.

as.TimeIntervalDataFrame

POSIXctp object indicating the period to add to ‘when’ slot of from to determine the end of the new period (the ‘when’ is used for the start of period)

RegularTimeIntervalDataFrame

a POSIXctp object indicating the period of each interval. If missing, it is given the value of by.

from

as.TimeIntervalDataFrame

object to convert to a TimeIntervalDataFrame

RegularTimeIntervalDataFrame

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

changeSupport

see changeSupport

to

RegularTimeIntervalDataFrame

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’.

changeSupport

see changeSupport

by

RegularTimeIntervalDataFrame

a POSIXctp object indicating the increment to use between the start of each interval.

merge

specifications of the columns used for merging.

x

TimeIntervalDataFrame 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

TimeIntervalDataFrame to merge with x

all

logical; see merge

tz

character representing a valid timezone (see timezone).

sort

logical; if TRUE the resulting built/merged TimeIntervalDataFrame 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

lapply

a TimeIntervalDataFrame on which the FUN must be applied.

tapply

see tapply for details

FUN

lapply

function to apply over each columns of X.

tapply,changeSupport

see tapply for details

INDEX, min.coverage, weights.arg, merge.X, split.X, keep.INDEX, simplify, split.from, merge.from

see tapply and/or changeSupport for details.

object

TimeIntervalDataFrame 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

cursor

To convert TimeIntervalDataFrame to a TimeInstantDataFrame before plotting (see TimeInstantDataFrame, 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).

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, two POSIXct that can be summarize as time interval with the POSIXcti class. This allows to manipulate at once time data without any restriction on time representation : data can occur at different time, data can be discontinuous, data can be heterogeneous (not lasting for a unique period), data can overlay each other, etc. There are several methods to test/deal/ensure that these properties are respected or not, see below.

The construction of the class allows to manipulate objects as if they were data.frame (see ‘Access to data’ and ‘Access to data properties’). Several functions are also available to access to time properties (see ‘Access to time properties’).

Methods are also available to facilitate the representations of instances of that class : see ‘graphic representation’ and ‘text representation’.

Finally, some specific methods allow to easily deal with agregation of data over time properties (day, hour, week, special or specific time intervals).

Slots

start:

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

end:

Object of class "POSIXct" corresponding to the end 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.

TimeIntervalDataFrame constructors

Objects can be created by calls of the form

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

• TimeIntervalDataFrame (start, end=NULL, timezone='UTC', data=NULL, ...) Arguments of the function correspond to object slots. If both start and end are given, they must have the same length. They are used to define the intervals of the object. If data is also given, it must have a number of rows identical to the length of start and end.

  If only start is given, a continuous (see continuous) TimeIntervalDataFrame is built. The first element of start is the start of the first interval, the second element is the end of the first interval and the start of the second interval. The last element of start is only the end of the last interval. This is why data, if given, must be one row shorter than start.

  If period is given it must be a POSIXctp object (or a valid character) and ‘start’ and ‘end’ must have length equal to 1. In that case, a TimeIntervalDataFrame will be created with start date equal to start ‘floored’ by the unit of ‘period’, end date ‘ceiled’ by the unit of ‘period’ and with enough intervals of ‘period’ length to fit. If ‘data’ given, it must have a number of rows equal to the number of intervals calculated.

• RegularTimeIntervalDataFrame (from, to, by, period, timezone='UTC', data=NULL) Wrapper to construct TimeIntervalDataFrame with specific properties (see details of each argument).

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

Math

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

• tidf * 2

• 2 * tidf

• 2:10 == tidf

• 2^tidf

• tidf^2

Accessing to and manipulating data

The TimeIntervalDataFrame class is defined to works like the data.frame class with the difference that a time interval (POSIXcti) is attached to each rows of the data.frame. Thus to access and manipulate data of a TimeIntervalDataFrame 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 on TimeIntervalDataFrame :

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

• a TimeIntervalDataFrame can be splitted exactly the same way that a data.frame can (see split in the base package) and some more possibilities have been defined (see split in the timetools package),

• a function can be applied over each column of a TimeIntervalDataFrame 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 TimeIntervalDataFrame given in argument is returned with the new calculated values ; on others cases, a non-TimeInterevalDataFrame object is returned.

• 'tapply' can split a TimeIntervalDataFrame and then apply a function over each group (see tapply),

• 'changeSupport' act like the 'tapply' function but with a different default behaviour (see changeSupport).

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

Access/modify to time properties

A TimeIntervamDataFrame can be tested for a few time properties :

continuous

see continuous ;

homogeneous

see homogeneous ;

period

see period ;

overlapping

see overlapping ;

regular

TRUE if all time intervals are equally spaced ;

timezone

gives or sets the timezone of the TimeIntervalDataFrame ;

start

returns a POSIXct object with the start time of each intervals ;

end

returns a POSIXct object with the end time of each intervals ;

when

returns a POSIXcti, i.e. the intervals of the object ;

interval

returns a POSIXcti, i.e. the intervals of the object.

Graphic representation

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

These functions works more or less like their generic definition.

Text representation

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

See Also

TimeInstantDataFrame, SubtimeDataFrame, POSIXcti, POSIXctp

Examples

showClass("TimeIntervalDataFrame")