A. Basic Usage

Gerold Hepp

2019-03-09

This vignette introduces the DTSg package, shows how to create objects of its main class and explains their two interfaces: R6 and S3. 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 flow:

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

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, some more slots for metadata, which we left empty, as well as that the object represents a regular UTC time series with a periodicity of one day. 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
#> Parameter:   
#> Variant:     
#> Unit:        
#> Aggregated:  FALSE
#> Regular:     TRUE
#> Periodicity: Time difference of 1 days
#> Time zone:   UTC

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 xts, 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("xts", quietly = TRUE) &&
    requireNamespace("dygraphs", quietly = TRUE) &&
    requireNamespace("RColorBrewer", quietly = TRUE)) {
  TS$plot(cols = "flow") # or plot(TS, cols = "flow")
}