twdtwApplyParallel: Apply TWDTW analysis to twdtwRaster using parallel processing
In vwmaus/dtwSat: Time-Weighted Dynamic Time Warping for Satellite Image Time Series Analysis

Description Usage Arguments Details Value Author(s) References See Also Examples

This function performs a multidimensional Time-Weighted DTW analysis and retrieves the matches between the temporal patterns and a set of time series [1].

twdtwApplyParallel(x, y, resample = TRUE, length = NULL,
  weight.fun = NULL, dist.method = "Euclidean",
  step.matrix = symmetric1, n = NULL, span = NULL, min.length = 0,
  theta = 0.5, ...)

## S4 method for signature 'twdtwRaster'
twdtwApplyParallel(x, y, resample, length,
  weight.fun, dist.method, step.matrix, n, span, min.length, theta,
  breaks = NULL, from = NULL, to = NULL, by = NULL,
  overlap = 0.5, filepath = "", ...)

`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. Patterns length 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 receive and performs a computation on a matrix. The function receives a matrix of time differences in days and returns a matrix of time-weights. 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 [2].
`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 [3]. 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 the over fittings. 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.
`theta`	numeric between 0 and 1. The weight of the time for the TWDTW computation. Use `theta=0` to cancel the time-weight, i.e. to run the original DTW algorithm. Default is 0.5, meaning that the time has the same weight as the curve shape in the TWDTW analysis.
`...`	arguments to pass to `writeRaster` and `pbCreate`
`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 intevals 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 to save the raster with results. If not informed the function saves in the current work directory.

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 to analyse time series with phenological cycles of vegetation that are usually bound to seasons. In previous studies by [1] the logistic weight had better results than the linear for land cover classification. See [1] for details about the method.

An object of class twdtwRaster.

Victor Maus, [email protected]

[1] Maus V, Camara G, Cartaxo R, Sanchez A, Ramos FM, de Queiroz, GR. (2016). A Time-Weighted Dynamic Time Warping method for land use and land cover mapping. IEEE Journal of Selected Topics in Applied Earth Observations and Remote Sensing, vol.9, no.8, pp.3729-3739.

[2] Giorgino, T. (2009). Computing and Visualizing Dynamic Time Warping Alignments in R: The dtw Package. Journal of Statistical Software, 31, 1-24.

[3] Muller, M. (2007). Dynamic Time Warping. In Information Retrieval for Music and Motion (pp. 79-84). London: Springer London, Limited.

twdtwRaster-class, and createPatterns

## Not run: 
  
# 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 serial TWDTW analysis 
r_twdtw <-
  twdtwApply(x = rts, y = temporal_patterns, weight.fun = log_fun, progress = 'text')

# or Run parallel TWDTW analysis
beginCluster()
r_twdtw <- 
  twdtwApplyParallel(x = rts, y = temporal_patterns, weight.fun = log_fun, progress = 'text')
endCluster()

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


## End(Not run)