# 1. TWDTW: Time-Weighted Dynamic Time Warping

This vignette present a short introduction on Time-Weighted Dynamic Time Warping (TWDTW) analysis using dtwSat. TWDTW is an algorithm for land cover mapping using multi-band satellite image time series. The algorithm is particularly valuable to produce land cover maps in regions with scarcity of training data. For details see Maus et al. (2016) and Maus et al. (2019).

# Satellite images time series

Continuous Earth observation measurements produce sequences of multi-temporal images–satellite images time series. TWDTW algorithm can extract information from satellite images time series, in particular about vegetation with annual phenological cycle.

An example of phenological cycles is available in dtwSat as MOD13Q1.MT.yearly.patterns, which includes temporal profiles of vegetation in the Brazilian Amazon extracted from MOD13Q1 time series. You can load and visualize these profiles in your R session using

library(dtwSat)

veg_profiles <- twdtwTimeSeries(MOD13Q1.MT.yearly.patterns)

veg_profiles
## An object of class "twdtwTimeSeries"
## Slot "timeseries" length: 11
## Slot "labels": [1] "Cotton-fallow"  "Forest"         "Low vegetation"

class(veg_profiles)
## [1] "twdtwTimeSeries"
## attr(,"package")
## [1] "dtwSat"

plot(veg_profiles, type = "patterns")

We can refer to the above profiles as the library of known vegetation phenological cycles in the study area. For this area study area dtwSat also provides some examples of time series, which you can load by running

veg_ts <- twdtwTimeSeries(MOD13Q1.ts)

veg_ts
## An object of class "twdtwTimeSeries"
## Slot "timeseries" length: 1
## Slot "labels": [1] "ts1"

class(veg_ts)
## [1] "twdtwTimeSeries"
## attr(,"package")
## [1] "dtwSat"

plot(veg_ts, type = "timeseries")

# TWDTW analysis

Comparing the above time series to the profiles library, which is the sequence of vegetation types in the above time series? To answered this question we can run a TWDTW analysis and compare the above time series to the profiles library, such that

# Define logistic time-weight, see Maus et al. (2016)
weight_fun <- logisticWeight(alpha = -0.1, beta = 50)

# Run TWDTW analysis
twdtw_matches <- twdtwApply(x = veg_ts,
y = veg_profiles,
weight.fun = weight_fun,
keep = TRUE, legacy=TRUE)

class(twdtw_matches)
## [1] "twdtwMatches"
## attr(,"package")
## [1] "dtwSat"

twdtw_matches
## An object of class "twdtwMatches"
## Number of time series: 1
## Number of alignments: 56
## Patterns labels: Cotton-fallow Forest Low vegetation Pasture Soybean-cotton Soybean-fallow Soybean-maize Soybean-millet Soybean-sunflower Water Wetland

TWDTW analysis has found 56 alignments, i.e. 56 alignments between the profiles in the library and shorter segments of the time series. Each of these matches have an associated dissimilarity metric–the TWDTW distance. Using the code below we can visualize all matches with a TWDTW distance lower than 10.0.

plot(x = twdtw_matches,
type = "alignments",
threshold = 10.0)

Every segment in the figure shows one possible match between the profiles and the time series. The segments with lower TWDTW distance are more likely to be the correct classification for that specific segment.

To further investigate the segments by looking at the matching points (observation) between a single pattern and the time series. In the code below we visualize the matching observations for the two best (lowest TWDTW distance) alignments of the Soybean-cotton.

plot(x = twdtw_matches,
type = "matches",
attr = "evi",
patterns.labels = "Soybean-cotton",
k = 2) 

We can also investigate the paths of minimum cost in the TWDTW cost matrix for each profile, for example for Soybean-cotton run

plot(x = twdtw_matches,
type = "paths",
patterns.labels = "Soybean-cotton")

Finally we define sub-intervals of 12 months and classify each segment of the time series into one class in our profiles library, such that

twdtw_classification <- twdtwClassify(x = twdtw_matches,
from = "2009-09-01",
to = "2014-08-31",
by = "12 month")

twdtw_classification
## An object of class "twdtwMatches"
## Number of time series: 1
## Number of alignments: 4
## Patterns labels: Cotton-fallow Forest Low vegetation Pasture Soybean-cotton Soybean-fallow Soybean-maize Soybean-millet Soybean-sunflower Water Wetland

plot(twdtw_classification, type = "classification")

In this last chunk of code we answered our question. We can see that only the 4 best alignments over all land cover classes remained, i.e. the alignments with the lowest TWDTW distance per segment.

This short introduction showed how to use dtwSat to analyse and classify a single time series. This is useful to better understand the method and adjust classification parameters. To learn how apply the method to a raster stack please red the next vignette.

# References

Maus, Victor, Gilberto Camara, Marius Appel, and Edzer Pebesma. 2019. dtwSat: Time-Weighted Dynamic Time Warping for Satellite Image Time Series Analysis in R.” Journal of Statistical Software 88 (5): 1–31. https://doi.org/10.18637/jss.v088.i05.
Maus, Victor, Gilberto Camara, Ricardo Cartaxo, Alber Sanchez, Fernando M. Ramos, and Gilberto R. de Queiroz. 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 9 (8): 3729–39. https://doi.org/10.1109/JSTARS.2016.2517118.