POSIXst-class: Class '"POSIXst"'

In timetools: Seasonal/Sequential (Instants/Durations, Even or not) Time Series

Class "POSIXst"

Description

Class to define POSIXst object such as hours of day, seconds of year, etc.

Usage

POSIXst(x, unit, of = NULL, tz = "UTC", ...)
  ## Default S3 method:
 POSIXst(x, unit, of = NULL, tz = "UTC", ...)
  ## S3 method for class 'integer'
 POSIXst(x, unit, of = NULL, tz = "UTC", ...)
  ## S3 method for class 'numeric'
 POSIXst(x, unit, of = NULL, tz = "UTC", ...)
  ## S3 method for class 'POSIXct'
 POSIXst(x, unit, of = NULL, tz = attributes(x)$tzone, ...)
  ## S3 method for class 'POSIXlt'
 POSIXst(x, unit, of = NULL, tz = attributes(x)$tzone, ...)
  ## S3 method for class 'TimeInstantDataFrame'
 POSIXst(x, unit, of = NULL, tz = timezone(x), ...)
  ## S3 method for class 'TimeIntervalDataFrame'
 POSIXst(x, unit, of = NULL, tz = timezone(x), ..., cursor = NULL)

year(x, ...)
month(x, ...)
day(x, of, ...)
hour(x, of, ...)
minute(x, of, ...)
second(x, of, ...)

  ## S3 method for class 'POSIXst'
x[i]
  ## S3 replacement method for class 'POSIXst'
x[i] <- value
  ## S3 method for class 'POSIXst'
c(...)
  ## S3 method for class 'POSIXst'
split(x, f, drop=FALSE, ...)
  ## S3 method for class 'POSIXst'
rep(x, ...)
  ## S3 method for class 'POSIXst'
seq(from, to, ...)
  ## S3 method for class 'POSIXst'
unique(x, incomparables=FALSE, ...)
  ## S3 method for class 'POSIXst'
duplicated(x, incomparables=FALSE, ...)

  ## S3 method for class 'POSIXst'
unit(x, ...)
  ## S3 method for class 'POSIXst'
of(x, ...)
  ## S3 method for class 'POSIXst'
timezone(object)

  ## S4 method for signature 'POSIXst'
length(x)

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

  ## S4 method for signature 'POSIXst,POSIXst'
match(x, table, nomatch = NA_integer_, incomparables=NULL)
  ## S4 method for signature 'POSIXst,ANY'
match(x, table, nomatch = NA_integer_, incomparables=NULL)
  ## S4 method for signature 'POSIXst,ANY'
x %in% table

  ## S3 method for class 'POSIXst'
Ops(e1, e2)

  ## S4 method for signature 'POSIXst,POSIXctp'
e1 + e2
  ## S4 method for signature 'POSIXctp,POSIXst'
e1 + e2
  ## S4 method for signature 'POSIXst,POSIXctp'
e1 - e2

  ## S4 method for signature 'POSIXst,POSIXst'
e1 - e2

  ## S4 method for signature 'POSIXst'
as.numeric(x, ...)

Arguments

x	object to convert into POSIXst or POSIXst object on which the method has to be applied.
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')’.
tz	if needed, specifies th timezone of POSIXst
cursor	for TimeIntervalDataFrame, if not NULL, the object is first coerced to a TimeInstantDataFrame using the as.TimeInstantDataFrame method.
i	index (logical or numeric) of the POSIXst objects.
value	New POSIXst object.
f	factor used to group the POSIXst elements.
drop	Argument specific to the split method. See link[base]{split} documentation.
object	POSIXst object on which the method has to be applied.
format	Character string to precise the desired format. See section ‘Text representation’ below for details.
table	The values (POSIXst) to be matched against. See match for further details.
nomatch	The value to be returned i nthe case when no match is found. See match for further details.
incomparables	A vector of values that cannot be matched. See match for further details.
e1	POSIXst or POSIXctp. See details.
e2	POSIXst or POSIXctp. See details.
from, to	starting and end values to sequence, see seq
...	More arguments.

Objects from the Class

Objects of this class are used to represent subtimes. A subtime (or a ‘POSIXst’, ‘st’ stand for Sub and Time) is a subdivision of time :

• second of a minute ;

• second of an hour ;

• second of a day ;

• second of a week ;

• second of a month ;

• second of a year ;

• minute of an hour ;

• minute of a day ;

• ...

• minute of a year ;

• ...

• month of year ;

• year AD (after death).

A POSIXst is a kind of time object composed of 2 units and a positionnal integer. The main unit can be accessed via the ‘of’ function ; the sub unit can be accessed via the ‘unit’ function. The positionnal integer correspond to the value of the subtime object. Consequently, a subtime st is the valueth unit(st) of of(st).

The range of valid values for each kind of POSIXst is defined accordingly to the DateTimeClasses definitions. For instance valid values for seconds of hour are 0 to 61, valid values for day of week are 0 to 6, etc.

To define POSIXst objects see POSIXst section below.

One object is actually a vector of subtimes and so can have a length of one for a single subtime or a length of ‘n’ for ‘n’ subtimes.

