In andreas50/uts: Unevenly-spaced Time Series

Introduction

This document describes internal details of the uts and utsMultivariate package. It is intended for developers who want to the extend the package functionality.

Internal representation

A uts object is a list of length two with class attribute c("uts", "uts_virtual"). The two list entries are named values and times, respectively, and are vectors of equal length. The former is an R vector of arbitrary mode, containing the observation values. The latter is a POSIXct vector of strictly increasing observation times.

A uts_vector object is a list of uts objects. It has the class attribute c("uts_vector", "uts_virtual") and an optional names attribute.

A uts_matrix is also a list of uts objects. It has the class attribute c("uts_matrix", "uts_vector", "uts_virtual"), a dim attribute, and an optional dimnames attribute. Because the class "uts_matrix" inherits from the class "uts_vector", methods for the latter (e.g. first(), last(), start(), end(), etc.) are automatically available for the former. In same cases though, a specialized method is available, especially

All three classes inherit from the abstract class uts_virtual. Because the Ops group methods are implemented via Ops.uts_virtual, operations such as subtraction can mix the classes.

Internal functions

The packages contains a variety of functions that are not needed by ordinary users, but might be of interest to developers seeking to implement their own methods. To view the list of functions (including links to their documentation), either type

> ?`uts-internal`
> ?`utsMultivariate-internal`

on the R command prompt, or go the HTML help page of the package and select the topic Internal Functions.

Criteria for package inclusion of your function

Whether your function is a good candidate for inclusion in this package depends on the answers to the following questions:

What fraction of end users are likely to use it?
Is it a method implementation for a generic function in base R?
How easy would a user be able to find it using a search engine (including the one that is part of R's HTML help) compared to writing the code from scratch?
Does it do one thing and do it well?

There is no hard threshold, but generally your function should meet a majority of these conditions.

As an example, consider a uts method that outputs a summary of the observation values of a time series:

summary.uts <- function(object, ...)
{
  summary(object$values)
}

Although the code is trivial to write from scratch, failing condition #3, many end users are likely to use it, either consciously or inadvertently, because summary() is a generic function in base R. Meeting conditions #1, #2, and #4 this method is therefore part of the uts package, even though it has been marked using the keyword internal and therefore does not show up in the package index.

On the other hand, consider a uts method that removes consecutive observations from a time series that are less than a certain (temporal) amount apart and for which the observation values are identical (how would you call such a function?). Only a minority of users will be interested in this functionality, and the functionality is difficult to define using a search engine term. Failing the first three conditions, this method is therefore not part of the uts package, even though I have already written it for an analysis of mine.

Finally, consider a uts method that plots a time series x within a certain time window (for example, plot the daily maximum temperature in New York in year 2010). This function actually does two different things: (i) restrict a time series to a certain time period, and (ii) plot the resulting time series. The desired behavior can easily be achieved by combining the window() and plot() method. Failing conditions #3 and #4, no subperiod plotting method has been included in the package. Moreover, the plot.uts method does not have arguments for picking a plotting time window.

Coding conventions

To ensure that code is writting in a consistent manner, please follow the conventions below.

Use spaces for tabs and a tab width of 2 spaces.
For variable and function names, use lower case words and separate them by an underscore character _. For example: "x", "get_item", "test_value".
Diagnostic messages (produced by error() and warning()) should not end with a period.
Do not manually write multi-line comments. Such comments are difficult to edit and reformat. Instead, use a text editor that supports automatic word wrapping, for example:
- Eclipse (Word-Wrap plugin)
- RStudio (Options/Code/Editing/Softwrap),
- UltraEdit (Configuration/Editor/Word_Wrap), 8 Notepad++ (View/Word_Wrap).

Rd documentation conventions

To ensure that the package help has a consistent format, please follow the conventions below.

Function parameter descriptions

To refer to an object of a given class "cl", write an object of class \code{"cl"} (which is the convention used in the help of predict.lm, mgcv, chron, etc.) rather than a "cl" object.

However, for objects of class "duration" it is fine to use the language a duration object (which is the convention used in the lubridate package).

As reference, here are is a list of commonly used parameter descriptions:

@return An object of class \code{"uts"}.
@param x a \code{"uts"} object.
@param time_points a strictly increasing sequence of \code{\link{POSIXct}} date-times.
@param max_dt a duration object, specifying ...
@param \dots further arguments passed to or from methods.