| 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 |
| 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 |
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 |
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 |
newdata |
The time series to classify, in one of the three forms of the time series of
|
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 |
type |
What the function returns for each time series. One of:
See details. |
time |
A vector with the dates of the time dimension of an array |
... |
Arguments of the TWDTW distance that replace the arguments of the model:
|
Details
A time series is classified in three steps, which are set by k, vote,
and type:
The
ktemporal patterns of the model with the lowest TWDTW distance to the time series are found.Each of these patterns votes for its label. With
vote = "majority"each pattern has one vote. Withvote = "weighted"each pattern votes with the weight 1/distance, so that a pattern twice as far has half the weight.-
typesets what is returned: the label with the most votes ("class"), the share of the votes of each label ("prob"), or theknearest 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:
With
vote = "majority", soybean has one vote and maize has two.type = "class"returns maize and the distance 4, andtype = "prob"returns 1/3 for soybean and 2/3 for maize.With
vote = "weighted", soybean has the vote 1 and maize has the votes 1/4 + 1/4.type = "class"returns soybean and the distance 1, andtype = "prob"returns 2/3 for soybean and 1/3 for maize.-
type = "neighbors"returns the three labels and the three distances, with anyvote.
The three types of result in more detail:
-
"class": if several labels have the same number of votes, the prediction is the one of them whose pattern is nearest. The distance is the TWDTW distance to the nearest pattern with the predicted label. -
"prob": the share of a label is its votes divided by the votes of allkpatterns. The shares of a time series sum to one, a label without a pattern among theknearest has the share zero, and the label oftype = "class"always has the largest share. Withk = 1the share is one for the label of the nearest pattern and zero for the other labels. The name follows other classifiers in R, wheretype = "prob"returns a score for each class. -
"neighbors": the patterns are ordered from the nearest to the farthest. This is the result to use for another way of combining the labels and the distances.
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" |
|
"prob" |
One column for each label of the model, named with the label, with its share of the votes. |
"neighbors" |
|
The predictions are factors with the labels of the model as levels, in alphabetical order.
See Also
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 |
... |
Arguments passed to |
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 |
... |
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 |
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:
twis the time-weight functiondist_{i,j}is the Euclidean distance between the i-th element ofxand the j-th element ofyin a multi-dimensional spaceel_{i,j}is the time elapsed between the i-th element ofxand the j-th element ofy\alphaand\betaare the steepness and midpoint of the logistic function, respectively
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 |
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. |
time_scale |
The time scale of the observations, e.g. |
... |
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 |
resampling_fun |
A function that creates one temporal pattern for each label from all time series
with this label. If |
resampling_freq |
The time between the observations of the temporal patterns created with
|
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 |
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 |
Details
The time series in x can have three forms:
A list of data.frames or matrices. Each of them is a time series with one row for each observation, a column with the time index, and one column for each band, as the time series of
twdtw. The time series can have different dates and different number of observations.A data.frame with one row for each time series and one column for each band and date, named with the band and the date separated by a period, e.g.
EVI.2011-09-14. Names with the date first, e.g.2011-09-14.EVI, and dates written with periods, e.g.EVI.2011.09.14, are also recognised. Columns with only the date in their name are the observations of a single band. Columns with other names are not used.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. The dates of the time dimension are given intime.
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 |
rmse |
The root mean squared error of the models returned by |
data |
A data.frame with one row for each temporal pattern and the columns |
twdtw_args |
A list with the arguments of the TWDTW distance: |
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 |
object |
A model of class |
... |
Arguments passed by |
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 |
type |
What the function returns for each time series. One of:
See details. |
time |
A vector with the dates of the time dimension of 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. |
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 |
time |
A vector with the dates of the time dimension of |
time_weight |
A numeric vector with length two (steepness and midpoint of logistic weight) or a function.
See details in |
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 |
index_column |
The column name or the column position of the time index in the patterns in |
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 |
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
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)