dtwSat (version 0.2.8)

twdtwApply: Apply TWDTW analysis

Description

This function performs a multidimensional Time-Weighted DTW analysis and retrieves the matches between the temporal patterns and a set of time series Maus:2019dtwSat.

Usage

twdtwApply(
  x,
  y,
  resample = TRUE,
  length = NULL,
  weight.fun = function(phi, psi) phi,
  dist.method = "Euclidean",
  step.matrix = symmetric1,
  n = NULL,
  span = NULL,
  min.length = 0,
  ...
)
# S4 method for twdtwTimeSeries
twdtwApply(
  x,
  y,
  resample,
  length,
  weight.fun,
  dist.method,
  step.matrix,
  n,
  span,
  min.length,
  legacy = FALSE,
  keep = FALSE,
  ...
)
# S4 method for twdtwRaster
twdtwApply(
  x,
  y,
  resample,
  length,
  weight.fun,
  dist.method,
  step.matrix,
  n,
  span,
  min.length,
  breaks = NULL,
  from = NULL,
  to = NULL,
  by = NULL,
  overlap = 0.5,
  filepath = "",
  fill = NULL,
  legacy = FALSE,
  progress = "text",
  minrows = 1,
  alpha = -0.1,
  beta = 50,
  ...
)

Value

An object of class twdtw*.

Arguments

x

An object of class twdtw*. This is the target time series. Usually, it is a set of unclassified time series.

y

An object of class twdtwTimeSeries. The temporal patterns.

resample

Resample the patterns to have the same length. Default is TRUE. See resampleTimeSeries for details.

length

An integer. Length of patterns used with patterns.length. If not declared the length of the output patterns will be the length of the longest pattern.

weight.fun

A function. Any function that receives two matrices and performs a computation on them, returning a single matrix with the same dimensions. The first matrix is the DTW local cost matrix and the second a matrix of the time differences in days. The function should return a matrix of DTW local cost weighted by the time differences. If not declared the time-weight is zero. In this case the function runs the standard version of the dynamic time warping. See details.

dist.method

A character. Method to derive the local cost matrix. Default is ''Euclidean'' see dist in package proxy.

step.matrix

See stepPattern in package dtw Giorgino:2009dtwSat.

n

An integer. The maximun number of matches to perform. NULL will return all matches.

span

A number. Span between two matches, i.e. the minimum interval between two matches; for details see Muller:2007dtwSat. If not declared it removes all overlapping matches of the same pattern. To include overlapping matches of the same pattern use span=0.

min.length

A number between 0 an 1. This argument removes overfittings. Minimum length after warping. Percentage of the original pattern length. Default is 0.5, meaning that the matching cannot be shorter than half of the pattern length.

...

Arguments to pass to writeRaster and pbCreate

legacy

logical. If FALSE, runs a faster new TWDTW implementation. Default FLASE

keep

Preserves the cost matrix, inputs, and other internal structures. Default is FALSE. For plot methods use keep=TRUE.

breaks

A vector of class Dates. This replaces the arguments from, to, and by.

from

A character or Dates object in the format "yyyy-mm-dd".

to

A character or Dates object in the format "yyyy-mm-dd".

by

A character with the interval size, e.g. "6 month".

overlap

A number between 0 and 1. The minimum overlapping between one match and the interval of classification. Default is 0.5, i.e. an overlap minimum of 50%.

filepath

A character. The path at which to save the raster with results. If not provided the function saves in the current work directory.

fill

A character to fill the classification gaps. For signature twdtwTimeSeries the default is fill="unclassified", for signature twdtwRaster the default is fill="unclassified".

progress

character. 'text' or 'window'.

minrows

Integer. Minimum number of rows in each block

alpha

Numeric. The steepness of TWDTW logistic weight.

beta

Numeric. The midpoint of TWDTW logistic weight.

Author

Victor Maus,

Details

The linear linearWeight and logisticWeight weight functions can be passed to twdtwApply through the argument weight.fun. This will add a time-weight to the dynamic time warping analysis. The time weight creates a global constraint useful for analyzing time series with phenological cycles of vegetation that are usually bound to seasons. In previous studies by Maus:2016dtwSat the logistic weight had better results than the linear for land cover classification. See Maus:2016,Maus:2019dtwSat for details about the method.

