---
title: "1. TWDTW: Time-Weighted Dynamic Time Warping"
author: "Victor Maus"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{1. TWDTW: Time-Weighted Dynamic Time Warping}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
bibliography: ./../inst/REFERENCES.bib
---

```{r, echo=FALSE, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE)
knitr::opts_chunk$set(fig.height = 4.5)
knitr::opts_chunk$set(fig.width = 6)
```

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:2016 and @Maus: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
```{r , echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE}
library(dtwSat)

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

veg_profiles

class(veg_profiles)

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
```{r , echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE}
veg_ts <- twdtwTimeSeries(MOD13Q1.ts)

veg_ts

class(veg_ts)

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 
```{r echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE}
# 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)

twdtw_matches
```

TWDTW analysis has found `r length(twdtw_matches)` alignments, i.e. `r length(twdtw_matches)` 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`. 
```{r, echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE}
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`.
```{r, echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE}
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
```{r, echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE}
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
```{r, echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE}
twdtw_classification <- twdtwClassify(x = twdtw_matches, 
                                      from = "2009-09-01", 
                                      to = "2014-08-31", 
                                      by = "12 month")

twdtw_classification

plot(twdtw_classification, type = "classification")
```

In this last chunk of code we answered our question. We can see that only the `r length(twdtw_classification)` 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


