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 [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 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 for parallel processing to pass to mclapply.

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 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%.

chunk.size

An integer. Set the number of cells for each block, see blockSize for details.

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 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.

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 Time-Weighted 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.1-11.

[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.

See Also

twdtwMatches-class, twdtwTimeSeries-class, twdtwRaster-class, 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("2007-09-01"), to=as.Date("2013-09-01"), 
                    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)

Want to suggest features or report bugs for rdrr.io? Use the GitHub issue tracker.