Transform Values in Time Series Lists

Function tor time series transformations without changes in data dimensions. Generally, functions introduced via the argument f should not change the dimensions of the output time series list. See tsl_resample() and tsl_aggregate() for transformations requiring changes in time series dimensions.However, there are glaring exceptions. For example, f_center() and f_scale() compute the overall mean and standard deviation across all zoo objects in the time series list to apply a common transformation. This operation requires removing exclusive columns from the zoo objects via tsl_subset().

This function supports progress bars generated by the progressr package. See examples.

This function also accepts a parallelization setup via future::plan(), but it might only be worth it for large time series lists.

Usage

tsl_transform(tsl = NULL, f = NULL, ...)

Arguments

tsl

(required, list) Time series list. Default: NULL

f

(required, transformation function) name of a function taking a matrix as input. Currently, the following options are implemented, but any other function taking a matrix as input (for example, scale()) should work as well:

f_proportion: proportion computed by row.
f_percentage: percentage computed by row.
f_hellinger: Hellinger transformation computed by row
f_center: Centering computed by column using the column mean across all zoo objects within tsl.
f_scale: Centering and scaling using the column mean and standard deviation across all zoo objects within tsl.
f_smooth: Time series smoothing with a user defined rolling window.
f_detrend_difference: Differencing detrending of time series via diff().
f_detrend_linear: Detrending of seasonal time series via linear modeling.
f_detrend_gam: Detrending of seasonal time series via Generalized Additive Models.

...

(optional, additional arguments of f) Optional arguments for the transformation function.

Value

time series list

Examples

future::plan(
  future::multisession,
  workers = 2 #set to parallelly::availableWorkers() - 1
)

#progress bar
# progressr::handlers(global = TRUE)

#two time series
tsl <- tsl_initialize(
  x = fagus_dynamics,
  name_column = "name",
  time_column = "time"
) |>
  tsl_subset(
    names = c("Spain", "Sweden"),
    colnames = c("rainfall", "temperature")
  )

if(interactive()){
  tsl_plot(
    tsl = tsl
  )
}

#centering and scaling
#-----------------------------------------
#same mean and standard deviation are used to scale each variable across all time series
tsl_scale <- tsl_transform(
  tsl = tsl,
  f = f_scale
)

if(interactive()){
  tsl_plot(
    tsl = tsl_scale,
    guide_columns = 3
  )
}


#rescaling to a new range
#-----------------------------------------

#rescale between -100 and 100
tsl_rescaled <- tsl_transform(
  tsl = tsl,
  f = f_rescale,
  new_min = -100,
  new_max = 100
)

#old range
sapply(X = tsl, FUN = range)
#>      Spain Sweden
#> [1,]   4.5   -4.7
#> [2,] 216.6  189.6

#new range
sapply(X = tsl_rescaled, FUN = range)
#>      Spain Sweden
#> [1,]  -100   -100
#> [2,]   100    100


#moving window smoothing
#-----------------------------------------
tsl_smooth_mean <- tsl_transform(
  tsl = tsl,
  f = f_smooth_window,
  smoothing_window = 3, #default
  smoothing_f = mean #default
)

if(interactive()){
  tsl_plot(
    tsl = tsl_smooth_mean,
    guide_columns = 3
  )
}

#principal components
#-----------------------------------------
#replaces original variables with their principal components
#requires centering and/or scaling
tsl_pca <- tsl |>
  tsl_transform(
    f = f_scale
  ) |>
  tsl_transform(
    f = f_pca
  )

tsl_colnames_get(tsl = tsl_pca)
#> $Spain
#> [1] "PC1" "PC2"
#> 
#> $Sweden
#> [1] "PC1" "PC2"
#> 

if(interactive()){
  tsl_plot(
    tsl = tsl_pca,
    guide_columns = 3
  )
}


#numeric transformations
#-----------------------------------------
#eemian pollen counts
tsl <- tsl_initialize(
  x = eemian_pollen,
  name_column = "name",
  time_column = "time"
)
#> Warning: Duplicated indices in 'Krumbach_I':
#> - value 6.8 replaced by 6.825

if(interactive()){
  tsl_plot(
    tsl = tsl
  )
}

#percentages
tsl_percentage <- tsl_transform(
  tsl = tsl,
  f = f_percentage
)

if(interactive()){
  tsl_plot(
    tsl = tsl_percentage
  )
}

#hellinger transformation
tsl_hellinger <- tsl_transform(
  tsl = tsl,
  f = f_hellinger
)
#> distantia::tsl_count_NA(): NA cases in 'tsl': 
#>            name NA_cases
#> 1     Achenhang        0
#> 2   Glowczyn_G2        0
#> 3     Grobern94        0
#> 4     Jammertal        0
#> 5 Kletnia_Stara        0
#> 6    Krumbach_I       22
#> 7         Naklo        0
#> 8        Ostrow        0
#> 9        W_KASP        0
#> Please impute, replace, or remove them with tsl_handle_NA().FALSE

if(interactive()){
  tsl_plot(
    tsl = tsl_hellinger
  )
}

#disable parallelization
future::plan(
  future::sequential
)

Usage

Arguments

Value

See also

Examples