Package {twdtw}


Title: Time-Weighted Dynamic Time Warping
Version: 1.1-0
Description: Provides a fast implementation of Time-Weighted Dynamic Time Warping (TWDTW), a measure for quantifying time series similarity. The TWDTW algorithm, described in Maus et al. (2016) <doi:10.1109/JSTARS.2016.2517118> and Maus et al. (2019) <doi:10.18637/jss.v088.i05>, is applicable to multi-dimensional time series of various resolutions. It is particularly suitable for comparing time series with seasonality for environmental and ecological data analysis, covering domains such as remote sensing imagery, climate data, hydrology, and animal movement. The 'twdtw' package offers a user-friendly 'R' interface, efficient 'Fortran' routines for TWDTW calculations, a k-nearest neighbour model to classify time series, flexible time weighting definitions, as well as utilities for time series preprocessing and visualization. With one temporal pattern for each class, the classification of time series has a processing time comparable to that of other machine learning models available in 'R', such as random forest and support vector machines.
License: GPL (≥ 3)
URL: https://github.com/vwmaus/twdtw/
BugReports: https://github.com/vwmaus/twdtw/issues/
Encoding: UTF-8
Imports: Rcpp, proxy
Suggests: rbenchmark, testthat (≥ 3.0.0)
LinkingTo: Rcpp
Collate: 'RcppExports.R' 'convert_date_to_numeric.R' 'init.R' 'plot_cost_matrix.R' 'time_series_formats.R' 'twdtw.R' 'twdtw_knn.R' 'twdtw_knn_predict.R' 'twdtw_nearest.R' 'zzz.R'
Config/testthat/edition: 3
Config/roxygen2/version: 8.1.1
NeedsCompilation: yes
Packaged: 2026-11-20 18:30:59 UTC; maus
Author: Victor Maus ORCID iD [aut, cre]
Maintainer: Victor Maus <vwmaus1@gmail.com>
Repository: CRAN
Date/Publication: 2026-11-20 19:20:02 UTC

Convert Date/POSIXct to a Numeric Cycle

Description

This function takes a date or datetime and converts it to a numeric cycle. The cycle can be specified in units of years, months, days, hours, minutes, or seconds. When cycle_length is a string, time_scale only changes the unit in which the result is expressed. When cycle_length is numeric, time_scale and origin are used to compute the elapsed time.

Usage

date_to_numeric_cycle(x, cycle_length, time_scale, origin = NULL)

Arguments

x

A vector of dates or datetimes to convert. If not of type Date or POSIXct, the function attempts to convert it.

cycle_length

The length of the cycle. Can be a numeric value or a string specifying the units ('year', 'month', 'day', 'hour', 'minute', 'second'). When numeric, the cycle length is in the same units as time_scale. When a string, it specifies the time unit of the cycle.

time_scale

Specifies the time scale for the conversion. Must be one of 'year', 'month', 'day', 'hour', 'minute', 'second'. When cycle_length is a string, time_scale changes the unit in which the result is expressed. When cycle_length is numeric, time_scale is used to compute the elapsed time in seconds.

origin

For numeric cycle_length, the origin must be specified. This is the point from which the elapsed time is computed. Must be of the same class as x.

Value

The numeric cycle value(s) corresponding to x.

Examples

date_to_numeric_cycle(Sys.time(), "year", "day") # Returns the day of the year
date_to_numeric_cycle(Sys.time(), "day", "hour") # Returns the hour of the day

Calculate the Maximum Possible Value of a Time Cycle

Description

This function returns the maximum possible value that a specific time component can take, given a cycle length and scale.

Usage

max_cycle_length(cycle_length, time_scale)

Arguments

cycle_length

A character string indicating the larger unit of time. It must be one of "year", "month", "day", "hour", "minute".

time_scale

A character string indicating the smaller unit of time, which is a division of the cycle_length. If cycle_length is "year", time_scale can be one of "month", "day", "hour", "minute", "second". If cycle_length is "month", time_scale can be "day", "hour", "minute", "second", and so on.

Value

The function returns the maximum possible value that the time_scale can take within one cycle_length.

Examples


max_cycle_length("year", "month")  # Maximum months is a year 12
max_cycle_length("day", "minute")  # Maximum minutes in a day 1440
max_cycle_length("year", "day")    # Maximum days in a year 366


Plot TWDTW cost matrix

Description

This function visualizes the Time-Weighted Dynamic Time Warping cost matrix.

Usage

plot_cost_matrix(x, ...)

Arguments

x

An object of class 'twdtw' including internal data.

...

Additional arguments passed to image.

Value

An image plot of the TWDTW cost matrix. The x-axis represents the time series x, and the y-axis represents the time series y. The cost matrix is color-coded, with darker shades indicating higher costs and lighter shades indicating lower costs. No object is returned by this function; the plot is directly outputted to the active device.

