Apply TWDTW analysis
Description
This function performs a multidimensional TimeWeighted DTW analysis and retrieves the matches between the temporal patterns and a set of time series [1].
Usage
1 2 3 4 5 6 7 8 9 10 11 12 13  twdtwApply(x, y, resample = TRUE, length = NULL, weight.fun = NULL,
dist.method = "Euclidean", step.matrix = symmetric1, n = NULL,
span = NULL, min.length = 0.5, theta = 0.5, ...)
## S4 method for signature 'twdtwTimeSeries'
twdtwApply(x, y, resample, length, weight.fun,
dist.method, step.matrix, n, span, min.length, theta, keep = FALSE, ...)
## S4 method for signature 'twdtwRaster'
twdtwApply(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, chunk.size = 1000,
filepath = NULL, ...)

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. Patterns length used with 
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 timeweights. If not declared the timeweight 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 
step.matrix 
see 
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 
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 
... 
arguments to pass to 
keep 
preserves the cost matrix, inputs, and other internal structures.
Default is FALSE. For plot methods use 
breaks 
A vector of class 
from 
A character or 
to 
A 
by 
A 
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%. 
chunk.size 
An integer. Set the number of cells for each block,
see 
filepath 
A character. The path to save the raster with results. If not informed the function saves in the current work directory. 
Details
The linear linearWeight
and logisticWeight
weight functions
can be passed to twdtwApply
through the argument weight.fun
. This will
add a timeweight 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.
Value
An object of class twdtw*.
Author(s)
Victor Maus, vwmaus1@gmail.com
References
[1] Maus V, Camara G, Cartaxo R, Sanchez A, Ramos FM, de Queiroz, GR. (2016). A TimeWeighted Dynamic Time Warping method for land use and land cover mapping. Selected Topics in Applied Earth Observations and Remote Sensing, IEEE Journal of, vol.PP, no.99, pp.111.
[2] Giorgino, T. (2009). Computing and Visualizing Dynamic Time Warping Alignments in R: The dtw Package. Journal of Statistical Software, 31, 124.
[3] Muller, M. (2007). Dynamic Time Warping. In Information Retrieval for Music and Motion (pp. 7984). London: Springer London, Limited.
See Also
twdtwMatchesclass
,
twdtwTimeSeriesclass
,
twdtwRasterclass
,
getTimeSeries
, and
createPatterns
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45  # Applying TWDTW analysis to objects of class twdtwTimeSeries
log_fun = logisticWeight(0.1, 100)
ts = twdtwTimeSeries(example_ts.list)
patt = twdtwTimeSeries(patterns.list)
mat1 = twdtwApply(x=ts, y=patt, weight.fun=log_fun)
mat1
## Not run:
# 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)
## End(Not run)
## Not run:
# Run TWDTW analysis for raster time series
patt = yearly_patterns_mt
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")
rts = twdtwRaster(evi, ndvi, red, blue, nir, mir, timeline = timeline, doy = doy)
time_interval = seq(from=as.Date("20070901"), to=as.Date("20130901"),
by="12 month")
log_fun = weight.fun=logisticWeight(0.1,50)
r_twdtw = twdtwApply(x=rts, y=patt, weight.fun=log_fun, breaks=time_interval,
filepath="~/test_twdtw", overwrite=TRUE, format="GTiff", mc.cores=3,
chunk.size=1000)
plot(r_twdtw, type="distance")
r_lucc = twdtwClassify(r_twdtw, format="GTiff", overwrite=TRUE)
plot(r_lucc)
plot(r_lucc, type="distance")
## End(Not run)