References

See Also

twdtwMatches-class, twdtwTimeSeries-class, twdtwRaster-class, getTimeSeries, and createPatterns

Examples

# Applying TWDTW analysis to objects of class twdtwTimeSeries
log_fun = logisticWeight(-0.1, 100)
ts = twdtwTimeSeries(MOD13Q1.ts.list)
patt = twdtwTimeSeries(MOD13Q1.patterns.list)
mat1 = twdtwApply(x=ts, y=patt, weight.fun=log_fun, keep=TRUE, legacy=TRUE)
mat1

if (FALSE) {
# Parallel processin
require(parallel)
mat_list = mclapply(as.list(ts), mc.cores=2, FUN=twdtwApply, y=patt, weight.fun=log_fun)
mat2 = twdtwMatches(alignments=mat_list)
}
if (FALSE) {
  
# Example of TWDTW analysis using raster files 
library(dtwSat)
library(caret) 

# Load raster data 
evi  <- brick(system.file("lucc_MT/data/evi.tif",  package = "dtwSat"))
ndvi <- brick(system.file("lucc_MT/data/ndvi.tif", package = "dtwSat"))
red  <- brick(system.file("lucc_MT/data/red.tif",  package = "dtwSat"))
blue <- brick(system.file("lucc_MT/data/blue.tif", package = "dtwSat"))
nir  <- brick(system.file("lucc_MT/data/nir.tif",  package = "dtwSat"))
mir  <- brick(system.file("lucc_MT/data/mir.tif",  package = "dtwSat"))
doy  <- brick(system.file("lucc_MT/data/doy.tif",  package = "dtwSat"))
timeline <- 
  scan(system.file("lucc_MT/data/timeline", package = "dtwSat"), what="date")

# Create raster time series 
rts <- twdtwRaster(evi, ndvi, red, blue, nir, mir, timeline = timeline, doy = doy)

# Load field samples and projection 
field_samples <- 
  read.csv(system.file("lucc_MT/data/samples.csv", package = "dtwSat"))
proj_str <- 
  scan(system.file("lucc_MT/data/samples_projection", package = "dtwSat"), 
       what = "character")

# Split samples for training (10%) and validation (90%) using stratified sampling 
set.seed(1)
I <- unlist(createDataPartition(field_samples$label, p = 0.1))
training_samples <- field_samples[I, ]
validation_samples <- field_samples[-I, ]

# Get time series form raster
training_ts <- getTimeSeries(rts, y = training_samples, proj4string = proj_str)
validation_ts <- getTimeSeries(rts, y = validation_samples, proj4string = proj_str)

# Create temporal patterns 
temporal_patterns <- createPatterns(training_ts, freq = 8, formula = y ~ s(x))

# Set TWDTW weight function 
log_fun <- logisticWeight(-0.1, 50)

# Run TWDTW analysis 
system.time(
  r_twdtw <-
    twdtwApply(x = rts, y = temporal_patterns, weight.fun = log_fun, progress = 'text') 
)

# Plot TWDTW distances for the first year 
plot(r_twdtw, type = "distance", time.levels = 1)

# Classify raster based on the TWDTW analysis 
r_lucc <- twdtwClassify(r_twdtw, progress = 'text')

# Plot TWDTW classification results 
plot(r_lucc, type = "map")

# Assess classification 
twdtw_assess <- 
  twdtwAssess(object = r_lucc, y = validation_samples, 
              proj4string = proj_str, conf.int = .95) 

# Plot map accuracy 
plot(twdtw_assess, type = "accuracy")

# Plot area uncertainty 
plot(twdtw_assess, type = "area")

# Plot misclassified samples  
plot(twdtw_assess, type = "map", samples = "incorrect") 

# Get latex table with error matrix 
twdtwXtable(twdtw_assess, table.type = "matrix")

# Get latex table with error accuracy 
twdtwXtable(twdtw_assess, table.type = "accuracy")

# Get latex table with area uncertainty 
twdtwXtable(twdtw_assess, table.type = "area")

}