Examples


# Create a time series
n <- 23
t <- seq(0, pi, length.out = n)
d <- seq(as.Date('2020-09-01'), length.out = n, by = "15 day")

x <- data.frame(time = d,      v1 = sin(t)*2 + runif(n))

# shift time by 30 days
y <- data.frame(time = d + 30, v1 = sin(t)*2 + runif(n))

plot(x, type = "l", xlim = range(c(d, d + 5)))
lines(y, col = "red")

# Call twdtw using "output = 'internals'
twdtw_obj <- twdtw(x, y,
       cycle_length = 'year',
       time_scale = 'day',
       time_weight = c(steepness = 0.1, midpoint = 50), output = 'internals')

plot_cost_matrix(twdtw_obj)


Classify time series using a TWDTW k-nearest neighbour model

Description

This function classifies time series with a model created by twdtw_knn. Each time series gets a label from the labels of its k nearest temporal patterns, i.e. the patterns of the model with the lowest Time-Weighted Dynamic Time Warping (TWDTW) distance. By default k = 1 and each time series gets the label of the nearest pattern.

Usage

## S3 method for class 'twdtw_knn'
predict(
  object,
  newdata,
  k = 1,
  vote = c("majority", "weighted"),
  type = c("class", "prob", "neighbors"),
  time = NULL,
  ...
)

Arguments

object

A model of class twdtw_knn, created by twdtw_knn.

newdata

The time series to classify, in one of the three forms of the time series of twdtw_knn: a list of data.frames or matrices, a data.frame with one row for each time series and one column for each band and date, or a numeric array with the dimensions series, time, and band.

k

The number of nearest temporal patterns used for each time series. An integer between one and the number of temporal patterns of the model. Defaults to 1, i.e. only the nearest pattern is used.

vote

The weight of the vote of each of the k nearest patterns. Either "majority" (default), where each pattern has one vote, or "weighted", where each pattern votes with the weight 1/distance. It can change the result only if k is larger than one. See details.

type

What the function returns for each time series. One of:

  • "class" (default): the predicted label, i.e. the label with the most votes, and the distance to the nearest pattern with this label.

  • "prob": a score from 0 to 1 for each label of the model, i.e. the share of the votes that the label gets.

  • "neighbors": the labels and the distances of the k nearest patterns, without a vote.

See details.

time

A vector with the dates of the time dimension of an array newdata. Its length must be equal to dim(newdata)[2]. It is only used if newdata is an array.

...

Arguments of the TWDTW distance that replace the arguments of the model: time_weight, cycle_length, time_scale, origin, and max_elapsed. For a list newdata also index_column, the column name or the column position of the time index, which defaults to "time". An argument that is not known is an error.

Details

A time series is classified in three steps, which are set by k, vote, and type:

  1. The k temporal patterns of the model with the lowest TWDTW distance to the time series are found.

  2. Each of these patterns votes for its label. With vote = "majority" each pattern has one vote. With vote = "weighted" each pattern votes with the weight 1/distance, so that a pattern twice as far has half the weight.

  3. type sets what is returned: the label with the most votes ("class"), the share of the votes of each label ("prob"), or the k nearest patterns without a vote ("neighbors").

With the defaults k = 1, vote = "majority", and type = "class", each time series gets the label of its nearest pattern.

As an example, let the three nearest patterns of a time series (k = 3) have the labels soybean, maize, and maize, and the distances 1, 4, and 4:

The three types of result in more detail:

With vote = "weighted", patterns at distance zero get all the votes. Negative distances, which are possible only with a time-weight function, are an error with this vote.

A vote can only change the prediction if the model has more than one temporal pattern for a label, as a model created without resampling_fun. With one pattern for each label, every label has one vote: the prediction is the label of the nearest pattern for any k, and vote = "weighted" with k equal to the number of patterns gives shares that are proportional to 1/distance.

The votes use the nearest patterns that are found for any type, so the shares of the votes need no additional TWDTW distances. A larger k takes more time, because the calculation of the distance to a pattern stops as soon as the pattern cannot be among the k nearest.

The TWDTW distances between all time series and all temporal patterns are calculated in a single call to twdtw_nearest. An array newdata is passed to this function as it is and is the fastest form. The other forms are converted to arrays.

The time series must have the bands of the temporal patterns of the model. An observation with a missing value in any band is not used, and the time series is classified with its remaining observations. A time series without any complete observation has NA in all columns of the result.

The time series are converted by twdtw_knn_predict. Other packages can add methods to this function to classify their classes of time series.

Value

A data.frame with one row for each time series in newdata, in the same order. The columns depend on type:

"class"

prediction, a factor with the predicted label, and distance, the TWDTW distance to the nearest temporal pattern with this label.

"prob"

One column for each label of the model, named with the label, with its share of the votes.

