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

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)
<- twdtwTimeSeries(MOD13Q1.MT.yearly.patterns)
veg_profiles
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

```
<- twdtwTimeSeries(MOD13Q1.ts)
veg_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")
```

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)
<- logisticWeight(alpha = -0.1, beta = 50)
weight_fun
# Run TWDTW analysis
<- twdtwApply(x = veg_ts,
twdtw_matches 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

```
<- twdtwClassify(x = twdtw_matches,
twdtw_classification 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.

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.