Last, a POSIXst object has a ‘timezone’ slots. This is defined for compatibility reason with POSIXct object and also with TimeInstantDataFrame, TimeIntervalDataFrame and SubtimeDataFrame.

Slots

subtime:

Object of class "integer" corresponding to the actual value of each subtime.

unit:

factor representing a time unit. It represents the subdvision of time (in 'second of year' it corresponds to 'second'). See POSIXt.units.

of:

factor representing a time unit. It represents the main time unit (in 'second of year' it corresponds to 'year'). See POSIXt.units.

timezone:

Object of class "character" indicating the timezone of the POSIXst object.

POSIXst

POSIXst objects can be created from various other class objects. For this purpose the POSIXst method has been defined.

First, if ‘x’ is missing, an empty factor with the appropriated levels (according to ‘unit and of’) is returned.

A POSIXst can be created from an integer or a numeric. If so, ‘unit’ and ‘of’ msute be supplied (see arguments section above). The ‘tz’ argument can be supplied (numeric will be converted to an integer). In both cases, values of the integer/numeric must be in the right range (see DateTimeClasses.

A POSIXst can be created from a POSIXct or POSIXlt object. In this case, the subtime (POSIxst) is extracted in the units indicated by ‘unit’ and ‘of’ arguments. The ‘tz’ argument indicates the timezone of the resulting object (it doesn't do any conversion on the POSIXl,ct objects).

Finally, POSIXst can be extracted from TimeInstantDataFrame and TimeIntervalDataFrame. For the first type of object, the method is applied to the time instants (which are POSIXct). For the latter, because a time interval can contains several POSIXst of one kind (for instance a day contains all 'hours of day'), the result of this method TimeIntervalDataFrame is a list of POSIXst. Each element of the list contains the POSIXsts asked for corresponding to each row of the TimeIntervalDataFrame object. If ‘cursor’ is supplied, the TimeIntervalDataFrame is first converted to a TimeInstantDataFrame (see as.TimeInstantDataFrame for details).

year(...), month(...), day(...), hour(...), minute(...) and second(...)

year, month, day, hour, minute and second are methods defined to extract the adequat information from a time object. These functions are wrappers to POSIXst.

Each of these methods call POSIXst replacing the unit argument with its own name : minute(x, of='day') will call POSIXst(x, unit='minute', of='day')

Accessing to POSIXst properties

A POSIXst has several properties. Because a POSIXst is a vector of subtimes, the class has a length function. Other properties are time properties : unit, of and timezone allow to access to the corresponding properties. The ‘unit’ and ‘of’ of a subtime is an ordered factor as the one defined by POSIXt.units.

For more informations on timezone, see the page of the manual.

Manipulating POSIXst

Manipulating POSIXst means acting on POSIXsts like on classical vectors. Methods available for this task allow to extract or replace parts of a POSIXst (with the usual '[' operator), and to concatenate (c) or split POSIXst (split). A unique, a duplicated, a rep and a seq methods are defined to uniquify, repeat or sequence elements of a POSIXst.

match and %in% methods have also been defined to find POSIXst objects among others.

Text representation

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

The five first functions work the same way that their generic definition.

'POSIXst' are formatted according to the format argument which must respect the following rules.

• %v value

• %s subtime unit (slot ‘unit’)

• %m main unit (slot ‘of’)

• %a Abbreviated weekday name in the current locale.

• %A Full weekday name in the current locale.

• %b Abbreviated month name in the current locale.

• %B Full month name in the current locale.

• %r timezone

• %p place of subtime (ie the string part of 1st, 2nd, 10th, etc.)

Testing two POSIXst

To test two POSIXst the differents operators of comparison are used. If the POSIXst compared have a different length, the shorter is recycled over the longer so the resulting vector (a logical vector) has length equal to the longer object.

Comparisons are made element by element. Two POSIXst with a different ‘unit’ or a different ‘of’ are differents (TRUE if test is ‘!=’, FALSE if ‘==’ NA otherwise). If they have identical ‘unit’ and ‘of’ the comparison is made over subtime slots.

Mathematical operations on POSIXst

POSIXst can be added and substracted to POSIXctp. POSIXst can also be substracted (and only substracted) to POSIXst.

For all operations, if the two arguments have a different length, the shorter is recycled over the longer so the resulting vector (a logical vector) has length equal to the longer object.

Mathematical operations with POSIXctp are actually time lagging. Units of the POSIXctp must be identical to the POSIXst's : the object is then lagged by the time periods (if the result is higher than the maximum the result is recycled at the begining. For instance : saturday + 2 days = monday).

• POSIXst + POSIXctp

• POSIXctp + POISXst

• POSIXst - POSIXctp

Substracting a POSIXst to another result in a POSIXctp. For instance wednesday - monday = 2 days.

Changing class

POSIXst can be converted to numeric with the as.numeric method. The subtime slot of the object is returned.

See Also

POSIXct, POSIXcti, POSIXctp, TimeIntervalDataFrame,

Examples

showClass("POSIXst")

timetools documentation built on Aug. 29, 2023, 5:09 p.m.