"neighbors"

prediction_1, ..., prediction_k and distance_1, ..., distance_k, where 1 is the nearest temporal pattern.

The predictions are factors with the labels of the model as levels, in alphabetical order.

See Also

twdtw_knn, twdtw_nearest

Examples


# Temporal patterns of 5 land use classes and satellite image time series of 999 pixels
ts_y <- readRDS(system.file("sits/modis_mod13q1_patterns.rds", package = "twdtw"))
ts_x <- readRDS(system.file("sits/modis_mod13q1_999ts.rds", package = "twdtw"))

m <- twdtw_knn(x = ts_y$observations,
               y = ts_y$label,
               cycle_length = 'year',
               time_scale = 'day',
               time_weight = c(steepness = 0.1, midpoint = 50))

# With the defaults each time series gets the label of its nearest pattern
lu <- predict(m, newdata = ts_x$observations)

head(lu)

# The model has one pattern for each label: weighted votes of all patterns
# give shares that are proportional to 1/distance
head(predict(m, newdata = ts_x$observations, k = 5, vote = "weighted", type = "prob"))

# A model that keeps 300 labelled time series as temporal patterns:
# the labels have several patterns, and the votes of the nearest patterns can be divided
m_samples <- twdtw_knn(x = ts_x$observations[1:300],
                       y = lu$prediction[1:300],
                       cycle_length = 'year',
                       time_scale = 'day',
                       time_weight = c(steepness = 0.1, midpoint = 50))

new_ts <- ts_x$observations[c(301, 307, 791)]

# type = "class": the label with the most votes among the 5 nearest patterns
predict(m_samples, newdata = new_ts, k = 5)

# type = "prob": the share of the votes of each label
predict(m_samples, newdata = new_ts, k = 5, type = "prob")

# Votes with the weight 1/distance change the shares,
# and the label of the third time series
predict(m_samples, newdata = new_ts, k = 5, vote = "weighted", type = "prob")

predict(m_samples, newdata = new_ts, k = 5, vote = "weighted")

# type = "neighbors": the labels and the distances of the nearest patterns
predict(m_samples, newdata = new_ts, k = 3, type = "neighbors")

# The fastest form is an array with the dimensions series, time, and band
bands <- c("EVI", "NDVI", "RED", "BLUE", "NIR", "MIR")
x <- sapply(ts_x$observations, function(ts) as.matrix(ts[bands]), simplify = "array")
x <- aperm(x, c(3, 1, 2))

lu_array <- predict(m, newdata = x, time = ts_x$observations[[1]]$time)

all.equal(lu, lu_array)


Print method for twdtw class

Description

Print method for twdtw class

Usage

## S3 method for class 'twdtw'
print(x, ...)

Arguments

x

An object of class twdtw.

...

Arguments passed to print.default or other methods.

Value

This function returns a textual representation of the object twdtw, which is printed directly to the console. If x is a list, the function will print a summary of matches and omit twdtw's internal data, see names(x). If x is not a list, it prints the content of x, i.e. either a matrix with all matches or the lowest twdtw distance.


Print method for twdtw_knn class

Description

Print method for twdtw_knn class

Usage

## S3 method for class 'twdtw_knn'
print(x, ...)

Arguments

x

An object of class twdtw_knn, created by twdtw_knn.

...

Not used.

Value

The object x, invisibly. The function prints the call that created the model, the number of temporal patterns and observations for each label, the root mean squared error of the models returned by resampling_fun, and the arguments of the TWDTW distance.


Convert to Date or POSIXct Format

Description

This function converts a vector of date-like strings to Date or POSIXct format, depending on the format of the input strings. It checks if the input is already in Date or POSIXct format and performs the conversion accordingly.

Usage

to_date_time(x)

Arguments

x

A vector of strings or objects to be converted.

Value

A vector of dates or datetimes.

Examples


dates <- c("2023-07-15", "2023-07-16")

datetimes <- c("2023-07-15 12:30:00", "2023-07-16 13:45:00")

to_date_time(dates)

to_date_time(datetimes)


Calculate Time-Weighted Dynamic Time Warping (TWDTW) distance

Description

This function calculates the Time-Weighted Dynamic Time Warping (TWDTW) distance between two time series.

Usage

twdtw(x, y, time_weight, cycle_length, time_scale, ...)

## S3 method for class 'data.frame'
twdtw(
  x,
  y,
  time_weight,
  cycle_length,
  time_scale,
  origin = NULL,
  index_column = "time",
  max_elapsed = Inf,
  output = "distance",
  version = "f90",
  ...
)

## S3 method for class 'matrix'
twdtw(
  x,
  y,
  time_weight,
  cycle_length,
  time_scale = NULL,
  index_column = 1,
  max_elapsed = Inf,
  output = "distance",
  version = "f90",
  ...
)

