SubtimeDataFrame {timetools}

Class "SubtimeDataFrame"

Description

Class to hold subtime data such a day of week, month of year, etc.

Usage

SubtimeDataFrame(when, data = NULL, ...)

as.SubtimeDataFrame(x, unit, of, ...)
  ## S3 method for class 'TimeInstantDataFrame'
as.SubtimeDataFrame(x, unit, of, FUN=NULL, ...)
  ## S3 method for class 'TimeIntervalDataFrame'
as.SubtimeDataFrame(x, unit, of, FUN=NULL, cursor=NULL, ...)

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

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

  ## S4 method for signature 'SubtimeDataFrame'
timezone(object)
  ## S4 method for signature 'SubtimeDataFrame'
when(x, ...)
  ## S3 method for class 'SubtimeDataFrame'
unit(x, ...)
  ## S3 method for class 'SubtimeDataFrame'
of(x, ...)

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

  ## S3 method for class 'SubtimeDataFrame'
print(x, ...)
  ## S3 method for class 'SubtimeDataFrame'
summary(object, ...)
  ## S3 method for class 'SubtimeDataFrame'
head(x, ...)
  ## S3 method for class 'SubtimeDataFrame'
tail(x, ...)
  ## S4 method for signature 'SubtimeDataFrame'
show(object)

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

Arguments

when

POSIXst.

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

x

object to convert to a TimeInstantDataFrame or SubtimeDataFrame object (to modify, to extract or to test)

unit

indicates the subtime part to extract ('year', 'month', 'day', 'hour', 'minute', 'second').

of

used to specify the main period from wich the is to extract ('year', 'month', 'day', 'hour', 'minute'). Not used for ‘unit in c('year', 'month')’.

FUN

function to use for the agregation (if wanted, see ‘details’)

cursor

For 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).

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

SubtimeDataFrame to merge with x

all

logical; see merge

by

specifications of the columns used for merging.

sort

logical; if TRUE the resulting merged SubtimeDataFrame 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 SubtimeDataFrame on which the FUN must be applied.

object

SubtimeDataFrame 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

as.is

should data be represented incrementally (the first row is given an x-value of 1, the second of 2, ... the last of n)(TRUE) or should data be grouped by their subtime (all value corresponding to monday are drawn at an x-value of 1) (FALSE) ?

height

plotting argument, see barplot

format

for barplot see barplot, otherwise a string to format the x-labels according to the format method of POSIXst objects (see 'Text representation' of POSIXst).

...

More arguments.

Objects from the Class

Formally, the class consists of a data.frame and, for each row, a POSIXst (or subtime). This class is provided to deal with subtime data. This class is compatible with TimeIntervalDataFrame and TimeInstantDataFrame.

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

SubtimeDataFrame constructors

Objects can be created by calls of the form

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

• SubtimeDataFrame (when, data=NULL, ...) Arguments of the function correspond to object slots.

• as.SubtimeDataFrame (from, representation, cursor=NULL, FUN=mean, ...) Converting object to SubtimeDataFrame. Conversion from a TimeIntervalDataFrame to a SubtimeDataFrame can be direct or after agregation.

  For a direct conversion (where date are only replaced by the desired subtime), FUN must be NULL.

  For an agregateed conversion, the function to use must be indicated by the FUN arg and all arguments to pass to this function can be given (namely).

Slots

when:

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

data:

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

Accessing to and manipulating data

The SubtimeDataFrame class is defined to works like the data.frame class with the difference that a subtime (POSIXst) 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.

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

• merge to join two (or more) SubtimeDataFrame (see merge),

• a SubtimeDataFrame 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 TimeIntervalDataFrame via the lapply function provided that the function return one value (in this case the resulting value is a TimeIntervalDataFrame beginning at the first instant of the object and ending at the latest one), or as much values as the number of rows of the object (in this case the SubtimeDataFrame given in argument in returned with the new values calculated).

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

Access to time properties

A SubtimeDataFrame can be tested for a few time properties :

timezone

gives or sets the timezone of the SubtimeDataFrame ;

when

returns a POSIXst object with the time instant of the SubtimeDataFrame.

unit

returns the unit of the time instant of the SubtimeDataFrame.

of

returns the 'of' of the time instant of the SubtimeDataFrame.

Graphic representation

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

These functions works more or less like their generic definition.

Text representation

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

See Also

TimeInstantDataFrame, TimeIntervalDataFrame, POSIXst

Examples

showClass("SubtimeDataFrame")