A. Basic usage

Gerold Hepp

2022-06-08

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.0   Min.   :  4.995  
#>  1st Qu.:2008-07-19 00:00:00.0   1st Qu.:  8.085  
#>  Median :2010-01-12 00:00:00.0   Median : 11.325  
#>  Mean   :2010-01-08 23:32:46.7   Mean   : 16.197  
#>  3rd Qu.:2011-07-08 00:00:00.0   3rd Qu.: 18.375  
#>  Max.   :2012-12-31 00:00:00.0   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 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, among others, the data provided, the specified ID and 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 column serves as the object’s 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
#> Missing values: explicit
#> Time zone:      UTC
#> Timestamps:     2192

With this done, we can move on and further explore our newly created time series data object 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")'
}