Arguments

x

A data.frame or matrix representing time series.

y

A data.frame or matrix representing a labeled time series (reference).

time_weight

A numeric vector with length two (steepness and midpoint of logistic weight) or a function. See details.

cycle_length

The length of the cycle. Can be a numeric value or a string specifying the units ('year', 'month', 'day', 'hour', 'minute', 'second'). When numeric, the cycle length is in the same units as time_scale. When a string, it specifies the time unit of the cycle.

time_scale

Specifies the time scale for the conversion. Must be one of 'year', 'month', 'day', 'hour', 'minute', 'second'. When cycle_length is a string, time_scale changes the unit in which the result is expressed. When cycle_length is numeric, time_scale is used to compute the elapsed time in seconds.

...

ignore

origin

For numeric cycle_length, the origin must be specified. This is the point from which the elapsed time is computed. Must be of the same class as x.

index_column

(optional) The column name of the time index for data.frame inputs. Defaults to "time". For matrix input, an integer indicating the column with the time index. Defaults to 1.

max_elapsed

Numeric value constraining the TWDTW calculation to the lower band given by a maximum elapsed time. Defaults to Inf.

output

A character string defining the output. It must be one of 'distance', 'matches', 'internals'. Defaults to 'distance'. 'distance' will return the lowest TWDTW distance between x and y. 'matches' will return all matches within the TWDTW matrix. 'internals' will return all TWDTW internal data.

version

A string identifying the version of TWDTW implementation. Options are 'f90' for Fortran 90, 'f90goto' for Fortran 90 with goto statements, or 'cpp' for C++ version. Defaults to 'f90'. The versions 'f90goto' and 'cpp' are deprecated and will be removed in version 1.2-0. See details.

Details

TWDTW calculates a time-weighted version of DTW by modifying each element of the DTW's local cost matrix (see details in Maus et al. (2016) and Maus et al. (2019)). The default time weight is calculated using a logistic function that adds a weight to each pair of observations in the time series x and y based on the time difference between observations, such that

tw(dist_{i,j}) = dist_{i,j} + \frac{1}{1 + e^{-{\alpha} (el_{i,j} - {\beta})}}

Where:

The logistic function is implemented as the default option in the C++ and Fortran versions of the code. To use the native implementation, \alpha and \beta must be provided as a numeric vector of length two using the argument time_weight. This implementation provides high processing performance.

The time_weight argument also accepts a function defined in R, allowing the user to define a different weighting scheme. However, passing a function to time_weight can degrade the processing performance, i.e., it can be up to 3x slower than using the default logistic time-weight.

A time-weight function passed to time_weight must receive two numeric arguments and return a single numeric value. The first argument received is the Euclidean dist_{i,j} and the second is the elapsed time el_{i,j}. For example, time_weight = function(dist, el) dist + 0.1*el defines a linear weighting scheme with a slope of 0.1. A time-weight function can only be used with version = 'f90', which is the default.

To calculate the distance without a time weight, use a logistic weight with a midpoint far above any elapsed time, e.g. time_weight = c(steepness = 1, midpoint = 1e6), which adds zero to the distance of each pair of observations. The result is the Dynamic Time Warping (DTW) distance as TWDTW calculates it: all observations of y are matched, and the match can start and end at any observation of x. This is not the DTW distance between two time series that are matched from their first to their last observations. The function function(dist, el) dist gives the same distance, but is slower.

The versions 'f90goto' and 'cpp' are deprecated and will be removed in version 1.2-0. They give the same result as the default version 'f90' for the logistic time weight, and twdtw gives a warning once per session if one of them is used.

You can use the max_elapsed parameter to limit the TWDTW calculation to a maximum elapsed time. This means it will skip comparisons between pairs of observations in x and y that are far apart in time. Be careful, though: if max_elapsed is set too low, it could change the results. It important to try out different settings for your specific problem.

The time series can have missing values. An observation with a missing value in any dimension is removed from x and y, and the distance is calculated with the remaining observations. Only if every observation of x or y has a missing value, there is nothing to compare: the distance is NA and there are no matches.

Value

An S3 object twdtw either: If output = 'distance', a numeric value representing the TWDTW distance between the two time series, or NA if every observation of one of them has a missing value. If output = 'matches', a numeric matrix of all TWDTW matches. For each match the starting index, ending index, and distance are returned. If output = 'internals', a list of all TWDTW internal data is returned.

References

