A. Basic Usage

Gerold Hepp

2019-10-19

This vignette introduces the DTSg package, shows how to create objects of its main as well as only class and explains their two interfaces: R6 as code and S3 in comments. Familiarity with the data.table package helps better understanding certain parts of the vignette, but is not essential to follow it.


Object Creation

First, let’s load some data. The package is shipped with a data.table containing a daily time series of river flows:

library(data.table)
library(DTSg)

data(flow)
flow
#>             date   flow
#>    1: 2007-01-01  9.540
#>    2: 2007-01-02  9.285
#>    3: 2007-01-03  8.940
#>    4: 2007-01-04  8.745
#>    5: 2007-01-05  8.490
#>   ---                  
#> 2165: 2012-12-27 26.685
#> 2166: 2012-12-28 28.050
#> 2167: 2012-12-29 23.580
#> 2168: 2012-12-30 18.840
#> 2169: 2012-12-31 17.250
summary(flow)
#>       date                          flow        
#>  Min.   :2007-01-01 00:00:00   Min.   :  4.995  
#>  1st Qu.:2008-07-19 00:00:00   1st Qu.:  8.085  
#>  Median :2010-01-12 00:00:00   Median : 11.325  
#>  Mean   :2010-01-08 23:32:46   Mean   : 16.197  
#>  3rd Qu.:2011-07-08 00:00:00   3rd Qu.: 18.375  
#>  Max.   :2012-12-31 00:00:00   Max.   :290.715

Now that we have a data set, we can create our first object by providing it to the new method of the package’s main R6 class generator DTSg. In addition, we specify an ID in order to give the new object a name:

TS <- DTSg$new(values = flow, ID = "River Flow")
#> Registered S3 method overwritten by 'xts':
#>   method     from
#>   as.zoo.xts zoo

Creating an object with the package’s alternative interface abusing an S4 constructor looks like this:

TS <- new(Class = "DTSg", values = flow, ID = "River Flow")

Object Inspection

Printing the object shows us the data provided, the specified ID and other metadata (if provided) as well as that the object represents a regular UTC time series with a periodicity of one day and 2192 timestamps. It also shows us that the first column has been renamed to .dateTime. This columns serves as its time index and cannot be changed at will:

TS$print() # or 'print(TS)' or just 'TS'
#> Values:
#>        .dateTime   flow
#>           <POSc>  <num>
#>    1: 2007-01-01  9.540
#>    2: 2007-01-02  9.285
#>    3: 2007-01-03  8.940
#>    4: 2007-01-04  8.745
#>    5: 2007-01-05  8.490
#>   ---                  
#> 2188: 2012-12-27 26.685
#> 2189: 2012-12-28 28.050
#> 2190: 2012-12-29 23.580
#> 2191: 2012-12-30 18.840
#> 2192: 2012-12-31 17.250
#> 
#> ID:          River Flow
#> Aggregated:  FALSE
#> Regular:     TRUE
#> Periodicity: Time difference of 1 days
#> Time zone:   UTC
#> Timestamps:  2192

With this done, we can move on and further explore our time series with a summary (summary), a report on missing values (nas) and a plot (plot). It suddenly seems to contain several missing values which apparently were not there upon loading the data set (plot requires the dygraphs and RColorBrewer packages to be installed; HTML vignettes unfortunately cannot display interactive elements, hence I included a static image of the JavaScript chart instead):

TS$summary() # or 'summary(TS)'
#>       flow        
#>  Min.   :  4.995  
#>  1st Qu.:  8.085  
#>  Median : 11.325  
#>  Mean   : 16.197  
#>  3rd Qu.: 18.375  
#>  Max.   :290.715  
#>  NA's   :23
TS$nas(cols = "flow") # or 'nas(TS, cols = "flow")'
#>    .col .group      .from        .to .n
#> 1: flow      1 2007-10-12 2007-10-24 13
#> 2: flow      2 2007-10-26 2007-11-03  9
#> 3: flow      3 2007-11-10 2007-11-10  1
if (requireNamespace("dygraphs", quietly = TRUE) &&
    requireNamespace("RColorBrewer", quietly = TRUE)) {
  TS$plot(cols = "flow") # or 'plot(TS, cols = "flow")'
}