Maus, V., Camara, G., Cartaxo, R., Sanchez, A., Ramos, F. M., & de Queiroz, G. R. (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-3739. doi:10.1109/JSTARS.2016.2517118

Maus, V., Camara, G., Appel, M., & Pebesma, E. (2019). dtwSat: Time-Weighted Dynamic Time Warping for Satellite Image Time Series Analysis in R. Journal of Statistical Software, 88(5), 1-31. doi:10.18637/jss.v088.i05

Examples


# Create a time series
n <- 23
t <- seq(0, pi, length.out = n)
d <- seq(as.Date('2020-09-01'), length.out = n, by = "15 day")

x <- data.frame(time = d,      v1 = sin(t)*2 + runif(n))

# shift time by 30 days
y <- data.frame(time = d + 30, v1 = sin(t)*2 + runif(n))

plot(x, type = "l", xlim = range(c(d, d + 5)))
lines(y, col = "red")

# Calculate TWDTW distance between x and y using logistic weight
twdtw(x, y,
      cycle_length = 'year',
      time_scale = 'day',
      time_weight = c(steepness = 0.1, midpoint = 50))

# Pass a generic time-weight function
twdtw(x, y,
      cycle_length = 'year',
      time_scale = 'day',
      time_weight = function(x,y) x + 1.0 / (1.0 + exp(-0.1 * (y - 50))))

# Without a time weight: a midpoint that no elapsed time reaches adds zero
twdtw(x, y,
      cycle_length = 'year',
      time_scale = 'day',
      time_weight = c(steepness = 1, midpoint = 1e6))


Create a k-nearest neighbour model using TWDTW

Description

This function creates a k-nearest neighbour (KNN) model to classify time series using the Time-Weighted Dynamic Time Warping (TWDTW) distance. The model keeps labelled time series as temporal patterns. predict classifies new time series with the labels of their nearest temporal patterns.

Usage

twdtw_knn(x, y, time_weight, cycle_length, time_scale, ..., time = NULL)

## S3 method for class 'list'
twdtw_knn(
  x,
  y,
  time_weight,
  cycle_length,
  time_scale,
  resampling_fun = NULL,
  resampling_freq = NULL,
  start = NULL,
  end = NULL,
  origin = NULL,
  max_elapsed = Inf,
  index_column = "time",
  ...,
  keep_models = FALSE
)

## S3 method for class 'data.frame'
twdtw_knn(
  x,
  y,
  time_weight,
  cycle_length,
  time_scale,
  resampling_fun = NULL,
  resampling_freq = NULL,
  start = NULL,
  end = NULL,
  origin = NULL,
  max_elapsed = Inf,
  ...,
  keep_models = FALSE
)

## S3 method for class 'array'
twdtw_knn(
  x,
  y,
  time_weight,
  cycle_length,
  time_scale,
  resampling_fun = NULL,
  resampling_freq = NULL,
  start = NULL,
  end = NULL,
  origin = NULL,
  max_elapsed = Inf,
  time = NULL,
  ...,
  keep_models = FALSE
)

Arguments

x

The labelled time series (samples) in one of three forms: a list of data.frames or matrices, a data.frame with one row for each time series, or a numeric array with the dimensions series, time, and band. See details.

y

A vector with the label of each time series in x, in the same order.

time_weight

A numeric vector with length two (steepness and midpoint of logistic weight) or a function. See details.

cycle_length

The length of the cycle, e.g. 'year'. See details in twdtw.

time_scale

The time scale of the observations, e.g. 'day'. See details in twdtw. It is not needed if both the time indices and cycle_length are numeric.

...

Arguments of the methods. An argument that a method does not know is an error.

time

A vector with the dates of the time dimension of an array x. Its length must be equal to dim(x)[2]. It is only used if x is an array.

resampling_fun

A function that creates one temporal pattern for each label from all time series with this label. If NULL (default), the model keeps all time series as temporal patterns. See details.

resampling_freq

The time between the observations of the temporal patterns created with resampling_fun, e.g. 16 for 16 days if the time indices are dates. If NULL (default), the temporal patterns have the time indices of the observations of the time series.

start, end

The time interval in which the label of each time series is valid. Either one value for all time series or a vector with one value for each time series, of the same class as the time indices. Only the observations from start to end, including both, are used. If NULL (default), all observations are used.

origin

For numeric cycle_length, the origin must be specified. This is the point from which the elapsed time is computed. Must be of the same class as x.

max_elapsed

Numeric value constraining the TWDTW calculation to the lower band given by a maximum elapsed time. Defaults to Inf.

index_column

The column name or the column position of the time index of the time series in a list. Defaults to "time".

keep_models

Whether the model keeps the fitted models that resampling_fun returns for each label and band, e.g. the gam objects. If FALSE (default), it keeps only their root mean squared error. The temporal patterns and the predictions do not depend on it. See details.

Details

The time series in x can have three forms:

All time series must have the same bands. Observations with dates are used in time order. Numeric time indices are in the units of the cycle, as in twdtw, and their observations are used in the order in which they are given. An observation with a missing value in any band is not used to calculate the TWDTW distance, and time series without any complete observation are removed with a warning.

If resampling_fun is NULL, the model keeps all time series as temporal patterns. Such a model can have several patterns for each label and can be classified with more than one nearest neighbour, see the argument k of predict.twdtw_knn.

If resampling_fun is a function, the model has one temporal pattern for each label. This reduces the number of TWDTW distances that predict calculates from the number of labelled time series to the number of labels. The function is called for each label and band with a data.frame that has two columns: x, the time index as a number, and y, the values of all time series with this label. It must return a model for which predict(model, newdata = data.frame(x = ...)) returns one numeric value for each row of newdata, e.g. function(data) lm(y ~ factor(x), data = data) for the mean of each date, or function(data) mgcv::gam(y ~ s(x), data = data) for a smoothed pattern. Before the function is called, time series with dates are shifted to start on the same day of the year in the year 1970, so that time series of different years overlap. This aligns the time series by the year. For another cycle, e.g. cycle_length = 'day', use numeric time indices in the units of the cycle, which are not shifted.

Most of the time to create the temporal patterns is used to fit these models. With thousands of time series, function(data) mgcv::bam(y ~ s(x), data = data, discrete = TRUE) gives nearly the same patterns as mgcv::gam and is about two times faster.

The models that resampling_fun returns, one for each label and band, are only used to create the temporal patterns: predict uses the patterns and not these models. By default the model keeps the patterns and the root mean squared error of each fitted model, which print shows, and not the fitted models. A fitted model usually contains the data it was fitted to, i.e. the observations of all time series of a label. Without the fitted models the model is much smaller, e.g. to save it to a file or to send it to other processes. With keep_models = TRUE the fitted models are kept in smooth_models, e.g. to plot them or to see their summary: summary(m$smooth_models[[label]][[band]]).

The temporal patterns of different labels can have a different number of observations, e.g. if the time series of the labels are from different years and their dates are one day apart after the shift. The TWDTW distance is not divided by the number of observations of the pattern, so a pattern with fewer observations tends to be nearer. With resampling_freq all patterns have observations at the same interval.

Creating the model does not calculate TWDTW distances. The distances between new time series and the temporal patterns are calculated by predict.twdtw_knn in a single call to twdtw_nearest.

twdtw_knn is a generic function. Other packages can add methods for their classes of time series, e.g. for the pixels of a satellite image data cube.

Value

An object of class twdtw_knn, which is a list with:

call

The call of the function.

smooth_models

The models returned by resampling_fun, if keep_models is TRUE: a list with one element for each label, which is a list with the model of each band. Otherwise NULL.

rmse

The root mean squared error of the models returned by resampling_fun: a matrix with one row for each band and one column for each label, or NULL if the model keeps all time series.

data

A data.frame with one row for each temporal pattern and the columns label and observations. The latter is a list of data.frames with the column time and one column for each band.

twdtw_args

A list with the arguments of the TWDTW distance: time_weight, cycle_length, time_scale, origin, and max_elapsed.

References

Maus, V., Camara, G., Cartaxo, R., Sanchez, A., Ramos, F. M., & de Queiroz, G. R. (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-3739. doi:10.1109/JSTARS.2016.2517118

See Also

predict.twdtw_knn, twdtw_nearest, twdtw

Examples


# Temporal patterns of 5 land use classes and satellite image time series of 999 pixels
ts_y <- readRDS(system.file("sits/modis_mod13q1_patterns.rds", package = "twdtw"))
ts_x <- readRDS(system.file("sits/modis_mod13q1_999ts.rds", package = "twdtw"))

# Create a model from a list of labelled time series
m <- twdtw_knn(x = ts_y$observations,
               y = ts_y$label,
               cycle_length = 'year',
               time_scale = 'day',
               time_weight = c(steepness = 0.1, midpoint = 50))

m

# Classify the time series of the pixels
lu <- predict(m, newdata = ts_x$observations)

head(lu)

table(lu$prediction)

# Use the first 300 classified time series as samples and create a model
# with one temporal pattern for each label: the mean of the samples on each date
samples <- ts_x$observations[1:300]
labels <- lu$prediction[1:300]

m <- twdtw_knn(x = samples,
               y = labels,
               resampling_fun = function(data) lm(y ~ factor(x), data = data),
               cycle_length = 'year',
               time_scale = 'day',
               time_weight = c(steepness = 0.1, midpoint = 50))

m

# A model without 'resampling_fun' keeps all samples as temporal patterns
# and can be classified with more than one nearest neighbour
m <- twdtw_knn(x = samples,
               y = labels,
               cycle_length = 'year',
               time_scale = 'day',
               time_weight = c(steepness = 0.1, midpoint = 50))

lu <- predict(m, newdata = ts_x$observations[301:310], k = 5)

lu


Classify time series of a given class with a TWDTW k-nearest neighbour model

Description

This generic function is called by predict.twdtw_knn to classify the time series in newdata, and the method is chosen by the class of newdata. It is exported for packages that add methods for their classes of time series, e.g. the pixels of a satellite image data cube. To classify time series call predict.

Usage

twdtw_knn_predict(newdata, object, ...)

## S3 method for class 'array'
twdtw_knn_predict(
  newdata,
  object,
  k = 1,
  vote = c("majority", "weighted"),
  type = c("class", "prob", "neighbors"),
  time = NULL,
  ...
)

## S3 method for class 'data.frame'
twdtw_knn_predict(
  newdata,
  object,
  k = 1,
  vote = c("majority", "weighted"),
  type = c("class", "prob", "neighbors"),
  ...
)

## S3 method for class 'list'
twdtw_knn_predict(
  newdata,
  object,
  k = 1,
  vote = c("majority", "weighted"),
  type = c("class", "prob", "neighbors"),
  index_column = "time",
  ...
)

Arguments

newdata

The time series to classify. The methods of this package are for a list of data.frames or matrices, a data.frame with one row for each time series and one column for each band and date, and a numeric array with the dimensions series, time, and band, see twdtw_knn.

object

A model of class twdtw_knn, created by twdtw_knn.

...

Arguments passed by predict.twdtw_knn to the methods: k, vote, type, and the arguments of the TWDTW distance that replace the arguments of the model. time is passed only if it is given to predict.

k

The number of nearest temporal patterns used for each time series. An integer between one and the number of temporal patterns of the model. Defaults to 1, i.e. only the nearest pattern is used.

vote

The weight of the vote of each of the k nearest patterns. Either "majority" (default), where each pattern has one vote, or "weighted", where each pattern votes with the weight 1/distance. It can change the result only if k is larger than one. See details.

type

What the function returns for each time series. One of:

  • "class" (default): the predicted label, i.e. the label with the most votes, and the distance to the nearest pattern with this label.

  • "prob": a score from 0 to 1 for each label of the model, i.e. the share of the votes that the label gets.

  • "neighbors": the labels and the distances of the k nearest patterns, without a vote.

See details.

time

A vector with the dates of the time dimension of an array newdata. Its length must be equal to dim(newdata)[2]. It is only used if newdata is an array.

index_column

The column name or the column position of the time index of the time series in a list. Defaults to "time".

Details

predict chooses its method by the class of the model, which is its first argument. This function chooses its method by the class of the time series, so that a package can add a method for its class without changing the model.

A method for another class usually converts newdata to a numeric array with the dimensions series, time, and band, calls twdtw_knn_predict with this array, the dates of its time dimension in time, and the other arguments in ..., and then arranges the rows of the result in the form of its class, see the examples. The method for an array passes the array to twdtw_nearest as it is, so that missing values remain missing.

Value

The methods of this package return a data.frame with one row for each time series in newdata, in the same order, see predict.twdtw_knn.

See Also

predict.twdtw_knn, twdtw_knn, twdtw_nearest

Examples


# Temporal patterns of 5 land use classes and satellite image time series of 999 pixels
ts_y <- readRDS(system.file("sits/modis_mod13q1_patterns.rds", package = "twdtw"))
ts_x <- readRDS(system.file("sits/modis_mod13q1_999ts.rds", package = "twdtw"))

m <- twdtw_knn(x = ts_y$observations,
               y = ts_y$label,
               cycle_length = 'year',
               time_scale = 'day',
               time_weight = c(steepness = 0.1, midpoint = 50))

# A class of time series that keeps the values of all time series in an array
# and the dates of the observations
bands <- c("EVI", "NDVI", "RED", "BLUE", "NIR", "MIR")
values <- sapply(ts_x$observations, function(ts) as.matrix(ts[bands]), simplify = "array")
pixels <- structure(list(values = aperm(values, c(3, 1, 2)),
                         dates = ts_x$observations[[1]]$time),
                    class = "pixel_series")

# A method for this class: pass the array and its dates to the method for arrays
twdtw_knn_predict.pixel_series <- function(newdata, object, ...) {
  twdtw_knn_predict(newdata$values, object, time = newdata$dates, ...)
}

# predict() now classifies objects of this class
head(predict(m, newdata = pixels, k = 2, type = "neighbors"))


Find the k-nearest neighbours of time series using TWDTW

Description

This function calculates the Time-Weighted Dynamic Time Warping (TWDTW) distance between each time series in x and each temporal pattern in y, and returns for each time series the k patterns with the lowest distance.

Usage

twdtw_nearest(
  x,
  y,
  time,
  time_weight,
  cycle_length,
  time_scale = NULL,
  k = 1,
  origin = NULL,
  index_column = "time",
  max_elapsed = Inf
)

Arguments

x

A numeric array with three dimensions: series, time, and band, i.e. x[i, , ] has the observations of the i-th time series with one row for each date and one column for each band. All time series share the same dates, missing observations are NA.

y

A list of temporal patterns (references). Each pattern is either a data.frame or a matrix with one row for each observation, a column with the time index, and one column for each band in x. The patterns can have different number of observations.

time

A vector with the dates of the time dimension of x. Its length must be equal to dim(x)[2].

time_weight

A numeric vector with length two (steepness and midpoint of logistic weight) or a function. See details in twdtw. A function is slower than the logistic weight, see details.

cycle_length

The length of the cycle. Can be a numeric value or a string specifying the units ('year', 'month', 'day', 'hour', 'minute', 'second'). When numeric, the cycle length is in the same units as time_scale. When a string, it specifies the time unit of the cycle.

time_scale

Specifies the time scale for the conversion. Must be one of 'year', 'month', 'day', 'hour', 'minute', 'second'. When cycle_length is a string, time_scale changes the unit in which the result is expressed. When cycle_length is numeric, time_scale is used to compute the elapsed time in seconds.

k

The number of nearest neighbours. Defaults to 1, i.e. only the nearest pattern.

origin

For numeric cycle_length, the origin must be specified. This is the point from which the elapsed time is computed. Must be of the same class as time.

index_column

The column name or the column position of the time index in the patterns in y. Defaults to "time".

max_elapsed

Numeric value constraining the TWDTW calculation to the lower band given by a maximum elapsed time. Defaults to Inf.

Details

The distances are the same as the distances calculated with twdtw for each pair of time series and pattern. However, all time series are processed in a single call to the 'Fortran' routines and only the distances are calculated. This is much faster than calling twdtw for each pair and suitable for a large number of time series, e.g. the pixels of satellite images. The matches and the internal matrices are not available, use twdtw for that. The function returns the position of the nearest patterns and has no labels. To classify time series with the labels of their nearest patterns, create a model with twdtw_knn, which calls this function.

The band names of x, i.e. dimnames(x)[[3]], are matched to the column names of the patterns in y. If either of them has no names, the bands are matched by their position.

Time indices of class Date or POSIXct, or character strings, are converted to the units of the cycle using date_to_numeric_cycle. Numeric time indices are assumed to be already in the units of the cycle and are not converted. This applies to both time and the time index of each pattern in y.

An observation with a missing value in any band is removed from the respective time series or pattern. A time series without any complete observation has NA for all neighbours. Patterns must have at least one complete observation.

Patterns with the same distance to a time series are returned in the order of their position in y.

If time_weight is a function, it is called once for each temporal pattern and block of time series and not for each pair of observations. The function receives two numeric vectors of the same length, the Euclidean distance and the elapsed time of the pairs of observations, and must return a numeric vector with their time-weighted distance. This requires a vectorised function, i.e. a function that returns for vectors the same values as for one distance and one elapsed time, for example function(dist, el) dist + 0.1 * el. Use ifelse instead of if for conditions. The function is tested with a sample of distances and elapsed times. If it is not vectorised, twdtw is called for each pair of time series and pattern, which is much slower. The logistic time weight given by its two parameters is the fastest option.

Value

A list with two matrices with one row for each time series in x and k columns ordered from the nearest to the farthest neighbour:

index

The position in y of the nearest patterns.

distance

The TWDTW distance to the nearest patterns.

References

Maus, V., Camara, G., Cartaxo, R., Sanchez, A., Ramos, F. M., & de Queiroz, G. R. (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-3739. doi:10.1109/JSTARS.2016.2517118

See Also

twdtw_knn, twdtw

Examples


# Satellite image time series of 999 pixels and temporal patterns of 5 land use classes
ts_x <- readRDS(system.file("sits/modis_mod13q1_999ts.rds", package = "twdtw"))
ts_y <- readRDS(system.file("sits/modis_mod13q1_patterns.rds", package = "twdtw"))

# Stack the time series into an array with dimensions: series, time, and band
bands <- c("EVI", "NDVI", "RED", "BLUE", "NIR", "MIR")
x <- sapply(ts_x$observations, function(ts) as.matrix(ts[bands]), simplify = "array")
x <- aperm(x, c(3, 1, 2))
dim(x)

# Find the nearest pattern for each time series
knn <- twdtw_nearest(x = x,
                     y = ts_y$observations,
                     time = ts_x$observations[[1]]$time,
                     cycle_length = 'year',
                     time_scale = 'day',
                     time_weight = c(steepness = 0.1, midpoint = 50))

table(ts_y$label[knn$index[, 1]])

# Find the two nearest patterns and their distances
knn <- twdtw_nearest(x = x,
                     y = ts_y$observations,
                     time = ts_x$observations[[1]]$time,
                     cycle_length = 'year',
                     time_scale = 'day',
                     time_weight = c(steepness = 0.1, midpoint = 50),
                     k = 2)

head(knn$index)
head(knn$distance)