diff --git a/.Rbuildignore b/.Rbuildignore index 65a7f18..ab39738 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -1,3 +1,5 @@ +^Meta$ +^doc$ ^.*\.Rproj$ ^\.Rproj\.user$ ^\vignettes$ diff --git a/.gitignore b/.gitignore index eed9ea3..6f490b7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ +Meta +doc # History files .Rhistory @@ -22,4 +24,3 @@ tardis.f *.o *.so Makefile - diff --git a/NAMESPACE b/NAMESPACE index 61ae7b3..84da8b4 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -81,6 +81,7 @@ import(rgdal) import(snow) import(zoo) importFrom(RColorBrewer,brewer.pal) +importFrom(Rdpack,reprompt) importFrom(caret,createDataPartition) importFrom(dtw,asymmetric) importFrom(dtw,rabinerJuangStepPattern) diff --git a/R/class-crossValidation.R b/R/class-crossValidation.R index 5995e9a..297b73a 100644 --- a/R/class-crossValidation.R +++ b/R/class-crossValidation.R @@ -38,6 +38,11 @@ #' \item{\code{accuracy}:}{A list with the accuracy and other TWDTW information for each #' data partitions.} #' } +#' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} #' #' @examples #' \dontrun{ diff --git a/R/class-twdtwAssessment.R b/R/class-twdtwAssessment.R index 556af91..c935454 100644 --- a/R/class-twdtwAssessment.R +++ b/R/class-twdtwAssessment.R @@ -42,6 +42,11 @@ #' If the twdtwRaster is unprojected (longitude/latitude) the estimated area is the sum of the approximate #' surface area in km2 of each cell (pixel). If the twdtwRaster is projected the estimated area is calculated #' using the the pixel resolution in the map unit. +#' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} #' NULL setClass( diff --git a/R/class-twdtwMatches.R b/R/class-twdtwMatches.R index 2c266b2..61f23e2 100644 --- a/R/class-twdtwMatches.R +++ b/R/class-twdtwMatches.R @@ -67,6 +67,11 @@ #' \code{\link[dtwSat]{twdtwTimeSeries-class}}, and #' \code{\link[dtwSat]{twdtwRaster-class}} #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' ts = twdtwTimeSeries(timeseries=MOD13Q1.ts.list) #' patterns = twdtwTimeSeries(timeseries=MOD13Q1.patterns.list) diff --git a/R/class-twdtwRaster.R b/R/class-twdtwRaster.R index 71f69a4..8fd9bd8 100644 --- a/R/class-twdtwRaster.R +++ b/R/class-twdtwRaster.R @@ -76,6 +76,11 @@ #' \code{\link[dtwSat]{twdtwMatches-class}}, and #' \code{\link[dtwSat]{twdtwTimeSeries-class}} #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' # Creating a new object of class twdtwTimeSeries #' evi = brick(system.file("lucc_MT/data/evi.tif", package="dtwSat")) diff --git a/R/class-twdtwTimeSeries.R b/R/class-twdtwTimeSeries.R index fe21d1b..1b5a8fb 100644 --- a/R/class-twdtwTimeSeries.R +++ b/R/class-twdtwTimeSeries.R @@ -37,6 +37,11 @@ #' \code{\link[dtwSat]{getTimeSeries}}, and #' \code{\link[dtwSat]{twdtwApply}} #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' # Creating a new object of class twdtwTimeSeries #' ptt = new("twdtwTimeSeries", timeseries = MOD13Q1.patterns.list, diff --git a/R/createPatterns.R b/R/createPatterns.R index ee04d0f..f737743 100644 --- a/R/createPatterns.R +++ b/R/createPatterns.R @@ -56,6 +56,11 @@ #' \code{\link[dtwSat]{getTimeSeries}}, and #' \code{\link[dtwSat]{twdtwApply}} #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @export setGeneric("createPatterns", function(x, from=NULL, to=NULL, freq=1, attr=NULL, split=TRUE, formula, ...) standardGeneric("createPatterns")) diff --git a/R/data.R b/R/data.R index 6fe9802..af40ca9 100644 --- a/R/data.R +++ b/R/data.R @@ -22,7 +22,8 @@ #' #' @description This dataset has a list of patterns with the phenological cycle of: Soybean, #' Cotton, and Maize. These time series are based on the MODIS product -#' MOD13Q1 250 m 16 days [1]. The patterns were built from ground truth samples of each +#' MOD13Q1 250 m 16 days \insertCite{Didan:2015}{dtwSat}. The patterns were built +#' from ground truth samples of each #' crop using Generalized Additive Models (GAM), see \link[dtwSat]{createPatterns}. #' #' @docType data @@ -36,13 +37,15 @@ #' \link[dtwSat]{MOD13Q1.ts.list}, and #' \link[dtwSat]{createPatterns}. #' -#' @seealso MOD13Q1 documentation: See -#' \url{https://lpdaac.usgs.gov/dataset_discovery/modis/modis_products_table/mod13q1_v006}. +#' @seealso For details about MOD13Q1 see \insertCite{Didan:2015}{dtwSat}. #' #' @references -#' [1] Friedl MA, Sulla-Menashe D, Tan B, Schneider A, Ramankutty N, Sibley A, Huang X. (2010). -#' MODIS Collection 5 global land cover: Algorithm refinements and characterization of new -#' datasets. Remote Sensing of Environment, 114(1), 168 182. +#' \insertAllCited{} +#' +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} + #' "MOD13Q1.patterns.list" @@ -51,7 +54,8 @@ #' @author Victor Maus, \email{vwmaus1@@gmail.com} #' #' @description This dataset has a time series based on the -#' MODIS product MOD13Q1 250 m 16 days [1]. It is an irregularly sampled time series +#' MODIS product MOD13Q1 250 m 16 days \insertCite{Didan:2015}{dtwSat}. +#' It is an irregularly sampled time series #' using the real date of each pixel from ''2009-08-05'' to ''2013-07-31''. #' #' @docType data @@ -64,13 +68,15 @@ #' \link[dtwSat]{MOD13Q1.patterns.list}. #' #' -#' @seealso MOD13Q1 documentation: -#' \url{https://lpdaac.usgs.gov/dataset_discovery/modis/modis_products_table/mod13q1_v006}. +#' @seealso For details about MOD13Q1 see \insertCite{Didan:2015}{dtwSat}. #' #' @references -#' [1] Friedl MA, Sulla-Menashe D, Tan B, Schneider A, Ramankutty N, Sibley A, Huang X. (2010). -#' MODIS Collection 5 global land cover: Algorithm refinements and characterization of new -#' datasets. Remote Sensing of Environment, 114(1), 168 182. +#' \insertAllCited{} +#' +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} + #' "MOD13Q1.ts" @@ -93,7 +99,8 @@ #' @author Victor Maus, \email{vwmaus1@@gmail.com} #' #' @description This dataset has a list of time series based on the -#' MODIS product MOD13Q1 250 m 16 days [1]. It is an irregularly sampled time series +#' MODIS product MOD13Q1 250 m 16 days \insertCite{Didan:2015}{dtwSat}. +#' It is an irregularly sampled time series #' using the real date of each pixel from ''2009-08-05'' to ''2013-07-31''. #' #' @docType data @@ -106,36 +113,39 @@ #' \link[dtwSat]{MOD13Q1.patterns.list}. #' #' -#' @seealso MOD13Q1 documentation: -#' \url{https://lpdaac.usgs.gov/dataset_discovery/modis/modis_products_table/mod13q1_v006}. +#' @seealso For details about MOD13Q1 see \insertCite{Didan:2015}{dtwSat}. #' #' @references -#' [1] Friedl MA, Sulla-Menashe D, Tan B, Schneider A, Ramankutty N, Sibley A, Huang X. (2010). -#' MODIS Collection 5 global land cover: Algorithm refinements and characterization of new -#' datasets. Remote Sensing of Environment, 114(1), 168 182. +#' \insertAllCited{} +#' +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} + #' "MOD13Q1.ts.list" - #' @title Data: Pattern time series #' @author Victor Maus, \email{vwmaus1@@gmail.com} #' #' @description This dataset has a list of patterns with the phenological cycle of: Water, #' Cotton-Fallow, Forest, Low vegetation, Pasture, Soybean-Cotton, Soybean-Maize, Soybean-Millet, #' Soybean-Sunflower, and Wetland. These time series are based on the MODIS product -#' MOD13Q1 250 m 16 days [1]. The patterns were built from ground truth samples of each +#' MOD13Q1 250 m 16 days \insertCite{Didan:2015}{dtwSat}. +#' The patterns were built from ground truth samples of each #' crop using Generalized Additive Models (GAM), see \link[dtwSat]{createPatterns}. #' #' @docType data #' @format A \link[dtwSat]{twdtwTimeSeries} object. #' -#' @seealso MOD13Q1 documentation: See -#' \url{https://lpdaac.usgs.gov/dataset_discovery/modis/modis_products_table/mod13q1_v006}. +#' @seealso For details about MOD13Q1 see \insertCite{Didan:2015}{dtwSat}. #' #' @references -#' [1] Friedl MA, Sulla-Menashe D, Tan B, Schneider A, Ramankutty N, Sibley A, Huang X. (2010). -#' MODIS Collection 5 global land cover: Algorithm refinements and characterization of new -#' datasets. Remote Sensing of Environment, 114(1), 168 182. +#' \insertAllCited{} +#' +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} #' "MOD13Q1.MT.yearly.patterns" diff --git a/R/dwtSat.R b/R/dwtSat.R index 37b5733..d352d15 100644 --- a/R/dwtSat.R +++ b/R/dwtSat.R @@ -17,7 +17,8 @@ #' @author Victor Maus, \email{vwmaus1@@gmail.com} #' #' @description Provides an implementation of the Time-Weighted Dynamic Time Warping -#' (TWDTW) method for land use and land cover mapping using satellite image time series [1]. +#' (TWDTW) method for land use and land cover mapping using satellite image time series +#' \insertCite{Maus:2016,Maus:2019}{dtwSat}. #' TWDTW is based on the Dynamic Time Warping technique and has achieved high accuracy #' for land use and land cover classification using satellite data. The method is based #' on comparing unclassified satellite image time series with a set of known temporal @@ -26,12 +27,8 @@ #' for satellite datasets, visualize the results of the time series analysis, produce #' land cover maps, and create temporal plots for land cover change analysis. #' -#' #' @references -#' [1] Maus V, Camara G, Cartaxo R, Sanchez A, Ramos FM, de Queiroz, GR. -#' (2016). A Time-Weighted Dynamic Time Warping method for land use and land cover -#' mapping. Selected Topics in Applied Earth Observations and Remote Sensing, -#' IEEE Journal of, vol.PP, no.99, pp.1-11. +#' \insertAllCited{} #' #' @seealso \code{\link[dtwSat]{twdtwApply}} #' diff --git a/R/getInternals.R b/R/getInternals.R index cb6cc58..95a835f 100644 --- a/R/getInternals.R +++ b/R/getInternals.R @@ -42,7 +42,13 @@ setGeneric("getMatches", function(object, timeseries.labels=NULL, patterns.label #' getInternals(mat) #' #' @return a list with TWDTW results or an object \code{\link[dtwSat]{twdtwTimeSeries-class}}. -#' +#' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' +#' NULL #' @aliases getAlignments diff --git a/R/getTimeSeries.R b/R/getTimeSeries.R index bb6bec5..09ecac0 100644 --- a/R/getTimeSeries.R +++ b/R/getTimeSeries.R @@ -51,6 +51,11 @@ setGeneric("getPatterns", function(object, ...) standardGeneric("getPatterns")) #' #' @return a list with TWDTW results or an object \code{\link[dtwSat]{twdtwTimeSeries-class}}. #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' # Getting time series from objects of class twdtwTimeSeries #' ts = twdtwTimeSeries(MOD13Q1.ts.list) diff --git a/R/linearWeight.R b/R/linearWeight.R index 0f12f52..3c8bc53 100644 --- a/R/linearWeight.R +++ b/R/linearWeight.R @@ -29,17 +29,15 @@ #' can be passed to \code{\link[dtwSat]{twdtwApply}} through the argument \code{weight.fun}. #' This will add a time-weight to the dynamic time warping analysis. The time weight #' creates a global constraint useful to analyse time series with phenological cycles -#' of vegetation that are usually bound to seasons. In previous studies by [1] the -#' logistic weight had better results than the linear for land cover classification. -#' See [1] for details about the method. +#' of vegetation that are usually bound to seasons. In previous studies by +#' \insertCite{Maus:2016;textual}{dtwSat} the logistic weight had better results than the +#' linear for land cover classification. See \insertCite{Maus:2016;textual}{dtwSat} and +#' \insertCite{Maus:2019;textual}{dtwSat}. #' #' @seealso \code{\link[dtwSat]{twdtwApply}} #' #' @references -#' [1] Maus V, Camara G, Cartaxo R, Sanchez A, Ramos FM, de Queiroz, GR. -#' (2016). A Time-Weighted Dynamic Time Warping method for land use and land cover -#' mapping. Selected Topics in Applied Earth Observations and Remote Sensing, -#' IEEE Journal of, vol.PP, no.99, pp.1-11. +#' \insertAllCited{} #' #' @examples #' lin_fun = linearWeight(a=0.1) diff --git a/R/logisticWeight.R b/R/logisticWeight.R index 7da480c..2a0b247 100644 --- a/R/logisticWeight.R +++ b/R/logisticWeight.R @@ -29,17 +29,15 @@ #' can be passed to \code{\link[dtwSat]{twdtwApply}} through the argument \code{weight.fun}. #' This will add a time-weight to the dynamic time warping analysis. The time weight #' creates a global constraint useful to analyse time series with phenological cycles -#' of vegetation that are usually bound to seasons. In previous studies by [1] the -#' logistic weight had better results than the linear for land cover classification. -#' See [1] for details about the method. +#' of vegetation that are usually bound to seasons. In previous studies by +#' \insertCite{Maus:2016;textual}{dtwSat} the logistic weight had better results than the +#' linear for land cover classification. See \insertCite{Maus:2016;textual}{dtwSat} and +#' \insertCite{Maus:2019;textual}{dtwSat}. #' #' @seealso \code{\link[dtwSat]{twdtwApply}} #' #' @references -#' [1] Maus V, Camara G, Cartaxo R, Sanchez A, Ramos FM, de Queiroz, GR. -#' (2016). A Time-Weighted Dynamic Time Warping method for land use and land cover -#' mapping. Selected Topics in Applied Earth Observations and Remote Sensing, -#' IEEE Journal of, vol.PP, no.99, pp.1-11. +#' \insertAllCited{} #' #' @examples #' log_fun = logisticWeight(alpha=-0.1, beta=100) diff --git a/R/miscellaneous.R b/R/miscellaneous.R index 50a45ee..30488f8 100644 --- a/R/miscellaneous.R +++ b/R/miscellaneous.R @@ -15,6 +15,11 @@ #' #' @seealso \link[dtwSat]{shiftDates} #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' year = c(2000, 2001) #' doy = c(366, 365) @@ -48,11 +53,22 @@ getDatesFromDOY = function(year, doy){ #' #' @return An object of the same class as the input \code{object}. #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @export setGeneric("shiftDates", function(object, year=NULL) standardGeneric("shiftDates")) #' @rdname shiftDates #' @aliases shiftDates-twdtwTimeSeries +#' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' patt = twdtwTimeSeries(MOD13Q1.patterns.list) #' npatt = shiftDates(patt, year=2005) diff --git a/R/plotAccuracy.R b/R/plotAccuracy.R index b527b11..336d208 100644 --- a/R/plotAccuracy.R +++ b/R/plotAccuracy.R @@ -28,6 +28,11 @@ #' @seealso #' \code{\link[dtwSat]{twdtwAssessment}} and \code{\link[dtwSat]{twdtwAssess}} #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' \dontrun{ #' diff --git a/R/plotAdjustedArea.R b/R/plotAdjustedArea.R index c7dc538..01057e4 100644 --- a/R/plotAdjustedArea.R +++ b/R/plotAdjustedArea.R @@ -10,6 +10,11 @@ #' @seealso #' \code{\link[dtwSat]{twdtwAssessment}} and \code{\link[dtwSat]{twdtwAssess}} #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' \dontrun{ #' diff --git a/R/plotAlignments.R b/R/plotAlignments.R index 46fa058..aa172fe 100644 --- a/R/plotAlignments.R +++ b/R/plotAlignments.R @@ -40,6 +40,11 @@ #' \code{\link[dtwSat]{plotMatches}}, and #' \code{\link[dtwSat]{plotClassification}}. #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' log_fun = logisticWeight(-0.1, 100) #' ts = twdtwTimeSeries(MOD13Q1.ts.list) diff --git a/R/plotArea.R b/R/plotArea.R index e39d8f1..9b904ff 100644 --- a/R/plotArea.R +++ b/R/plotArea.R @@ -45,6 +45,11 @@ #' \code{\link[dtwSat]{plotChanges}}, and #' \code{\link[dtwSat]{plotDistance}}. #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' \dontrun{ #' diff --git a/R/plotChanges.R b/R/plotChanges.R index df478c8..eb21d4f 100644 --- a/R/plotChanges.R +++ b/R/plotChanges.R @@ -43,6 +43,11 @@ #' \code{\link[dtwSat]{plotMaps}}, and #' \code{\link[dtwSat]{plotDistance}}. #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' \dontrun{ #' # Run TWDTW analysis for raster time series diff --git a/R/plotClassification.R b/R/plotClassification.R index 3f92597..26ba5c7 100644 --- a/R/plotClassification.R +++ b/R/plotClassification.R @@ -41,6 +41,11 @@ #' \code{\link[dtwSat]{plotMatches}}, and #' \code{\link[dtwSat]{plotCostMatrix}}. #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' log_fun = logisticWeight(-0.1, 100) #' ts = twdtwTimeSeries(MOD13Q1.ts.list) diff --git a/R/plotCostMatrix.R b/R/plotCostMatrix.R index d36a41c..4f85fcd 100644 --- a/R/plotCostMatrix.R +++ b/R/plotCostMatrix.R @@ -39,6 +39,11 @@ #' \code{\link[dtwSat]{plotMatches}}, and #' \code{\link[dtwSat]{plotClassification}}. #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' log_fun = logisticWeight(-0.1, 100) #' ts = twdtwTimeSeries(MOD13Q1.ts.list) diff --git a/R/plotDistance.R b/R/plotDistance.R index b5908b8..0fe7136 100644 --- a/R/plotDistance.R +++ b/R/plotDistance.R @@ -36,7 +36,12 @@ #' \code{\link[dtwSat]{plotArea}}, #' \code{\link[dtwSat]{plotChanges}}, and #' \code{\link[dtwSat]{plotDistance}}. -#' +#' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' \dontrun{ #' # Run TWDTW analysis for raster time series diff --git a/R/plotMapSamples.R b/R/plotMapSamples.R index a90658b..dbf5aee 100644 --- a/R/plotMapSamples.R +++ b/R/plotMapSamples.R @@ -16,6 +16,11 @@ #' \code{\link[dtwSat]{plotAccuracy}}, and #' \code{\link[dtwSat]{plotAdjustedArea}}. #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @example examples/test_twdtw_raster_analysis.R #' @export plotMapSamples = function(x, samples="all", ...){ diff --git a/R/plotMaps.R b/R/plotMaps.R index 00e4408..9c69dc8 100644 --- a/R/plotMaps.R +++ b/R/plotMaps.R @@ -43,6 +43,11 @@ #' \code{\link[dtwSat]{plotChanges}}, and #' \code{\link[dtwSat]{plotDistance}}. #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' \dontrun{ #' # Run TWDTW analysis for raster time series diff --git a/R/plotMatches.R b/R/plotMatches.R index 1da3982..d40e2e1 100644 --- a/R/plotMatches.R +++ b/R/plotMatches.R @@ -44,6 +44,11 @@ #' \code{\link[dtwSat]{plotAlignments}}, and #' \code{\link[dtwSat]{plotClassification}}. #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' log_fun = logisticWeight(-0.1, 100) #' ts = twdtwTimeSeries(MOD13Q1.ts.list) diff --git a/R/plotPaths.R b/R/plotPaths.R index 5eebaa3..7c4e84d 100644 --- a/R/plotPaths.R +++ b/R/plotPaths.R @@ -38,6 +38,11 @@ #' \code{\link[dtwSat]{plotMatches}}, and #' \code{\link[dtwSat]{plotClassification}}. #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' log_fun = logisticWeight(-0.1, 100) #' ts = twdtwTimeSeries(MOD13Q1.ts.list) diff --git a/R/plotPatterns.R b/R/plotPatterns.R index 96f8b5f..5bb6bd6 100644 --- a/R/plotPatterns.R +++ b/R/plotPatterns.R @@ -34,6 +34,11 @@ #' \code{\link[dtwSat]{twdtwTimeSeries-class}} and #' \code{\link[dtwSat]{plotTimeSeries}} #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' patt = twdtwTimeSeries(MOD13Q1.patterns.list) #' plotPatterns(patt) diff --git a/R/plotTimeSeries.R b/R/plotTimeSeries.R index cbbf44c..f8f05cf 100644 --- a/R/plotTimeSeries.R +++ b/R/plotTimeSeries.R @@ -32,6 +32,11 @@ #' \code{\link[dtwSat]{twdtwTimeSeries-class}} and #' \code{\link[dtwSat]{plotPatterns}} #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' ts = twdtwTimeSeries(MOD13Q1.ts.list) #' plotTimeSeries(ts) diff --git a/R/subset.R b/R/subset.R index 4979381..d59521b 100644 --- a/R/subset.R +++ b/R/subset.R @@ -38,6 +38,11 @@ #' \code{\link[dtwSat]{twdtwMatches-class}} #' #' @return An object of class twdtw*. +#' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} #' #' @examples #' # Getting time series from objects of class twdtwTimeSeries diff --git a/R/twdtwApply.R b/R/twdtwApply.R index 6200ae4..c1532d2 100644 --- a/R/twdtwApply.R +++ b/R/twdtwApply.R @@ -19,7 +19,7 @@ #' #' @description This function performs a multidimensional Time-Weighted DTW #' analysis and retrieves the matches between the temporal patterns and -#' a set of time series [1]. +#' a set of time series \insertCite{Maus:2019}{dtwSat}. #' #' @inheritParams twdtwClassify #' @@ -49,7 +49,8 @@ #' Default is ''Euclidean'' see \code{\link[proxy]{dist}} in package #' \pkg{proxy}. #' -#' @param step.matrix See \code{\link[dtw]{stepPattern}} in package \pkg{dtw} [2]. +#' @param step.matrix See \code{\link[dtw]{stepPattern}} in package \pkg{dtw} +#' \insertCite{Giorgino:2009}{dtwSat}. #' #' @param n An integer. The maximun number of matches to perform. #' NULL will return all matches. @@ -63,9 +64,9 @@ #' Default is FALSE. For plot methods use \code{keep=TRUE}. #' #' @param span A number. Span between two matches, \emph{i.e.} the minimum -#' interval between two matches; for details see [3]. If not declared it removes -#' all overlapping matches of the same pattern. To include overlapping matches -#' of the same pattern use \code{span=0}. +#' interval between two matches; for details see \insertCite{Muller:2007}{dtwSat}. +#' If not declared it removes all overlapping matches of the same pattern. To include +#' overlapping matches of the same pattern use \code{span=0}. #' #' @param min.length A number between 0 an 1. This argument removes overfittings. #' Minimum length after warping. Percentage of the original pattern length. Default is 0.5, @@ -75,24 +76,16 @@ #' function saves in the current work directory. #' #' @references -#' [1] Maus V, Camara G, Cartaxo R, Sanchez A, Ramos FM, de Queiroz, GR. -#' (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, vol.9, no.8, pp.3729-3739. -#' @references -#' [2] Giorgino, T. (2009). Computing and Visualizing Dynamic Time Warping Alignments in R: -#' The dtw Package. Journal of Statistical Software, 31, 1-24. -#' @references -#' [3] Muller, M. (2007). Dynamic Time Warping. In Information Retrieval for Music -#' and Motion (pp. 79-84). London: Springer London, Limited. +#' \insertAllCited{} #' #' @details The linear \code{linearWeight} and \code{logisticWeight} weight functions #' can be passed to \code{twdtwApply} through the argument \code{weight.fun}. This will #' add a time-weight to the dynamic time warping analysis. The time weight #' creates a global constraint useful for analysing time series with phenological cycles -#' of vegetation that are usually bound to seasons. In previous studies by [1] the -#' logistic weight had better results than the linear for land cover classification. -#' See [1] for details about the method. +#' of vegetation that are usually bound to seasons. In previous studies by +#' \insertCite{Maus:2016}{dtwSat} the logistic weight had better results than the +#' linear for land cover classification. +#' See \insertCite{Maus:2016,Maus:2019}{dtwSat} for details about the method. #' #' @return An object of class twdtw*. #' diff --git a/R/twdtwApplyParallel.R b/R/twdtwApplyParallel.R index bba9329..f882d80 100644 --- a/R/twdtwApplyParallel.R +++ b/R/twdtwApplyParallel.R @@ -5,29 +5,21 @@ #' #' @description This function performs a multidimensional Time-Weighted DTW #' analysis and retrieves the matches between the temporal patterns and -#' a set of time series [1]. +#' a set of time series \insertCite{Maus:2019}{dtwSat}. #' #' @inheritParams twdtwApply #' #' @references -#' [1] Maus V, Camara G, Cartaxo R, Sanchez A, Ramos FM, de Queiroz, GR. -#' (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, vol.9, no.8, pp.3729-3739. -#' @references -#' [2] Giorgino, T. (2009). Computing and Visualizing Dynamic Time Warping Alignments in R: -#' The dtw Package. Journal of Statistical Software, 31, 1-24. -#' @references -#' [3] Muller, M. (2007). Dynamic Time Warping. In Information Retrieval for Music -#' and Motion (pp. 79-84). London: Springer London, Limited. +#' \insertAllCited{} #' -#' @details The \code{linearWeight} and \code{logisticWeight} weight functions +#' @details The linear \code{linearWeight} and \code{logisticWeight} weight functions #' can be passed to \code{twdtwApply} through the argument \code{weight.fun}. This will #' add a time-weight to the dynamic time warping analysis. The time weight #' creates a global constraint useful for analysing time series with phenological cycles -#' of vegetation that are usually bound to seasons. In previous studies by [1] the -#' logistic weight had better results than the linear for land cover classification. -#' See [1] for details about the method. +#' of vegetation that are usually bound to seasons. In previous studies by +#' \insertCite{Maus:2016}{dtwSat} the logistic weight had better results than the +#' linear for land cover classification. +#' See \insertCite{Maus:2016,Maus:2019}{dtwSat} for details about the method. #' #' @return An object of class twdtwRaster. #' diff --git a/R/twdtwAssess.R b/R/twdtwAssess.R index 441b6c3..060a539 100644 --- a/R/twdtwAssess.R +++ b/R/twdtwAssess.R @@ -10,8 +10,9 @@ setGeneric("twdtwAssess", #' @description Performs an accuracy assessment #' of the classified maps. The function returns Overall Accuracy, #' User's Accuracy, Produce's Accuracy, error matrix (confusion matrix), -#' and estimated area according to [1-2]. The function returns the metrics -#' for each time interval and a summary considering all classified intervals. +#' and estimated area according to \insertCite{Olofsson:2013,Olofsson:2014;textual}{dtwSat}. +#' The function returns the metrics for each time interval and a summary considering all +#' classified intervals. #' #' @param object An object of class \code{\link[dtwSat]{twdtwRaster}} resulting from #' the classification, i.e. \code{\link[dtwSat]{twdtwClassify}}. @@ -51,15 +52,11 @@ setGeneric("twdtwAssess", #' first date of the timeline from satellite images. #' #' @references -#' [1] Olofsson, P., Foody, G.M., Stehman, S.V., Woodcock, C.E. (2013). -#' Making better use of accuracy data in land change studies: Estimating -#' accuracy and area and quantifying uncertainty using stratified estimation. -#' Remote Sensing of Environment, 129, pp.122-131. -#' -#' @references -#' [2] Olofsson, P., Foody G.M., Herold M., Stehman, S.V., Woodcock, C.E., Wulder, M.A. (2014) -#' Good practices for estimating area and assessing accuracy of land change. Remote Sensing of -#' Environment, 148, pp. 42-57. +#' \insertAllCited{} +#' +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} #' #' @seealso \code{\link[dtwSat]{twdtwClassify}}, #' \code{\link[dtwSat]{twdtwAssessment}}, and diff --git a/R/twdtwClassify.R b/R/twdtwClassify.R index 5946c83..4a91a2f 100644 --- a/R/twdtwClassify.R +++ b/R/twdtwClassify.R @@ -62,6 +62,11 @@ #' \code{\link[dtwSat]{twdtwTimeSeries-class}}, and #' \code{\link[dtwSat]{twdtwRaster-class}}, #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @export setGeneric(name = "twdtwClassify", def = function(x, ...) standardGeneric("twdtwClassify")) diff --git a/R/twdtwCrossValidate.R b/R/twdtwCrossValidate.R index 12da52c..bb91e93 100644 --- a/R/twdtwCrossValidate.R +++ b/R/twdtwCrossValidate.R @@ -25,6 +25,11 @@ setGeneric("twdtwCrossValidate", #' @param ... Other arguments to be passed to \code{\link[dtwSat]{createPatterns}} and #' to \code{\link[dtwSat]{twdtwApply}}. #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' \dontrun{ #' # Data folder diff --git a/R/twdtwXtable.R b/R/twdtwXtable.R index 6a8bc13..fb1c98f 100644 --- a/R/twdtwXtable.R +++ b/R/twdtwXtable.R @@ -44,6 +44,11 @@ setGeneric("twdtwXtable", #' @seealso \code{\link[dtwSat]{twdtwAssess}} and #' \code{\link[dtwSat]{twdtwAssessment}}. #' +#' @references +#' \insertRef{Maus:2019}{dtwSat} +#' +#' \insertRef{Maus:2016}{dtwSat} +#' #' @examples #' \dontrun{ #' diff --git a/R/zzz.R b/R/zzz.R index 9af21df..dd809fc 100644 --- a/R/zzz.R +++ b/R/zzz.R @@ -48,6 +48,7 @@ #' @importFrom caret createDataPartition #' @importFrom xtable xtable print.xtable #' @importFrom utils packageDescription flush.console +#' @importFrom Rdpack reprompt #' @useDynLib dtwSat, .registration = TRUE #' NULL diff --git a/cran-comments.md b/cran-comments.md index e523082..cd4bae8 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,10 +1,14 @@ ## Test environments -* local Ubuntu 18.04 (64-bit), R 3.5.2 -* win-builder R-devel and R-release -devtools::check(args = '--as-cran', build_args = '--compact-vignettes=gs+qpdf') -devtools::build_win(args = '--compact-vignettes=gs+qpdf') -devtools::submit_cran(args = '--compact-vignettes=gs+qpdf') - +* win-builder + devtools::check_win_oldrelease(args = '--compact-vignettes=gs+qpdf', binary = FALSE) + devtools::check_win_release(args = '--compact-vignettes=gs+qpdf', binary = FALSE) + devtools::check_win_devel(args = '--compact-vignettes=gs+qpdf', binary = FALSE) +* R-hub + rhub::check_for_cran(check_args = '--as-cran --compact-vignettes=gs+qpdf') +* Ubuntu 18.04 (64-bit), R 3.5.2 + devtools::check(args = '--as-cran', build_args = '--compact-vignettes=gs+qpdf') + devtools::check(args = '--use-valgrind', build_args = '--compact-vignettes=gs+qpdf') + devtools::submit_cran(args = '--compact-vignettes=gs+qpdf') ## REVIEWS diff --git a/dtwSat.Rproj b/dtwSat.Rproj index 14cd891..6c2d28e 100644 --- a/dtwSat.Rproj +++ b/dtwSat.Rproj @@ -17,5 +17,5 @@ PackageUseDevtools: Yes PackageInstallArgs: --no-multiarch --with-keep.source PackageBuildArgs: --compact-vignettes=gs+qpdf PackageBuildBinaryArgs: --compact-vignettes=gs+qpdf -PackageCheckArgs: --as-cran --no-build-vignettes --no-vignettes +PackageCheckArgs: --as-cran PackageRoxygenize: rd,collate,namespace diff --git a/man/MOD13Q1.MT.yearly.patterns.Rd b/man/MOD13Q1.MT.yearly.patterns.Rd index 647a963..bdfe44d 100644 --- a/man/MOD13Q1.MT.yearly.patterns.Rd +++ b/man/MOD13Q1.MT.yearly.patterns.Rd @@ -12,17 +12,19 @@ MOD13Q1.MT.yearly.patterns This dataset has a list of patterns with the phenological cycle of: Water, Cotton-Fallow, Forest, Low vegetation, Pasture, Soybean-Cotton, Soybean-Maize, Soybean-Millet, Soybean-Sunflower, and Wetland. These time series are based on the MODIS product -MOD13Q1 250 m 16 days [1]. The patterns were built from ground truth samples of each +MOD13Q1 250 m 16 days \insertCite{Didan:2015}{dtwSat}. +The patterns were built from ground truth samples of each crop using Generalized Additive Models (GAM), see \link[dtwSat]{createPatterns}. } \references{ -[1] Friedl MA, Sulla-Menashe D, Tan B, Schneider A, Ramankutty N, Sibley A, Huang X. (2010). -MODIS Collection 5 global land cover: Algorithm refinements and characterization of new -datasets. Remote Sensing of Environment, 114(1), 168 182. +\insertAllCited{} + + \insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ -MOD13Q1 documentation: See -\url{https://lpdaac.usgs.gov/dataset_discovery/modis/modis_products_table/mod13q1_v006}. +For details about MOD13Q1 see \insertCite{Didan:2015}{dtwSat}. } \author{ Victor Maus, \email{vwmaus1@gmail.com} diff --git a/man/MOD13Q1.patterns.list.Rd b/man/MOD13Q1.patterns.list.Rd index 9734cae..b59172d 100644 --- a/man/MOD13Q1.patterns.list.Rd +++ b/man/MOD13Q1.patterns.list.Rd @@ -14,21 +14,23 @@ MOD13Q1.patterns.list \description{ This dataset has a list of patterns with the phenological cycle of: Soybean, Cotton, and Maize. These time series are based on the MODIS product -MOD13Q1 250 m 16 days [1]. The patterns were built from ground truth samples of each +MOD13Q1 250 m 16 days \insertCite{Didan:2015}{dtwSat}. The patterns were built +from ground truth samples of each crop using Generalized Additive Models (GAM), see \link[dtwSat]{createPatterns}. } \references{ -[1] Friedl MA, Sulla-Menashe D, Tan B, Schneider A, Ramankutty N, Sibley A, Huang X. (2010). -MODIS Collection 5 global land cover: Algorithm refinements and characterization of new -datasets. Remote Sensing of Environment, 114(1), 168 182. +\insertAllCited{} + + \insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \link[dtwSat]{MOD13Q1.ts}, \link[dtwSat]{MOD13Q1.ts.list}, and \link[dtwSat]{createPatterns}. -MOD13Q1 documentation: See -\url{https://lpdaac.usgs.gov/dataset_discovery/modis/modis_products_table/mod13q1_v006}. +For details about MOD13Q1 see \insertCite{Didan:2015}{dtwSat}. } \author{ Victor Maus, \email{vwmaus1@gmail.com} diff --git a/man/MOD13Q1.ts.Rd b/man/MOD13Q1.ts.Rd index 2d6fa6c..ded61fe 100644 --- a/man/MOD13Q1.ts.Rd +++ b/man/MOD13Q1.ts.Rd @@ -12,20 +12,22 @@ MOD13Q1.ts } \description{ This dataset has a time series based on the -MODIS product MOD13Q1 250 m 16 days [1]. It is an irregularly sampled time series +MODIS product MOD13Q1 250 m 16 days \insertCite{Didan:2015}{dtwSat}. +It is an irregularly sampled time series using the real date of each pixel from ''2009-08-05'' to ''2013-07-31''. } \references{ -[1] Friedl MA, Sulla-Menashe D, Tan B, Schneider A, Ramankutty N, Sibley A, Huang X. (2010). -MODIS Collection 5 global land cover: Algorithm refinements and characterization of new -datasets. Remote Sensing of Environment, 114(1), 168 182. +\insertAllCited{} + + \insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \link[dtwSat]{MOD13Q1.ts.list}, \link[dtwSat]{MOD13Q1.patterns.list}. -MOD13Q1 documentation: -\url{https://lpdaac.usgs.gov/dataset_discovery/modis/modis_products_table/mod13q1_v006}. +For details about MOD13Q1 see \insertCite{Didan:2015}{dtwSat}. } \author{ Victor Maus, \email{vwmaus1@gmail.com} diff --git a/man/MOD13Q1.ts.list.Rd b/man/MOD13Q1.ts.list.Rd index 7f30404..9b14609 100644 --- a/man/MOD13Q1.ts.list.Rd +++ b/man/MOD13Q1.ts.list.Rd @@ -12,20 +12,22 @@ MOD13Q1.ts.list } \description{ This dataset has a list of time series based on the -MODIS product MOD13Q1 250 m 16 days [1]. It is an irregularly sampled time series +MODIS product MOD13Q1 250 m 16 days \insertCite{Didan:2015}{dtwSat}. +It is an irregularly sampled time series using the real date of each pixel from ''2009-08-05'' to ''2013-07-31''. } \references{ -[1] Friedl MA, Sulla-Menashe D, Tan B, Schneider A, Ramankutty N, Sibley A, Huang X. (2010). -MODIS Collection 5 global land cover: Algorithm refinements and characterization of new -datasets. Remote Sensing of Environment, 114(1), 168 182. +\insertAllCited{} + + \insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \link[dtwSat]{MOD13Q1.ts}, and \link[dtwSat]{MOD13Q1.patterns.list}. -MOD13Q1 documentation: -\url{https://lpdaac.usgs.gov/dataset_discovery/modis/modis_products_table/mod13q1_v006}. +For details about MOD13Q1 see \insertCite{Didan:2015}{dtwSat}. } \author{ Victor Maus, \email{vwmaus1@gmail.com} diff --git a/man/createPatterns.Rd b/man/createPatterns.Rd index 57da6ec..9a57b5a 100644 --- a/man/createPatterns.Rd +++ b/man/createPatterns.Rd @@ -73,6 +73,11 @@ autoplot(patt[[1]], facets = NULL) + xlab("Time") + ylab("Value") } } +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} +} \seealso{ \code{\link[dtwSat]{twdtwMatches-class}}, \code{\link[dtwSat]{twdtwTimeSeries-class}}, diff --git a/man/dtwSat.Rd b/man/dtwSat.Rd index e280963..ebbd846 100644 --- a/man/dtwSat.Rd +++ b/man/dtwSat.Rd @@ -5,7 +5,8 @@ \title{Time-Weighted Dynamic Time Warping for Satellite Image Time Series} \description{ Provides an implementation of the Time-Weighted Dynamic Time Warping -(TWDTW) method for land use and land cover mapping using satellite image time series [1]. +(TWDTW) method for land use and land cover mapping using satellite image time series +\insertCite{Maus:2016,Maus:2019}{dtwSat}. TWDTW is based on the Dynamic Time Warping technique and has achieved high accuracy for land use and land cover classification using satellite data. The method is based on comparing unclassified satellite image time series with a set of known temporal @@ -15,10 +16,7 @@ for satellite datasets, visualize the results of the time series analysis, produ land cover maps, and create temporal plots for land cover change analysis. } \references{ -[1] Maus V, Camara G, Cartaxo R, Sanchez A, Ramos FM, de Queiroz, GR. -(2016). A Time-Weighted Dynamic Time Warping method for land use and land cover -mapping. Selected Topics in Applied Earth Observations and Remote Sensing, -IEEE Journal of, vol.PP, no.99, pp.1-11. +\insertAllCited{} } \seealso{ \code{\link[dtwSat]{twdtwApply}} diff --git a/man/get.Rd b/man/get.Rd index 242fb39..0de62f0 100644 --- a/man/get.Rd +++ b/man/get.Rd @@ -44,6 +44,11 @@ getAlignments(mat) getMatches(mat) getInternals(mat) +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwMatches-class}}, and diff --git a/man/getDatesFromDOY.Rd b/man/getDatesFromDOY.Rd index d96250c..9d5e676 100644 --- a/man/getDatesFromDOY.Rd +++ b/man/getDatesFromDOY.Rd @@ -26,6 +26,11 @@ doy = c(366, 365) dates = getDatesFromDOY(year, doy) dates +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \link[dtwSat]{shiftDates} diff --git a/man/getTimeSeries.Rd b/man/getTimeSeries.Rd index 81fab44..3f2b16c 100644 --- a/man/getTimeSeries.Rd +++ b/man/getTimeSeries.Rd @@ -80,6 +80,11 @@ ts = getTimeSeries(rts, y = ts_location, proj4string = prj_string) autoplot(ts[[1]], facets = NULL) + xlab("Time") + ylab("Value") +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwRaster-class}}, diff --git a/man/linearWeight.Rd b/man/linearWeight.Rd index 0f7de00..f4fdb4a 100644 --- a/man/linearWeight.Rd +++ b/man/linearWeight.Rd @@ -24,9 +24,10 @@ The linear \code{linearWeight} and \code{logisticWeight} weight functions can be passed to \code{\link[dtwSat]{twdtwApply}} through the argument \code{weight.fun}. This will add a time-weight to the dynamic time warping analysis. The time weight creates a global constraint useful to analyse time series with phenological cycles -of vegetation that are usually bound to seasons. In previous studies by [1] the -logistic weight had better results than the linear for land cover classification. -See [1] for details about the method. +of vegetation that are usually bound to seasons. In previous studies by +\insertCite{Maus:2016;textual}{dtwSat} the logistic weight had better results than the +linear for land cover classification. See \insertCite{Maus:2016;textual}{dtwSat} and +\insertCite{Maus:2019;textual}{dtwSat}. } \examples{ lin_fun = linearWeight(a=0.1) @@ -34,10 +35,7 @@ lin_fun } \references{ -[1] Maus V, Camara G, Cartaxo R, Sanchez A, Ramos FM, de Queiroz, GR. -(2016). A Time-Weighted Dynamic Time Warping method for land use and land cover -mapping. Selected Topics in Applied Earth Observations and Remote Sensing, -IEEE Journal of, vol.PP, no.99, pp.1-11. +\insertAllCited{} } \seealso{ \code{\link[dtwSat]{twdtwApply}} diff --git a/man/logisticWeight.Rd b/man/logisticWeight.Rd index b086d3c..b45f63c 100644 --- a/man/logisticWeight.Rd +++ b/man/logisticWeight.Rd @@ -24,9 +24,10 @@ The linear \code{linearWeight} and \code{logisticWeight} weight functions can be passed to \code{\link[dtwSat]{twdtwApply}} through the argument \code{weight.fun}. This will add a time-weight to the dynamic time warping analysis. The time weight creates a global constraint useful to analyse time series with phenological cycles -of vegetation that are usually bound to seasons. In previous studies by [1] the -logistic weight had better results than the linear for land cover classification. -See [1] for details about the method. +of vegetation that are usually bound to seasons. In previous studies by +\insertCite{Maus:2016;textual}{dtwSat} the logistic weight had better results than the +linear for land cover classification. See \insertCite{Maus:2016;textual}{dtwSat} and +\insertCite{Maus:2019;textual}{dtwSat}. } \examples{ log_fun = logisticWeight(alpha=-0.1, beta=100) @@ -34,10 +35,7 @@ log_fun } \references{ -[1] Maus V, Camara G, Cartaxo R, Sanchez A, Ramos FM, de Queiroz, GR. -(2016). A Time-Weighted Dynamic Time Warping method for land use and land cover -mapping. Selected Topics in Applied Earth Observations and Remote Sensing, -IEEE Journal of, vol.PP, no.99, pp.1-11. +\insertAllCited{} } \seealso{ \code{\link[dtwSat]{twdtwApply}} diff --git a/man/plotAccuracy.Rd b/man/plotAccuracy.Rd index ad66c21..d66f621 100644 --- a/man/plotAccuracy.Rd +++ b/man/plotAccuracy.Rd @@ -45,6 +45,11 @@ plotAccuracy(x, category.type="letter") } +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwAssessment}} and \code{\link[dtwSat]{twdtwAssess}} diff --git a/man/plotAdjustedArea.Rd b/man/plotAdjustedArea.Rd index 708bffe..0305eb8 100644 --- a/man/plotAdjustedArea.Rd +++ b/man/plotAdjustedArea.Rd @@ -41,6 +41,11 @@ plotAdjustedArea(twdtw_assess, category.type="letter") } +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwAssessment}} and \code{\link[dtwSat]{twdtwAssess}} diff --git a/man/plotAlignments.Rd b/man/plotAlignments.Rd index 58da040..b6ba9a5 100644 --- a/man/plotAlignments.Rd +++ b/man/plotAlignments.Rd @@ -39,6 +39,11 @@ plotAlignments(mat1) plotAlignments(mat1, attr=c("evi","ndvi")) +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwMatches-class}}, diff --git a/man/plotArea.Rd b/man/plotArea.Rd index ce2792a..7252087 100644 --- a/man/plotArea.Rd +++ b/man/plotArea.Rd @@ -83,6 +83,11 @@ plotArea(r_lucc, perc=FALSE) } } +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} +} \seealso{ \code{\link[dtwSat]{twdtwRaster-class}}, \code{\link[dtwSat]{twdtwApply}}, diff --git a/man/plotChanges.Rd b/man/plotChanges.Rd index ee39de5..cec62f8 100644 --- a/man/plotChanges.Rd +++ b/man/plotChanges.Rd @@ -62,6 +62,11 @@ plotChanges(r_lucc) } } +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} +} \seealso{ \code{\link[dtwSat]{twdtwRaster-class}}, \code{\link[dtwSat]{twdtwApply}}, diff --git a/man/plotClassification.Rd b/man/plotClassification.Rd index 07e9f08..9ceb2f9 100644 --- a/man/plotClassification.Rd +++ b/man/plotClassification.Rd @@ -43,6 +43,11 @@ gp = plotClassification(x=mat1, from=from, to=to, by=by, overlap=.5) gp +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwMatches-class}}, diff --git a/man/plotCostMatrix.Rd b/man/plotCostMatrix.Rd index c8439cb..318a0c5 100644 --- a/man/plotCostMatrix.Rd +++ b/man/plotCostMatrix.Rd @@ -39,6 +39,11 @@ plotCostMatrix(mat1, matrix.name="localMatrix") plotCostMatrix(mat1, matrix.name="timeWeight") +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwMatches-class}}, diff --git a/man/plotDistance.Rd b/man/plotDistance.Rd index a446d94..2beaf9d 100644 --- a/man/plotDistance.Rd +++ b/man/plotDistance.Rd @@ -51,6 +51,11 @@ plotDistance(r_twdtw) } } +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} +} \seealso{ \code{\link[dtwSat]{twdtwRaster-class}}, \code{\link[dtwSat]{twdtwApply}}, diff --git a/man/plotMapSamples.Rd b/man/plotMapSamples.Rd index 64543cf..081107a 100644 --- a/man/plotMapSamples.Rd +++ b/man/plotMapSamples.Rd @@ -108,6 +108,11 @@ twdtwXtable(twdtw_assess, table.type = "area") } +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwAssessment}}, diff --git a/man/plotMaps.Rd b/man/plotMaps.Rd index 2a16fd2..723582e 100644 --- a/man/plotMaps.Rd +++ b/man/plotMaps.Rd @@ -62,6 +62,11 @@ plotMaps(r_lucc) } } +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} +} \seealso{ \code{\link[dtwSat]{twdtwRaster-class}}, \code{\link[dtwSat]{twdtwApply}}, diff --git a/man/plotMatches.Rd b/man/plotMatches.Rd index 373313c..4ca4eff 100644 --- a/man/plotMatches.Rd +++ b/man/plotMatches.Rd @@ -50,6 +50,11 @@ plotMatches(mat1, patterns.labels=c("Soybean","Maize"), k=4) plotMatches(mat1, patterns.labels=c("Soybean","Cotton"), k=c(3,1)) +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwMatches-class}}, diff --git a/man/plotPaths.Rd b/man/plotPaths.Rd index 12b619f..cea9447 100644 --- a/man/plotPaths.Rd +++ b/man/plotPaths.Rd @@ -38,6 +38,11 @@ plotPaths(mat1, patterns.labels="Soybean", k=1:2) plotPaths(mat1, patterns.labels=c("Maize","Cotton"), k=2) +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwMatches-class}}, diff --git a/man/plotPatterns.Rd b/man/plotPatterns.Rd index ac9f68c..44e91f7 100644 --- a/man/plotPatterns.Rd +++ b/man/plotPatterns.Rd @@ -31,6 +31,11 @@ patt = twdtwTimeSeries(MOD13Q1.patterns.list) plotPatterns(patt) plotPatterns(patt, attr="evi") +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwTimeSeries-class}} and diff --git a/man/plotTimeSeries.Rd b/man/plotTimeSeries.Rd index 2d15cf6..8233ef1 100644 --- a/man/plotTimeSeries.Rd +++ b/man/plotTimeSeries.Rd @@ -28,6 +28,11 @@ ts = twdtwTimeSeries(MOD13Q1.ts.list) plotTimeSeries(ts) plotTimeSeries(ts, attr="evi") +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwTimeSeries-class}} and diff --git a/man/shiftDates.Rd b/man/shiftDates.Rd index 16ddbcc..961670e 100644 --- a/man/shiftDates.Rd +++ b/man/shiftDates.Rd @@ -38,6 +38,15 @@ npatt = shiftDates(patt, year=2005) index(patt) index(npatt) +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} + +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwTimeSeries-class}} diff --git a/man/subset.Rd b/man/subset.Rd index 57ca3d0..9bf1f24 100644 --- a/man/subset.Rd +++ b/man/subset.Rd @@ -72,6 +72,11 @@ ts_evi = getTimeSeries(rts_evi, y = field_samples, proj4string = prj_string) # Subset all labels = "Forest" ts_forest = subset(ts_evi, labels="Forest") +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwRaster-class}}, diff --git a/man/twdtwApply.Rd b/man/twdtwApply.Rd index 0995e16..6cef17b 100644 --- a/man/twdtwApply.Rd +++ b/man/twdtwApply.Rd @@ -46,15 +46,16 @@ time warping. See details.} Default is ''Euclidean'' see \code{\link[proxy]{dist}} in package \pkg{proxy}.} -\item{step.matrix}{See \code{\link[dtw]{stepPattern}} in package \pkg{dtw} [2].} +\item{step.matrix}{See \code{\link[dtw]{stepPattern}} in package \pkg{dtw} +\insertCite{Giorgino:2009}{dtwSat}.} \item{n}{An integer. The maximun number of matches to perform. NULL will return all matches.} \item{span}{A number. Span between two matches, \emph{i.e.} the minimum -interval between two matches; for details see [3]. If not declared it removes -all overlapping matches of the same pattern. To include overlapping matches -of the same pattern use \code{span=0}.} +interval between two matches; for details see \insertCite{Muller:2007}{dtwSat}. +If not declared it removes all overlapping matches of the same pattern. To include +overlapping matches of the same pattern use \code{span=0}.} \item{min.length}{A number between 0 an 1. This argument removes overfittings. Minimum length after warping. Percentage of the original pattern length. Default is 0.5, @@ -93,16 +94,17 @@ An object of class twdtw*. \description{ This function performs a multidimensional Time-Weighted DTW analysis and retrieves the matches between the temporal patterns and -a set of time series [1]. +a set of time series \insertCite{Maus:2019}{dtwSat}. } \details{ The linear \code{linearWeight} and \code{logisticWeight} weight functions can be passed to \code{twdtwApply} through the argument \code{weight.fun}. This will add a time-weight to the dynamic time warping analysis. The time weight creates a global constraint useful for analysing time series with phenological cycles -of vegetation that are usually bound to seasons. In previous studies by [1] the -logistic weight had better results than the linear for land cover classification. -See [1] for details about the method. +of vegetation that are usually bound to seasons. In previous studies by +\insertCite{Maus:2016}{dtwSat} the logistic weight had better results than the +linear for land cover classification. +See \insertCite{Maus:2016,Maus:2019}{dtwSat} for details about the method. } \examples{ # Applying TWDTW analysis to objects of class twdtwTimeSeries @@ -207,16 +209,7 @@ twdtwXtable(twdtw_assess, table.type = "area") } \references{ -[1] Maus V, Camara G, Cartaxo R, Sanchez A, Ramos FM, de Queiroz, GR. -(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, vol.9, no.8, pp.3729-3739. - -[2] Giorgino, T. (2009). Computing and Visualizing Dynamic Time Warping Alignments in R: -The dtw Package. Journal of Statistical Software, 31, 1-24. - -[3] Muller, M. (2007). Dynamic Time Warping. In Information Retrieval for Music -and Motion (pp. 79-84). London: Springer London, Limited. +\insertAllCited{} } \seealso{ \code{\link[dtwSat]{twdtwMatches-class}}, diff --git a/man/twdtwApplyParallel.Rd b/man/twdtwApplyParallel.Rd index f9d56d0..f788a9f 100644 --- a/man/twdtwApplyParallel.Rd +++ b/man/twdtwApplyParallel.Rd @@ -41,15 +41,16 @@ time warping. See details.} Default is ''Euclidean'' see \code{\link[proxy]{dist}} in package \pkg{proxy}.} -\item{step.matrix}{See \code{\link[dtw]{stepPattern}} in package \pkg{dtw} [2].} +\item{step.matrix}{See \code{\link[dtw]{stepPattern}} in package \pkg{dtw} +\insertCite{Giorgino:2009}{dtwSat}.} \item{n}{An integer. The maximun number of matches to perform. NULL will return all matches.} \item{span}{A number. Span between two matches, \emph{i.e.} the minimum -interval between two matches; for details see [3]. If not declared it removes -all overlapping matches of the same pattern. To include overlapping matches -of the same pattern use \code{span=0}.} +interval between two matches; for details see \insertCite{Muller:2007}{dtwSat}. +If not declared it removes all overlapping matches of the same pattern. To include +overlapping matches of the same pattern use \code{span=0}.} \item{min.length}{A number between 0 an 1. This argument removes overfittings. Minimum length after warping. Percentage of the original pattern length. Default is 0.5, @@ -85,16 +86,17 @@ An object of class twdtwRaster. \description{ This function performs a multidimensional Time-Weighted DTW analysis and retrieves the matches between the temporal patterns and -a set of time series [1]. +a set of time series \insertCite{Maus:2019}{dtwSat}. } \details{ -The \code{linearWeight} and \code{logisticWeight} weight functions +The linear \code{linearWeight} and \code{logisticWeight} weight functions can be passed to \code{twdtwApply} through the argument \code{weight.fun}. This will add a time-weight to the dynamic time warping analysis. The time weight creates a global constraint useful for analysing time series with phenological cycles -of vegetation that are usually bound to seasons. In previous studies by [1] the -logistic weight had better results than the linear for land cover classification. -See [1] for details about the method. +of vegetation that are usually bound to seasons. In previous studies by +\insertCite{Maus:2016}{dtwSat} the logistic weight had better results than the +linear for land cover classification. +See \insertCite{Maus:2016,Maus:2019}{dtwSat} for details about the method. } \examples{ \dontrun{ @@ -186,16 +188,7 @@ twdtwXtable(twdtw_assess, table.type = "area") } \references{ -[1] Maus V, Camara G, Cartaxo R, Sanchez A, Ramos FM, de Queiroz, GR. -(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, vol.9, no.8, pp.3729-3739. - -[2] Giorgino, T. (2009). Computing and Visualizing Dynamic Time Warping Alignments in R: -The dtw Package. Journal of Statistical Software, 31, 1-24. - -[3] Muller, M. (2007). Dynamic Time Warping. In Information Retrieval for Music -and Motion (pp. 79-84). London: Springer London, Limited. +\insertAllCited{} } \seealso{ \code{\link[dtwSat]{twdtwRaster-class}}, and diff --git a/man/twdtwAssess.Rd b/man/twdtwAssess.Rd index faf299d..4f6d2d0 100644 --- a/man/twdtwAssess.Rd +++ b/man/twdtwAssess.Rd @@ -73,8 +73,9 @@ if the objects are single pixels.} Performs an accuracy assessment of the classified maps. The function returns Overall Accuracy, User's Accuracy, Produce's Accuracy, error matrix (confusion matrix), -and estimated area according to [1-2]. The function returns the metrics -for each time interval and a summary considering all classified intervals. +and estimated area according to \insertCite{Olofsson:2013,Olofsson:2014;textual}{dtwSat}. +The function returns the metrics for each time interval and a summary considering all +classified intervals. } \examples{ \dontrun{ @@ -255,14 +256,11 @@ twdtwXtable(twdtw_assess, table.type = "area") } } \references{ -[1] Olofsson, P., Foody, G.M., Stehman, S.V., Woodcock, C.E. (2013). -Making better use of accuracy data in land change studies: Estimating -accuracy and area and quantifying uncertainty using stratified estimation. -Remote Sensing of Environment, 129, pp.122-131. - -[2] Olofsson, P., Foody G.M., Herold M., Stehman, S.V., Woodcock, C.E., Wulder, M.A. (2014) -Good practices for estimating area and assessing accuracy of land change. Remote Sensing of -Environment, 148, pp. 42-57. +\insertAllCited{} + + \insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwClassify}}, diff --git a/man/twdtwAssessment-class.Rd b/man/twdtwAssessment-class.Rd index bc5d58e..be5e610 100644 --- a/man/twdtwAssessment-class.Rd +++ b/man/twdtwAssessment-class.Rd @@ -34,6 +34,11 @@ using the the pixel resolution in the map unit. } } +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} +} \seealso{ \code{\link[dtwSat]{twdtwClassify}}, \code{\link[dtwSat]{twdtwAssess}}, and diff --git a/man/twdtwClassify.Rd b/man/twdtwClassify.Rd index 35488b8..a3bd26e 100644 --- a/man/twdtwClassify.Rd +++ b/man/twdtwClassify.Rd @@ -216,6 +216,11 @@ twdtwXtable(twdtw_assess, table.type = "area") } +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwApply}}, diff --git a/man/twdtwCrossValidate.Rd b/man/twdtwCrossValidate.Rd index 5c6f676..4f6843a 100644 --- a/man/twdtwCrossValidate.Rd +++ b/man/twdtwCrossValidate.Rd @@ -72,6 +72,11 @@ twdtwXtable(cross_validation, show.overall=FALSE) } } +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} +} \author{ Victor Maus, \email{vwmaus1@gmail.com} } diff --git a/man/twdtwCrossValidation-class.Rd b/man/twdtwCrossValidation-class.Rd index ef494d4..d1a3121 100644 --- a/man/twdtwCrossValidation-class.Rd +++ b/man/twdtwCrossValidation-class.Rd @@ -71,6 +71,11 @@ plot(cross_validation) } } +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} +} \seealso{ \code{\link[dtwSat]{twdtwMatches-class}}, \code{\link[dtwSat]{createPatterns}}, and diff --git a/man/twdtwMatches-class.Rd b/man/twdtwMatches-class.Rd index b66e237..992897a 100644 --- a/man/twdtwMatches-class.Rd +++ b/man/twdtwMatches-class.Rd @@ -118,6 +118,11 @@ mat = twdtwApply(ts, patt, weight.fun = logisticWeight(-0.1, 100)) mat = twdtwMatches(ts, patterns=patt, alignments=mat) mat +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwApply}}, diff --git a/man/twdtwRaster-class.Rd b/man/twdtwRaster-class.Rd index 253ee77..77235c6 100644 --- a/man/twdtwRaster-class.Rd +++ b/man/twdtwRaster-class.Rd @@ -184,6 +184,11 @@ doy = brick(system.file("lucc_MT/data/doy.tif", package="dtwSat")) rts = twdtwRaster(doy, evi, ndvi, blue, red, nir, mir, timeline = timeline) } } +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} +} \seealso{ \code{\link[dtwSat]{twdtwApply}}, \code{\link[dtwSat]{getTimeSeries}}, diff --git a/man/twdtwTimeSeries-class.Rd b/man/twdtwTimeSeries-class.Rd index e825537..5ab4ade 100644 --- a/man/twdtwTimeSeries-class.Rd +++ b/man/twdtwTimeSeries-class.Rd @@ -102,6 +102,11 @@ tsB = twdtwTimeSeries(B = MOD13Q1.ts.list[[2]]) ts = twdtwTimeSeries(tsA, tsB, C=MOD13Q1.ts) ts +} +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} } \seealso{ \code{\link[dtwSat]{twdtwMatches-class}}, diff --git a/man/twdtwXtable.Rd b/man/twdtwXtable.Rd index 5ec197a..00bf7fb 100644 --- a/man/twdtwXtable.Rd +++ b/man/twdtwXtable.Rd @@ -109,6 +109,11 @@ twdtwXtable(twdtw_assess, table.type="area", category.type="letter", } } +\references{ +\insertRef{Maus:2019}{dtwSat} + + \insertRef{Maus:2016}{dtwSat} +} \seealso{ \code{\link[dtwSat]{twdtwAssess}} and \code{\link[dtwSat]{twdtwAssessment}}. diff --git a/vignettes/dtwSat.R b/vignettes/dtwSat.R deleted file mode 100644 index 3246b08..0000000 --- a/vignettes/dtwSat.R +++ /dev/null @@ -1,235 +0,0 @@ -## ---- echo = FALSE, eval = TRUE------------------------------------------- -options(replace.assign = TRUE, width = 76, prompt = "R> ") - -## ---- echo=FALSE, cache = FALSE------------------------------------------- -library(knitr) -opts_chunk$set( - prompt = TRUE, - width = 76, - warning = FALSE, - message = FALSE, - error = FALSE, - results = "hide", - cache.path = "./cache/", - cache = FALSE, - comment = "" -) -#knit_hooks$set(purl = hook_purl) # Save chunks to Rscript file - -###### Test 3 -# Work around encoding issue on Windows -other_user <- Sys.getenv("USER") != "maus" -set.seed(20160708L) -library(tikzDevice) -options(tikzDocumentDeclaration = "\\documentclass{jss}\\usepackage{siunitx}\\usepackage{latexsym}") -if (other_user) { - opts_chunk$set(dev="png") -} else { - opts_chunk$set(dev="pdf") -} -##### End test 3 - -#options(tikzDocumentDeclaration = "\\documentclass{jss}\\usepackage{siunitx}\\usepackage{latexsym}") - -## ---- echo=FALSE, eval = TRUE, cache = FALSE------------------------------ -library(dtwSat) -library(ggplot2) -library(scales) -library(Hmisc) -library(reshape2) - -new_theme = theme_get() -new_theme$text$family = "Helvetica" -new_theme$text$size = 8 -old_theme = theme_set(new_theme) - -tab_format = "latex" -page_width = 5.590551#in 14.2#cm -page_height = 9.173228#in 23.3#cm - -## ----twdtw-example, echo = FALSE, eval = TRUE, fig.width = page_width, fig.height = page_height/4, fig.align = 'center', fig.cap = 'Matches of the known temporal pattern to subintervals of the long-term time series. The solid black line is the long-term time series, the colored lines are the different matches of the same pattern, and the gray dashed lines are the matching points.', fig.pos = '!h'---- -n <- 4 -ts <- twdtwTimeSeries(MOD13Q1.ts, labels = "Time series") -patt <- twdtwTimeSeries(MOD13Q1.patterns.list$Cotton, labels = "Matches") -log_fun <- logisticWeight(alpha = -0.1, beta = 100) -mat <- twdtwApply(x = ts, y = patt, weight.fun = log_fun, keep = TRUE, n = n) -df_dist <- mat[[1]] -df_dist$label <- paste("Distance:", round(df_dist$distance, 2)) -df_dist$y <- 1.8 -plotMatches(mat, attr = "evi", k = n) + - ylab("Time series Pattern") + - geom_text(data = df_dist, mapping = aes_string(x = 'to', y = 'y', label = 'label'), - size = 2, family="Helvetica") + - theme(legend.position = "none") - -## ---- echo = TRUE, eval = TRUE, results = 'markup'------------------------ -library(dtwSat) -names(MOD13Q1.patterns.list) -head(MOD13Q1.ts, n = 2) - -## ---- echo = TRUE, eval = TRUE, results = 'markup'------------------------ -ts <- twdtwTimeSeries(MOD13Q1.ts, labels = "Time series") -patterns_ts <- twdtwTimeSeries(MOD13Q1.patterns.list) -patterns_ts - -## ----example-timeseries, echo = TRUE, eval = TRUE, fig.width = page_width, fig.height = page_height / 3, fig.align = 'center', fig.cap = 'Example of time series based on MODIS product MOD13Q1 \\citep{Friedl:2010}. The labels of the phenological cycle are shown in the plot.', fig.pos = '!h'---- -plot(ts, type = "timeseries") + annotate(geom = "text", - x = MOD13Q1.ts.labels$from + 90, y = 0.98, - label = MOD13Q1.ts.labels$label, size = 2) - -## ----temporal-patterns-soy-cot-mai, echo = TRUE, eval = TRUE, fig.width = page_width, fig.height = page_height / 3.5, fig.align = 'center', fig.cap = 'Temporal patterns of soybean, cotton, and maize based on MODIS product MOD13Q1 \\citep{Friedl:2010}.', fig.pos = '!h'---- -plot(patterns_ts, type = "patterns") - -## ---- echo = TRUE, eval = TRUE, results = 'markup'------------------------ -log_weight <- logisticWeight(alpha = -0.1, beta = 100) -matches <- - twdtwApply(x = ts, y = patterns_ts, weight.fun = log_weight, keep = TRUE) -slotNames(matches) -show(matches) - -## ----logist-time-weight, echo = FALSE, eval = TRUE, out.width = paste0(page_width / 2, 'in'), fig.align = 'center', fig.cap = 'Logistic time-weight function \\code{logisticWeight} with steepness \\code{alpha = -0.1} and midpoint \\code{beta = 100}. The $x$ axis shows the absolute difference between two dates in days and the $y$ axis shows the time-weight \\citep{Maus:2016}.', fig.pos = '!h'---- -# Maximum time difference in days -max_diff <- 366/2 -# Set parameters -alpha <- -0.1 -beta <- 100 -a <- 1 / max_diff -# Define the logistic weight -log_fun <- logisticWeight(alpha, beta) -# Define the linear weight -lin_fun <- linearWeight(a) -# Build data.frame with linear and logistic time-weight -Difference <- 0:max_diff -df_weight <- data.frame(Difference, Logistic = log_fun(Difference), Linear = lin_fun(Difference)) -names(df_weight) <- c("Difference", paste0("Logistic weight, alpha: ", alpha, " and beta: ", beta), - paste0("Linear weight, slop: ", round(a, 3))) -# Reshape and plot weight curves -df_weight <- melt(df_weight, id.vars = "Difference") -names(df_weight)[-1] <- c("Functions", "Weight") -ggplot(df_weight, aes_string(x="Difference", y="Weight", group="Functions", linetype="Functions")) + - geom_line() + xlab("Time difference (days)") + - theme(text = element_text(size = 10, family="Helvetica"), - plot.title = element_text(size = 10, family="Helvetica", face="bold"), - axis.title = element_text(size = 10, family="Helvetica"), - legend.position = c(.3,.85), legend.background = element_rect(fill="transparent")) + - scale_linetype(guide_legend(title = "")) - -## ----twdtw-matches, echo = TRUE, eval = TRUE, fig.width = page_width, fig.height = page_height / 3.5, fig.align = 'center', fig.cap = c('The four best matches of the "soybean" pattern in the time series using a logistic time-weight. The solid black line is the long-term time series; the coloured lines are the temporal patterns; and the grey dashed lines are the respective matching points.'), fig.pos = '!h'---- -plot(matches, type = "matches", patterns.labels = "Soybean", k = 4) - -## ----alignments-all-patterns, echo = TRUE, eval = TRUE, fig.width = page_width, fig.height = page_height / 2.5, fig.align = 'center', fig.cap = c('Alignments and dissimilarity measures of the patterns "soybean", "cotton", and "maize" to the subintervals of the long-term time series using a logistic time-weight. The solid black line is the EVI time series, and the coloured lines are the alignments of the patterns that have dissimilarity measure lower than three.'), fig.pos = '!h'---- -plot(matches, type = "alignments", attr = "evi", threshold = 3.0) - -## ----time-series-classification, echo = TRUE, eval = TRUE, fig.width = page_width, fig.height = page_height / 2.8, fig.align = 'center', fig.cap = c('Classification of each 6 months periods of the time series using results of the TWDTW analysis with logistic time-weight. The solid lines are the attributes of the time series, the background colours indicate the classification of the periods.'), fig.pos = '!ht'---- -ts_classification <- twdtwClassify(x = matches, - from = as.Date("2009-09-01"), to = as.Date("2013-09-01"), - by = "6 month", overlap = 0.5) -plot(ts_classification, type = "classification") - -## ---- echo = TRUE, eval = TRUE, results = 'markup'------------------------ -data_folder <- system.file("lucc_MT/data", package = "dtwSat") -dir(data_folder) - -## ---- echo = TRUE, eval = TRUE-------------------------------------------- -blue <- brick(paste(data_folder, "blue.tif", sep = "/")) -red <- brick(paste(data_folder, "red.tif", sep = "/")) -nir <- brick(paste(data_folder, "nir.tif", sep = "/")) -mir <- brick(paste(data_folder, "mir.tif", sep = "/")) -evi <- brick(paste(data_folder, "evi.tif", sep = "/")) -ndvi <- brick(paste(data_folder, "ndvi.tif", sep = "/")) -day_of_year <- brick(paste(data_folder, "doy.tif", sep = "/")) -dates <- scan(paste(data_folder, "timeline", sep = "/"), what = "dates") - -## ---- echo = TRUE, eval = TRUE-------------------------------------------- -raster_timeseries <- twdtwRaster(blue, red, nir, mir, evi, ndvi, - timeline = dates, doy = day_of_year) - -## ---- echo = TRUE, eval = TRUE, results = 'markup'------------------------ -field_samples <- read.csv(paste(data_folder, "samples.csv", sep = "/")) -head(field_samples, 5) -table(field_samples[["label"]]) -proj_str <- scan(paste(data_folder, "samples_projection", sep = "/"), - what = "character") -proj_str - -## ---- echo = TRUE, eval = TRUE, results = 'markup'------------------------ -field_samples_ts <- getTimeSeries(raster_timeseries, - y = field_samples, proj4string = proj_str) -field_samples_ts - -## ---- echo = TRUE, eval = FALSE, results = 'markup'----------------------- -# set.seed(1) -# log_fun <- logisticWeight(alpha = -0.1, beta = 50) -# cross_validation <- twdtwCrossValidate(field_samples_ts, -# times = 100, p = 0.1, freq = 8, formula = y ~ s(x, bs = "cc"), -# weight.fun = log_fun) - -## ---- echo = FALSE, eval = TRUE------------------------------------------- -load(system.file("lucc_MT/cross_validation.RData", package = "dtwSat")) - -## ---- echo = FALSE, eval = TRUE, results = 'asis'------------------------- -twdtwXtable(cross_validation, conf.int = .95, digits = 2, caption = "\\label{tab:cross-validation} User\'s and producer\'s accuracy of the TWDTW cross-validation using 100 resampling-with-replacement. The table shows the standard deviation ($\\sigma$) and the 95\\% confidence interval (ci) of the mean ($\\mu$).", comment = FALSE, caption.placement = "bottom", table.placement="!ht", show.footnote = FALSE) - -## ----plot-accuracy, echo = TRUE, eval = TRUE, fig.width = page_width, fig.height = page_width / 2, fig.align = 'center', fig.cap = 'User\'s and producer\'s accuracy of the TWDTW cross-validation using 100 resampling-with-replacement. The plot shows the 95\\% confidence interval of the mean.', fig.pos = '!ht'---- -plot(cross_validation, conf.int = .95) + - geom_jitter(size = 0.2, width = 0.1) - -## ---- echo = TRUE, eval = TRUE-------------------------------------------- -library(caret) -set.seed(1) -I <- unlist(createDataPartition(field_samples[ , "label"], p = 0.1)) -training_ts <- subset(field_samples_ts, I) -validation_samples <- field_samples[-I, ] - -## ---- echo = TRUE, eval = TRUE-------------------------------------------- -temporal_patterns <- - createPatterns(training_ts, freq = 8, formula = y ~ s(x)) - -## ----temporal-patterns, echo = TRUE, eval = TRUE, fig.width = page_width, fig.height = page_width / 1.3, fig.align = 'center', fig.pos = '!h', fig.cap = 'Temporal patterns of Forest, Cotton-fallow, Soybean-cotton, Soybean-maize, and Soybean-millet based on the ground truth samples.'---- -plot(temporal_patterns, - type = "patterns") + theme(legend.position = c(.8, .21)) - -## ---- echo = TRUE, eval = TRUE, results = 'markup'------------------------ -log_fun <- logisticWeight(alpha = -0.1, beta = 50) -twdtw_dist <- twdtwApply(x = raster_timeseries, y = temporal_patterns, - overlap = 0.5, weight.fun = log_fun, overwrite = TRUE, format = "GTiff") - -## ----plot-dissmilarity2008, echo = TRUE, eval = TRUE, fig.width = page_width, fig.align = 'center', fig.cap = 'Illustration of the TWDTW dissimilarity from each temporal pattern in 2008. The blue areas are more similar to the pattern and the red areas are less similar to the pattern.', fig.pos = '!ht'---- -plot(x = twdtw_dist, type = "distance") - -## ---- echo = TRUE, eval = TRUE, results = 'markup'------------------------ -land_cover_maps <- - twdtwClassify(twdtw_dist, format = "GTiff", overwrite = TRUE) - -## ----plot-map, echo = TRUE, eval = TRUE, fig.width = page_width, fig.align = 'center', fig.cap = 'Land cover maps for each year from 2008 to 2013.', fig.pos = '!h'---- -plot(x = land_cover_maps, type = "maps") - -## ----plot-area, echo = TRUE, eval = TRUE, fig.width = page_width, fig.align = 'center', fig.cap = 'Percentage of area for each land cover class from 2008 to 2013.', fig.pos = '!h'---- -plot(x = land_cover_maps, type = "area") - -## ----plot-change, echo = TRUE, eval = TRUE, fig.width = page_width, fig.align = 'center', fig.cap = 'Gains and losses in area from the other classes. The $y$ axis shows the actual class; the positive direction of $x$ axis shows the gains and the negative direction of $x$ axis shows the losses of the classes indicated in $y$. Colors indicate which class the gain/losse belong.', fig.pos = '!h'---- -plot(x = land_cover_maps, type = "changes") - -## ----plot-dissmilarity, echo = TRUE, eval = TRUE, fig.width = page_width, fig.align = 'center', fig.cap = 'TWDTW dissimilarity measure for each pixel over each classified period. The blue areas have high confidence and the red areas have low confidence in the classification.', fig.pos = '!h'---- -plot(x = land_cover_maps, type = "distance") - -## ---- echo = TRUE, eval = TRUE-------------------------------------------- -maps_assessment <- twdtwAssess(land_cover_maps, y = validation_samples, - proj4string = proj_str, conf.int = .95) - -## ---- echo = FALSE, eval = TRUE, results = 'asis'------------------------- -twdtwXtable(maps_assessment, table.type = "errormatrix", digits = 0, rotate.col = TRUE, caption = "\\label{tab:map-error-matrix}Error matrix of the map classification based on TWDTW analysis. The area is in the map unit, in this case $m^2$. $w$ is the proportion of area mapped for each class.", comment = FALSE, caption.placement = "bottom", table.placement = "!ht", show.footnote = FALSE) - -## ---- echo = FALSE, eval = TRUE, results = 'asis'------------------------- -twdtwXtable(maps_assessment, table.type = "accuracy", show.prop = TRUE, digits = 2, rotate.col = TRUE, caption = "\\label{tab:map-accuracy}Accuracy and error matrix in proportion of area of the classified map. * 95\\% confidence interval.", comment = FALSE, caption.placement = "bottom", table.placement = "!ht", show.footnote = FALSE) - -## ----plot-map-incorrect-samples, echo = TRUE, eval = TRUE, fig.width = page_width, fig.align = 'center', fig.cap = 'Incorrect classified samples.', fig.pos = '!ht'---- -plot(x = maps_assessment, type = "map", samples = "incorrect") - -## ---- echo = FALSE, eval = TRUE, results = 'asis'------------------------- -twdtwXtable(maps_assessment, table.type = "area", digits = 0, rotate.col = TRUE, caption = "\\label{tab:map-adjusted-area}Mapped and adjusted, accumulated over the whole period, i.e., the sum of the maps from 2008 to 2013. The area is in the map unit, in this case $m^2$. * 95\\% confidence level.", comment = FALSE, caption.placement = "bottom", table.placement = "!ht", show.footnote = FALSE) - -## ----plot-area-and-uncertainty, echo = FALSE, eval = TRUE, fig.width = page_width, fig.height = page_height / 2.7, fig.align = 'center', fig.cap = 'Mapped and adjusted, accumulated over the whole period, i.e., the sum from the sum of the maps from 2008 to 2013. The area is in the map unit, in this case $m^2$.', fig.pos = '!ht'---- -plot(x = maps_assessment, type = "area", perc = FALSE) + - ylab(expression(paste("Area", m^2, sep = " "))) - diff --git a/vignettes/dtwSat.tex b/vignettes/dtwSat.tex deleted file mode 100644 index ba803da..0000000 --- a/vignettes/dtwSat.tex +++ /dev/null @@ -1,1478 +0,0 @@ -\documentclass[article,shortnames]{jss} -\usepackage[utf8]{inputenc} - -\providecommand{\tightlist}{% - \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} - -\author{ -Victor Maus\\University of Münster \And Gilberto Câmara\\INPE \And Marius Appel\\University of Münster \And Edzer Pebesma\\University of Münster -} -\title{\pkg{dtwSat}: Time-Weighted Dynamic Time Warping for Satellite Image -Time Series Analysis in \proglang{R}} - -\Plainauthor{Victor Maus, Gilberto Câmara, Marius Appel, Edzer Pebesma} -\Plaintitle{dtwSat: Time-Weighted Dynamic Time Warping for Satellite Image Time -Series Analysis in R} -\Shorttitle{\pkg{dtwSat}: Time-Weighted Dynamic Time Warping} - -\Abstract{ -The opening of large archives of satellite data such as LANDSAT, MODIS -and the SENTINELs has given researchers unprecedented access to data, -allowing them to better quantify and understand local and global land -change. The need to analyse such large data sets has lead to the -development of automated and semi-automated methods for satellite image -time series analysis. However, few of the proposed methods for remote -sensing time series analysis are available as open source software. In -this paper we present the \proglang{R} package \pkg{dtwSat}. This -package provides an implementation of the Time-Weighted Dynamic Time -Warping method for land cover mapping using sequence of multi-band -satellite images. Methods based on dynamic time warping are flexible to -handle irregular sampling and out-of-phase time series, and they have -achieved significant results in time series analysis. \pkg{dtwSat} is -available from the Comprehensive R Archive Network and contributes to -making methods for satellite time series analysis available to a larger -audience. The package supports the full cycle of land cover -classification using image time series, ranging from selecting temporal -patterns to visualising and assessing the results. -} - -\Keywords{dynamic programming, MODIS time series, land cover changes, crop monitoring} -\Plainkeywords{dynamic programming, MODIS time series, land cover changes, crop monitoring} - -%% publication information -%% \Volume{50} -%% \Issue{9} -%% \Month{June} -%% \Year{2012} -%% \Submitdate{} -%% \Acceptdate{2012-06-04} - -\Address{ - Victor Maus\\ - University of Münster\\ - Institute for Ecological Economics\newline Vienna University of - Economics and Business\newline Welthandelsplatz 1\newline 1020 Wien, - Austria\\ - E-mail: \href{mailto:vwmaus1@gmail.com}{\nolinkurl{vwmaus1@gmail.com}}\\ - URL: \url{www.victor-maus.com}\\~\\ - } - -% Pandoc header - -\usepackage{amsmath} \usepackage{array} \usepackage{caption} \usepackage{subcaption} \usepackage{float} \usepackage{microtype} - -\setlength{\tabcolsep}{4pt} - -\usepackage{xcolor} \usepackage[printwatermark]{xwatermark} - -\begin{document} - -\begin{CodeChunk} - -\begin{CodeOutput} -Warning in fun(libname, pkgname): - -tikzDevice: No appropriate LaTeX compiler could be found. -Access to LaTeX is required in order for the TikZ device -to produce output. - -The following places were tested for a valid LaTeX compiler: - - the global option: tikzLatex - the environment variable: R_LATEXCMD - the environment variable: R_PDFLATEXCMD - the global option: latexcmd - the PATH using the command: pdflatex - the PATH using the command: latex - the PATH using the command: /usr/texbin/pdflatex - -If you have a working LaTeX compiler, try one of the -following solutions: - - Set the path to your compiler as the value of either latexcmd or - tikzLatex in .Rprofile using options(). - - Set the path to your compiler as the value of either R_LATEXCMD or - R_PDFLATEXCMD in .Renviron. - - Ensure the folder containing your compiler is included in PATH. -\end{CodeOutput} -\end{CodeChunk} - -\newwatermark[allpages,color=gray!25,angle=45,scale=1.5,xpos=0,ypos=0]{Conditionally accepted} -\sloppy - -\hypertarget{introduction}{% -\section{Introduction}\label{introduction}} - -Remote sensing images are the most widely used data source for measuring -land use and land cover change (LUCC). In many areas, remote sensing -images are the only data available for this purpose -\citep{Lambin:2006, Fritz:2013}. Recently, the opening of large archives -of satellite data such as LANDSAT, MODIS and the SENTINELs has given -researchers unprecedented access to data, allowing them to better -quantify and understand local and global land change. The need to -analyse such large data sets has lead to the development of automated -and semi-automated methods for satellite image time series analysis. -These methods include multi-image compositing \citep{Griffiths:2013}, -detecting forest disturbance and recovery -\citep{Kennedy:2010, Zhu:2012, DeVries:2015}, crop classification -\citep{Xiao:2005, Wardlow:2007, Petitjean:2012, Maus:2016}, planted -forest mapping \citep{Maire:2014}, crop expansion and intensification -\citep{Galford:2008, Sakamoto:2009}, detecting trend and seasonal -changes -\citep{Lunetta:2006, Verbesselt:2010, Verbesselt:2010a, Verbesselt:2012}, -and extracting seasonality metrics from satellite time series -\citep{Jonsson:2002, Jonsson:2004}. Given the open availability of large -image data sets, the Earth Observation community would get much benefit -from methods that are openly available, reproducible and comparable. -However, few of the proposed methods for remote sensing time series -analysis are available as open source software, the main exception being -the BFAST and BFAST-monitor algorithms for change detection -\citep{Verbesselt:2010, Verbesselt:2010a}. This paper is a contribution -to making methods for satellite time series analysis available to a -larger audience. - -In this paper we describe the \pkg{dtwSat} package, written in -\proglang{R} \citep{R:2015} and \proglang{Fortran} programming -languages, and available from the Comprehensive R Archive Network at -\url{http://CRAN.R-project.org/package=dtwSat}. The package provides an -implementation of Time-Weighted Dynamic Time Warping (TWDTW) -\citep{Maus:2016} for satellite image time series analysis. - -The TWDTW method is an adaptation of the well-known dynamic time warping -(DTW) method for time series analysis -\citep{Velichko:1970, Sakoe:1971, Sakoe:1978, Rabiner:1993, Berndt:1994, Keogh:2005, Muller:2007} -for land cover classification. The standard DTW compares a temporal -signature of a known event (\emph{e.g.}, a person's speech) with an -unknown time series. It finds all possible alignments between two time -series and provides a dissimilarity measure \citep{Rabiner:1993}. In -contrast to standard DTW, the TWDTW method is sensitive to seasonal -changes of natural and cultivated vegetation types. It also considers -inter-annual climatic and seasonal variability. In a tropical forest -area, the method has achieved a high accuracy for mapping classes of -single cropping, double cropping, forest, and pasture \citep{Maus:2016}. - -We chose \proglang{R} because it is an open source software that offers -a large number of reliable packages. The \pkg{dtwSat} package builds -upon on a number of graphical and statistical tools in \proglang{R}: -\pkg{dtw} \citep{Giorgino:2009}, \pkg{proxy} \citep{Meyer:2015}, -\pkg{zoo} \citep{Zeileis:2005}, \pkg{mgcv} -\citep{Wood:2000, Wood:2003, Wood:2004, Wood:2006, Wood:2011}, \pkg{sp} -\citep{Pebesma:2005, Bivand:2013}, \pkg{raster} \citep{Hijmans:2015}, -\pkg{caret} \citep{Kuhn:2016}, and \pkg{ggplot2} \citep{Wickham:2009}. -Other \proglang{R} packages that are related and useful for remote -sensing and land cover analysis include \pkg{landsat} -\citep{Goslee:2011}, \pkg{rgdal} \citep{Bivand:2015}, \pkg{spacetime} -\citep{Pebesma:2012, Bivand:2013}, \pkg{bfast} -\citep{Verbesselt:2010, Verbesselt:2010a}, \pkg{bfastmonitor} -\citep{Verbesselt:2011}, \pkg{bfastSpatial} \citep{Dutrieux:2014}, -\pkg{MODISTools} \citep{Tuck:2014}, \pkg{maptools} \citep{Bivand:2015}, -and \pkg{lucc} \citep{Moulds:2015}. Using existing packages as building -blocks, software developers in \proglang{R} save a lot of time and can -concentrate on their intended goals. - -There is already an \proglang{R} package that implements the standard -DTW method for time series analysis: the \pkg{dtw} package -\citep{Giorgino:2009}. In the \pkg{dtwSat} package, we focus on the -specific case of satellite image time series analysis. The analysis -method implemented in \pkg{dtwSat} package extends that of the \pkg{dtw} -package; it adjusts the standard DTW method to account for the -seasonality of different types of land cover. Our aim is to support the -full cycle of land cover classification, from selecting sample patterns -to visualising and assessing the final result. - -This paper focuses on the motivation and guidance for using the TWDTW -method for remote sensing applications. The full description of the -method is available in a paper published by the lead author -\citep{Maus:2016}. In what follows, the -\autoref{the-time-weighted-dynamic-time-warping-method} describes the -application of TWDTW \citep{Maus:2016} for satellite time series -analysis. The \autoref{dtwsat-package-overview} gives an overview of the -\pkg{dtwSat} package. Then, \autoref{classifying-a-time-series} focuses -on the analysis of a single time series and shows some visualisation -methods. We then present an example of a complete land cover change -analysis for a study area in Mato Grosso, Brazil in -\autoref{producing-a-land-cover-map}. - -\hypertarget{the-time-weighted-dynamic-time-warping-method}{% -\section{The Time-Weighted Dynamic Time Warping -method}\label{the-time-weighted-dynamic-time-warping-method}} - -In this section, we describe the Time-Weighted Dynamic Time Warping -(TWDTW) algorithm in general terms. For a detailed technical -explanation, refer to \citet{Maus:2016}. TWDTW is time-constrained -version of the Dynamic Time Warping (DTW) algorithm. Although the -standard DTW method is good for shape matching \citep{Keogh:2005}, it is -not suited \emph{per se} for satellite image time series analysis, since -it disregards the temporal range when finding the best matches between -two time series \citep{Maus:2016}. When using image time series for land -cover classification, one needs to balance between shape matching and -temporal alignment, since each land cover class has a distinct -phenological cycle associated with the vegetation -\citep[\citet{Zhang:2003}]{Reed:1994}. For example, soybeans and maize -cycles range from 90 to 120 days, whereas sugar-cane has a 360 to 720 -days cycle. A time series with cycle larger than 180 days is unlikely to -come from soybeans or maize. For this reason, \citet{Maus:2016} include -a time constraint in DTW to account for seasonality. The resulting -method is capable of distinguishing different land cover classes. - -The inputs to TWDTW are: (a) a set of time series of known temporal -patterns (\emph{e.g.}, phenological cycles of land cover classes); (b) -an unclassified long-term satellite image time series. For each temporal -pattern, the algorithm finds all matching subintervals in the long-term -time series, providing a dissimilarity measure (cf., -\autoref{fig:twdtw-example}). The result of the algorithm is a set of -subintervals, each associated with a pattern and with a dissimilarity -measure. We then break the unclassified time series in periods according -to our needs (\emph{e.g.}, yearly or monthly). For each period, we -consider all matching subintervals that intersect with it, and classify -them based on the land cover class of the best matching subinterval. In -this way, the long-term satellite time series is divided in periods, and -each period is assigned a land cover class. - -\begin{CodeChunk} -\begin{figure}[!h] - -{\centering \includegraphics{dtwSat_files/figure-latex/twdtw-example-1} - -} - -\caption[Matches of the known temporal pattern to subintervals of the long-term time series]{Matches of the known temporal pattern to subintervals of the long-term time series. The solid black line is the long-term time series, the colored lines are the different matches of the same pattern, and the gray dashed lines are the matching points.}\label{fig:twdtw-example} -\end{figure} -\end{CodeChunk} - -To use TWDTW for land cover classification, we need the following data -sets: - -\begin{itemize} -\item - A set of remote sensing time series for the study area. For example, a - tile of a MODIS MOD13Q1 image consists of 4800 x 4800 pixels, covering - an area of 10 degrees x 10 degrees at the Equator \citep{Didan:2015}. - A 15-year (2000-2015) MODIS MOD13Q1 set time series has 23 images per - year, with a total of 23 million time series, each with 346 samples. -\item - A set of time series with land cover information, called - \emph{temporal patterns}. Typically, each time series is short and - covers one phenological cycle of one land cover type. Examples would - be a time series of a soybean crop, or one that describes a mature - tropical forest. These temporal patterns can be extracted from the - remote sensing image data, if the user knows their spatial and - temporal location. -\item - A set of ground truth points, with spatial and temporal information - and land cover classification. These \emph{ground truth} points are - used for validation and accuracy assessment. -\end{itemize} - -Based on the information provided by the user about the images to be -analysed, our method maps them to a three-dimensional (3-D) array in -space-time (\autoref{fig:3-D-array}). This array can have multiple -attributes, such as the satellite bands (\emph{e.g.}, ``RED'', ``NIR'', -and ``BLUE''), and derived indices (\emph{e.g.}, ``NDVI'', ``EVI'', and -``EVI2''). This way, each pixel location is associated to a sequence of -measurements, building a satellite image time series. -\autoref{fig:3-D-array} shows an example of ``EVI'' time series for a -location in the Brazilian Amazon from 2000 to 2008. In the first two -years, the area was covered by forest that was cut in 2002. The area was -then used for cattle raising (pasture) for three years, and then for -crop production from 2006 to 2008. Satellite image time series are thus -useful to describe the dynamics of the landscape and the land use -trajectories. - -\begin{figure}[!h] -\begin{center} - \includegraphics[width=.49\textwidth]{images_array.pdf} - \includegraphics[width=.49\textwidth]{images_ts.pdf} -\end{center} -\caption{A 3-dimensional array of satellite images (left), an enhanced vegetation index (EVI) time series at the pixel location $(x,y)$ (right). The arrows indicate gaps in the time series. Adapted from \citet{Maus:2016}.} -\label{fig:3-D-array} -\end{figure} - -\hypertarget{dtwsat-package-overview}{% -\section{dtwSat package overview}\label{dtwsat-package-overview}} - -\pkg{dtwSat} provides a set of functions for land cover change analysis -using satellite image time series. This includes functions to build -temporal patterns for land cover types, apply the TWDTW analysis using -different weighting functions, visualise the results in a graphical -interface, produce land cover maps, and create spatiotemporal plots for -land changes. Therefore, \pkg{dtwSat} gives an end-to-end solution for -satellite time series analysis, which users can make a complete land -change analysis. - -For the \pkg{dtwSat} package, the user should provide the following -inputs: - -\begin{itemize} -\item - A set of time ordered satellite images, all with the same spatial - extent. The user should also inform the date of each image. In - \proglang{R} the images should use the \code{RasterBrick} or - \code{RasterStack} class of the \pkg{raster} package. -\item - A list of temporal patterns, each associated to a time series in - \pkg{zoo} format. -\item - A list of known ground truth points, each with spatial and temporal - information, in a format readable in \proglang{R}, such as CSV or - shapefile. -\end{itemize} - -The \pkg{dtwSat} package organizes the data in three \code{S4} classes -of objects: \code{twdtwTimeSeries}, \code{twdtwMatches}, and -\code{twdtwRaster}. To store time series we use the class -\code{twdtwTimeSeries}. The objects of class \code{twdtwTimeSeries} have -two slots; the slot called \code{timeseries} has a list of \code{zoo} -objects; and the slot called \code{labels} stores the labels of the time -series. The class \code{twdtwMatches} has 3 slots to store inputs and -results of the TWDTW analysis. The slots called \code{timeseries} and -\code{patterns} are objects of the class \code{twdtwTimeSeries} with the -unclassified long-term time series and the temporal patterns, -respectively. A third slot called \code{alignments} has a \code{list} -with detailed information about the matches between the patterns and the -unclassified long-term time series. The classes \code{twdtwTimeSeries} -and \code{twdtwMatches} are used to analyse lists of time series. - -The class \code{twdtwRaster} is used for satellite image time series. -This class can store either unclassified raster time series with the -satellite raw data, the results of the TWDTW analyis, or a classified -raster time series. In both cases, the objects of class -\code{twdtwRaster} have five slots. The slot called \code{timeseries} is -a list of \code{RasterBrick} or \code{RasterStack} objects with time -ordered satellite images (all with the same temporal and spatial -extents); the slot called \code{timeline} is a vector of class -\code{Date} with dates of the satellite images; the slot called -\code{layers} has the names of satellite bands; the slot called -\code{levels} has levels for the raster values; and the slot called -\code{labels} has labels for the raster values. This class builds upon -the \proglang{R} package \pkg{raster} to build a multi-attribute 3-D -raster in space-time, allowing for multi-band satellite image time -series analysis. - -\hypertarget{classifying-a-time-series}{% -\section{Classifying a time series}\label{classifying-a-time-series}} - -This section describes how to classify one time series, using examples -that come with the \pkg{dtwSat} package. We will show how to match three -temporal patterns (``soybean'', ``cotton'', and ``maize'') to -subintervals of a long-term satellite image time series. These time -series have been extracted from a set of MODIS MOD13Q1 -\citep{Didan:2015} images and include the vegetation indices ``ndvi'', -``evi'', and the original bands ``nir'', ``red'', ``blue'', and ``mir''. -In this example, the classification of crop types for the long-term time -series is known. - -\hypertarget{input-data}{% -\subsection{Input data}\label{input-data}} - -The inputs for the next examples are time series in \pkg{zoo} format. -The first is an object of class \code{zoo} with a long-term time series, -referred to as \code{MOD13Q1.ts}, and the second is a \code{list} of -time series of class \code{zoo} with the temporal patterns of -``soybean'', ``cotton'', and ``maize'', referred to as -\code{MOD13Q1.patterns.list}. - -From \code{zoo} objects we construct time series of class -\code{twdtwTimeSeries}, for which we have a set of visualization and -analysis methods implemented in the \pkg{dtwSat} package. The code below -builds two objects of class \code{twdtwTimeSeries}. The first has the -long-term time series and second has the temporal patterns. We use the -plot method types \code{timeseries} and \code{patterns} to shown the -objects \code{ts} in \autoref{fig:example-timeseries} and -\code{MOD13Q1.ts} in \autoref{fig:temporal-patterns-soy-cot-mai}, -respectively. This plot method uses \code{ggplot} syntax -\citep{Wickham:2009}. - -\begin{CodeChunk} - -\begin{CodeInput} -R> library(dtwSat) -R> names(MOD13Q1.patterns.list) -\end{CodeInput} - -\begin{CodeOutput} -[1] "Soybean" "Cotton" "Maize" -\end{CodeOutput} - -\begin{CodeInput} -R> head(MOD13Q1.ts, n = 2) -\end{CodeInput} - -\begin{CodeOutput} - ndvi evi red nir blue mir -2009-08-05 0.3169 0.1687 0.1167 0.2250 0.0427 0.2193 -2009-08-28 0.2609 0.1385 0.1168 0.1993 0.0548 0.2657 -\end{CodeOutput} -\end{CodeChunk} - -\begin{CodeChunk} - -\begin{CodeInput} -R> ts <- twdtwTimeSeries(MOD13Q1.ts, labels = "Time series") -R> patterns_ts <- twdtwTimeSeries(MOD13Q1.patterns.list) -R> patterns_ts -\end{CodeInput} - -\begin{CodeOutput} -An object of class "twdtwTimeSeries" -Slot "timeseries" length: 3 -Slot "labels": [1] "Soybean" "Cotton" "Maize" -\end{CodeOutput} -\end{CodeChunk} - -\begin{CodeChunk} - -\begin{CodeInput} -R> plot(ts, type = "timeseries") + annotate(geom = "text", -R+ x = MOD13Q1.ts.labels$from + 90, y = 0.98, -R+ label = MOD13Q1.ts.labels$label, size = 2) -\end{CodeInput} -\begin{figure}[!h] - -{\centering \includegraphics{dtwSat_files/figure-latex/example-timeseries-1} - -} - -\caption{Example of time series based on MODIS product MOD13Q1 \citep{Friedl:2010}. The labels of the phenological cycle are shown in the plot.}\label{fig:example-timeseries} -\end{figure} -\end{CodeChunk} - -\begin{CodeChunk} - -\begin{CodeInput} -R> plot(patterns_ts, type = "patterns") -\end{CodeInput} -\begin{figure}[!h] - -{\centering \includegraphics{dtwSat_files/figure-latex/temporal-patterns-soy-cot-mai-1} - -} - -\caption{Temporal patterns of soybean, cotton, and maize based on MODIS product MOD13Q1 \citep{Friedl:2010}.}\label{fig:temporal-patterns-soy-cot-mai} -\end{figure} -\end{CodeChunk} - -TWDTW uses both amplitude and phase information to classify the -phenological cycles in the long-term time series. The differences in the -amplitude and phase of the cycles are more clear when we observe the EVI -signal in Figures \ref{fig:example-timeseries} and -\ref{fig:temporal-patterns-soy-cot-mai}. The EVI peak of the ``soybean'' -time series has a similar amplitude as that of ``cotton''. However, the -``soybean'' series peaks in late December while the ``cotton'' series -peaks in early April. The EVI peak of the ``maize'' time series is at -the same period as the peak of ``cotton''. However, the ``maize'' time -series has smaller amplitude than the ``cotton'' one. Therefore, -combining shape and time information we can improve the time series -classification. \goodbreak - -\hypertarget{detection-of-time-series-patterns-with-twdtw}{% -\subsection{Detection of time series patterns with -TWDTW}\label{detection-of-time-series-patterns-with-twdtw}} - -Each subinterval of the long-term time series in \code{ts} has a known -phenological cycle. We will now compare the known information with the -result of the TWDTW algorithm. We use the function \code{twdtwApply} -that returns an \proglang{R} object of class \code{twdtwMatches} with -all matches of each temporal pattern in the time series. - -\begin{CodeChunk} - -\begin{CodeInput} -R> log_weight <- logisticWeight(alpha = -0.1, beta = 100) -R> matches <- -R+ twdtwApply(x = ts, y = patterns_ts, weight.fun = log_weight, keep = TRUE) -R> slotNames(matches) -\end{CodeInput} - -\begin{CodeOutput} -[1] "timeseries" "patterns" "alignments" -\end{CodeOutput} - -\begin{CodeInput} -R> show(matches) -\end{CodeInput} - -\begin{CodeOutput} -An object of class "twdtwMatches" -Number of time series: 1 -Number of alignments: 27 -Patterns labels: Soybean Cotton Maize -\end{CodeOutput} -\end{CodeChunk} - -To retrieve the complete information of the matches we set -\code{keep = TRUE}. We need this information for the plot methods of the -class \code{twdtwMatches}. The argument \code{weight.fun} defines the -time-weight to the dynamic time warping analysis \citep{Maus:2016}. By -default the time-weight is zero, meaning that the function will run a -standard dynamic time warping analysis. The arguments \code{x} and -\code{y} are objects of class \code{twdtwTimeSeries} with the -unclassified long-term time series and the temporal patterns, -respectively. To perform the alignment between the time series the -default TWDTW recursion has a symmetric step (for more details and other -recursion options see \code{?stepPattern}). \citet{Giorgino:2009} -provides a detaild discussion on the recursion steps and other step -patterns. For further details and other arguments of the TWDTW analysis -see \code{?twdtwApply}. - -In our example we use a logistic weight function for the temporal -constraint of the TWDTW algorithm. This function is defined by -\code{logisticWeight}. The \pkg{dtwSat} package provides two in-built -functions: \code{linearWeight} and \code{logisticWeight}. The -\code{linearWeight} function with slope \code{a} and intercept \code{b} -is given by \[ - \omega = a \cdot g(t_1,t_2) + b, - \label{eq:lineartw} -\] and the \code{logisticWeight} with midpoint \code{beta}, and -steepness \code{alpha}, given by \[ - \omega = \frac{1}{1 + e^{-\alpha(g(t_1,t_2)-\beta)} }. - \label{eq:nonlineartw} -\] The function \(g\) is the absolute difference in days between two -dates, \(t_1\) and \(t_2\). The aim of these functions is to control the -time warp, e.g., a ``large time warp'' is needed to match a point of the -temporal pattern whose original date is January 1 to a point of the -long-term time series whose date is July 1, on the other hand to match -January 1 to December 15 has a ``small time warp''. If there is a large -seasonal difference between the pattern and its matching point in time -series, an extra cost is added to the DTW distance measure. This -constraint controls the time warping and makes the time series alignment -dependent on the seasons. This is especially useful for detecting -temporary crops and for distinguishing pasture from agriculture. The -linear function creates a strong time constraint even for small time -differences, including small time warps. The logistic function has a low -weight for small time warps and significant costs for bigger time warps, -cf., \autoref{fig:logist-time-weight}. In our previous studies -\citep{Maus:2016} the logistic-weight had better results than the -linear-weight for land cover classification. Users can define different -weight functions as temporal constraints in the argument -\code{weight.fun} of the function \code{twdtwApply}. - -\begin{CodeChunk} -\begin{figure}[!h] - -{\centering \includegraphics[width=2.7952755in]{dtwSat_files/figure-latex/logist-time-weight-1} - -} - -\caption{Logistic time-weight function \code{logisticWeight} with steepness \code{alpha = -0.1} and midpoint \code{beta = 100}. The $x$ axis shows the absolute difference between two dates in days and the $y$ axis shows the time-weight \citep{Maus:2016}.}\label{fig:logist-time-weight} -\end{figure} -\end{CodeChunk} - -\hypertarget{visualising-the-result-of-the-twdtw-algorithm}{% -\subsection{Visualising the result of the TWDTW -algorithm}\label{visualising-the-result-of-the-twdtw-algorithm}} - -\pkg{dtwSat} provides five ways to visualise objects of class -\code{twdtwMatches} through the plot types: \code{matches}, -\code{alignments}, \code{classification}, \code{path}, and \code{cost}. -The plot type \code{matches} shows the matching points of the patterns -in the long-term time series; the plot type \code{alignments} shows the -alignments and dissimilarity measures; the plot type \code{path} shows -the low cost paths in the TWDTW cost matrix; and the plot type -\code{cost} allows the visualisation of the cost matrices (local cost, -accumulated cost, and time cost); and the plot type -\code{classification} shows the classification of the long-term time -series based on the TWDTW analysis. The plot methods for class -\code{twdtwMatches} return a \code{ggplot} object, so that users can -further manipulate the result using the \pkg{ggplot2} package. For more -details on visualisation functions, please refer to the \pkg{dtwSat} -documentation in the CRAN \citep{Maus:2015a}. - -We now describe the plot types \code{matches} and \code{alignments}. The -code bellow shows how to visualise the matching points of the four best -matches of ``soybean'' pattern in the long-term time series, cf., -\autoref{fig:twdtw-matches}. - -\begin{CodeChunk} - -\begin{CodeInput} -R> plot(matches, type = "matches", patterns.labels = "Soybean", k = 4) -\end{CodeInput} -\begin{figure}[!h] - -{\centering \includegraphics{dtwSat_files/figure-latex/twdtw-matches-1} - -} - -\caption[The four best matches of the "soybean" pattern in the time series using a logistic time-weight]{The four best matches of the "soybean" pattern in the time series using a logistic time-weight. The solid black line is the long-term time series; the coloured lines are the temporal patterns; and the grey dashed lines are the respective matching points.}\label{fig:twdtw-matches} -\end{figure} -\end{CodeChunk} - -The next example uses the plot type \code{alignments} to show the -alignments of the temporal patterns (see -\autoref{fig:alignments-all-patterns}). We set the threshold for the -dissimilarity measure to be lower than \(3.0\). This plot displays the -different subintervals of the long-term time series that have alignments -whose dissimilarity is less than the specified threshold. - -\begin{CodeChunk} - -\begin{CodeInput} -R> plot(matches, type = "alignments", attr = "evi", threshold = 3.0) -\end{CodeInput} -\begin{figure}[!h] - -{\centering \includegraphics{dtwSat_files/figure-latex/alignments-all-patterns-1} - -} - -\caption[Alignments and dissimilarity measures of the patterns "soybean", "cotton", and "maize" to the subintervals of the long-term time series using a logistic time-weight]{Alignments and dissimilarity measures of the patterns "soybean", "cotton", and "maize" to the subintervals of the long-term time series using a logistic time-weight. The solid black line is the EVI time series, and the coloured lines are the alignments of the patterns that have dissimilarity measure lower than three.}\label{fig:alignments-all-patterns} -\end{figure} -\end{CodeChunk} - -\autoref{fig:alignments-all-patterns} shows the alignments of each -pattern over the long-term time series, note that we can rank the -alignments by their TWDTW dissimilarity, i.e., alignments overlapping -the same period usually have distinct dissimilarity, which can be used -to rank them. In the figure we can see that maize (blue lines) and -cotton (green lines) overlap approximately the same time periods, -however, they have distinct dissimilarity measures, and therefore, can -be ranked. Observing the time period from January 2010 to July 2010, -both soybean, maize, and cotton have at least one overlapping alignment, -however in this case the cotton pattern matches better to the interval -because its dissimilarity is lower than the others. - -\hypertarget{classifying-the-long-term-time-series}{% -\subsection{Classifying the long-term time -series}\label{classifying-the-long-term-time-series}} - -Using the matches and their associated dissimilarity measures, we can -classify the subintervals of the long-term time series using -\code{twdtwClassify}. To do this, we need to define a period for -classification and the minimum overlap between the period and the -alignments that intersect with it. For each interval, -\code{twdtwClassify} will select the alignment that has the lowest TWDTW -dissimilarity taking into account the minimum overlap condition. For -example, in \autoref{fig:alignments-all-patterns} the interval from 1 -September 2012 to 1 March 2013 has three overlapping alignments, maize -in blue, cotton in green, and soybean in red. Without a minimum overlap -the function \code{twdtwClassify} would classify this interval as maize, -which has the lowest dissimilarity in the period. However, if we set a -minimum overlap of 50\%, the function \code{twdtwClassify} classifies -the interval as soybean, which is the only class whose alignment -overlaps the interval during more than 50\% of the time. The interval of -classification are usually defined according to the phenological cycles -or the agricultural calendar of the region. The classification interval -can also be irregular, for details see the argument \code{breaks} in -\code{?twdtwClassify}. - -In the example bellow we classify each period of 6 months from September -2009 to September 2013; we set a minimum overlap of 50\% between the -alignment and the classification period. This means that at least 50\% -of the alignment has to be contained inside of the classification -period. We also use the plot type \code{classification} to show the -classified subintervals of the long-term time series. - -\begin{CodeChunk} - -\begin{CodeInput} -R> ts_classification <- twdtwClassify(x = matches, -R+ from = as.Date("2009-09-01"), to = as.Date("2013-09-01"), -R+ by = "6 month", overlap = 0.5) -R> plot(ts_classification, type = "classification") -\end{CodeInput} -\begin{figure}[!ht] - -{\centering \includegraphics{dtwSat_files/figure-latex/time-series-classification-1} - -} - -\caption[Classification of each 6 months periods of the time series using results of the TWDTW analysis with logistic time-weight]{Classification of each 6 months periods of the time series using results of the TWDTW analysis with logistic time-weight. The solid lines are the attributes of the time series, the background colours indicate the classification of the periods.}\label{fig:time-series-classification} -\end{figure} -\end{CodeChunk} - -By comparing the results of the classified time series in -\autoref{fig:time-series-classification} with the crop cycles in -\autoref{fig:example-timeseries} we see that the algorithm has -classified correctly all the eight subintervals from 2009 to 2013, which -are, respectively: ``Soybean'', ``Cotton'', ``Soybean'', ``Cotton'', -``Soybean'', ``Maize'', ``Soybean'', ``Maize''. - -\hypertarget{producing-a-land-cover-map}{% -\section{Producing a land cover map}\label{producing-a-land-cover-map}} - -In this section we present an application of TWDTW for land cover change -analysis using satellite image time series. Our input is a set of -images, each covering the same geographical area at different times. -Each pixel location is then associated to an unclassified satellite -image time series. We assume to have done field work in the area; for -some pixel locations and time periods, we know what is the land cover. -We then will show how to obtain a set of template patterns, based on the -field samples and how to apply these patterns to land cover -classification of the set of images. In the end of this section we show -how to use \pkg{dtwSat} for land cover change analysis and accuracy -assessment. - -As an example we classify approximately 5300 km\(^2\) in a tropical -forest region in Mato Grosso, Brazil (\autoref{fig:study-area}). This is -a sequence of 160 images with 999 pixels each for 6 years, from 2007 to -2013. We also have a set of 603 ground truth samples of the following -classes: ``Forest'', ``Cotton-fallow'', ``Soybean-cotton'', -``Soybean-maize'', and ``Soybean-millet''. The satellite images and the -field samples used in the examples come with \pkg{dtwSat} package. - -\begin{figure}[!ht] -\begin{center} - \includegraphics[width=\textwidth]{study_area.pdf} -\end{center} -\caption{Study area in Mato Grosso, Brazil, shown in a \copyright\ Google Earth image. The area was originally covered by tropical forest that has been removed for agricultural use.} -\label{fig:study-area} -\end{figure} - -\hypertarget{input-data-1}{% -\subsection{Input data}\label{input-data-1}} - -The inputs are: \emph{a)} the satellite images for a given geographical -area, organised as a set of georeferenced raster files in GeoTIFF -format, each containing all time steps of a spectral band or index; and -\emph{b)} a set of ground truth samples. The satellite images are -extracted from the MODIS product MOD13Q1 collection 5 \citep{Didan:2015} -and include vegetation indices ``ndvi'', ``evi'', and original bands -``nir'', ``red'', ``blue'', and ``mir''. This product has 250 x 250 m -spatial resolution and a 16 day maximum-value composite (MVC) for each -pixel location \citep{Didan:2015}, meaning that one image can have -measurements from different dates. For this reason, MOD13Q1 also -includes the ``day of the year'' (doy) of each pixel as a layer, which -we use to keep the time series consistent with the measurements. - -The data files for the examples that follow are in the \pkg{dtwSat} -installation folder \emph{lucc\_MT/data/}. The \emph{tif} files include -the time series of ``blue'', ``red'', ``nir'', ``mir'', ``evi'', -``ndvi'', and ``doy'' (day of the year); the text file \emph{timeline} -has the dates of the satellite images; the CSV file \emph{samples.csv} -has the \code{longitude}, \code{latitude}, \code{from}, \code{to}, and -\code{label} for each field sample; and the text file -\emph{samples\_projection} contains information about the cartographic -projection of the samples, in the format of coordinate reference system -used by \code{sp::CRS}. - -\begin{CodeChunk} - -\begin{CodeInput} -R> data_folder <- system.file("lucc_MT/data", package = "dtwSat") -R> dir(data_folder) -\end{CodeInput} - -\begin{CodeOutput} - [1] "blue.tif" "doy.tif" "evi.tif" - [4] "mir.tif" "ndvi.tif" "nir.tif" - [7] "red.tif" "samples_projection" "samples.csv" -[10] "timeline" -\end{CodeOutput} -\end{CodeChunk} - -We have stored all the time series for each band in one single file. In -this way, we can use the function \code{raster::brick} to read the -satellite images. The algorithm also works when the time steps for each -band are split in many files. In this case, the user should call the -function \code{raster::stack} with the appropriate parameters. Because -of processing performance, we suggest that interested users group their -images in bricks and follow the procedures given below. - -\begin{CodeChunk} - -\begin{CodeInput} -R> blue <- brick(paste(data_folder, "blue.tif", sep = "/")) -R> red <- brick(paste(data_folder, "red.tif", sep = "/")) -R> nir <- brick(paste(data_folder, "nir.tif", sep = "/")) -R> mir <- brick(paste(data_folder, "mir.tif", sep = "/")) -R> evi <- brick(paste(data_folder, "evi.tif", sep = "/")) -R> ndvi <- brick(paste(data_folder, "ndvi.tif", sep = "/")) -R> day_of_year <- brick(paste(data_folder, "doy.tif", sep = "/")) -R> dates <- scan(paste(data_folder, "timeline", sep = "/"), what = "dates") -\end{CodeInput} -\end{CodeChunk} - -We use these data-sets to create a multiple raster time series, which is -used in the next sections for the TWDTW analysis. \pkg{dtwSat} provides -the constructor \code{twdtwRaster} that builds a multi-band satellite -image time series. The inputs of this function are \code{RasterBrick} -objects with the same temporal and spatial extents, and a vector -(\code{timeline}) with the acquisition dates of the images in the format -\code{"YYYY-MM-DD"}. The argument \code{doy} is combined with -\code{timeline} to get the real date of each pixel, independently from -each other. If \code{doy} is not provided then the dates of the pixels -are given by \code{timeline}, i.e., all pixels in one image will have -the same date. Products from other sensors, such as the Sentinels and -Landsat, usually have all pixels with same date, therefore the argument -\code{doy} is not needed. This function produces an object of class -\code{twdtwRaster} with the time series of multiple satellite bands. - -\begin{CodeChunk} - -\begin{CodeInput} -R> raster_timeseries <- twdtwRaster(blue, red, nir, mir, evi, ndvi, -R+ timeline = dates, doy = day_of_year) -\end{CodeInput} -\end{CodeChunk} - -Our second input is a set of ground truth samples in the CSV file -\emph{samples.csv}, which has a total of 603 samples divided in five -classes: 68 ``cotton-fallow'', 138 ``forest'', 79 ``soybean-cotton'', -134 ``soybean-maize'', and 184 ``soybean-millet''. Reading this CSV -file, we get a \code{data.frame} object, with the spatial location -(\code{latitude} and \code{longitude}), starting and ending dates -(\code{from} and \code{to}), and the \code{label} for each sample. - -\begin{CodeChunk} - -\begin{CodeInput} -R> field_samples <- read.csv(paste(data_folder, "samples.csv", sep = "/")) -R> head(field_samples, 5) -\end{CodeInput} - -\begin{CodeOutput} - longitude latitude from to label -1 -55.98819 -12.03646 2011-09-01 2012-09-01 Cotton-fallow -2 -55.99118 -12.04062 2011-09-01 2012-09-01 Cotton-fallow -3 -55.98606 -12.03646 2011-09-01 2012-09-01 Cotton-fallow -4 -55.98562 -12.03437 2011-09-01 2012-09-01 Cotton-fallow -5 -55.98475 -12.03021 2011-09-01 2012-09-01 Cotton-fallow -\end{CodeOutput} - -\begin{CodeInput} -R> table(field_samples[["label"]]) -\end{CodeInput} - -\begin{CodeOutput} - - Cotton-fallow Forest Soybean-cotton Soybean-maize Soybean-millet - 68 138 79 134 184 -\end{CodeOutput} - -\begin{CodeInput} -R> proj_str <- scan(paste(data_folder, "samples_projection", sep = "/"), -R+ what = "character") -R> proj_str -\end{CodeInput} - -\begin{CodeOutput} -[1] "+proj=longlat +datum=WGS84 +no_defs +ellps=WGS84 +towgs84=0,0,0" -\end{CodeOutput} -\end{CodeChunk} - -\hypertarget{assessing-the-separability-of-temporal-patterns}{% -\subsection{Assessing the separability of temporal -patterns}\label{assessing-the-separability-of-temporal-patterns}} - -The classification is highly dependent on the quality of the temporal -patterns. Therefore, it is useful to perform an analysis to assess the -separability of the temporal pattern. Ideally, one would need patterns -that, when applied to the set of unknown time series, produce consistent -results (see the guidelines for single time series analysis in -\autoref{classifying-a-time-series}). For this reason, before performing -the land cover mapping, we perform a cross validation step. In this way, -the users would assess the separability of their patterns before -classifying a large data set. - -In the next example we use the function \code{getTimeSeries} to extract -the time series of each field sample from our raster time series. The -arguments of the function are a set of raster time series, a -\code{data.frame} with spatial and temporal information about the fields -samples (as in the object \code{field_samples} given above), and a -\code{proj4string} with the projection information. The projection -should follow the \code{sp::CRS} format. The result is an object of -class \code{twdtwTimeSeries} with one time series for each field sample. - -\begin{CodeChunk} - -\begin{CodeInput} -R> field_samples_ts <- getTimeSeries(raster_timeseries, -R+ y = field_samples, proj4string = proj_str) -R> field_samples_ts -\end{CodeInput} - -\begin{CodeOutput} -An object of class "twdtwTimeSeries" -Slot "timeseries" length: 603 -Slot "labels": [1] "Cotton-fallow" "Cotton-fallow" "Cotton-fallow" -\end{CodeOutput} -\end{CodeChunk} - -To perform the cross-validation we use the function -\code{twdtwCrossValidate}. This function splits the sample time series -into training and validation sets using stratified sampling with a -simple random sampling within each stratum, for details see -\code{?caret::createDataPartition}. The function uses the training -samples to create the temporal patterns and then classifies the -remaining validation samples using \code{twdtwApply}. The results of the -classification are used in the accuracy calculation. - -A Generalized Additive Model (GAM) -\citep[\citet{Wood:2011}]{Hastie:1986} generates the smoothed temporal -patterns based on the training samples. We use the GAM because of its -flexibility for non-parametric fits, with less rigorous assumptions on -the relationship between response and predictor. This potentially -provides better fit to satellite data than purely parametric models, due -to the data's inter- and intra-annual variability. - -In the next example we set the arguments \code{times = 100} and -\code{p = 0.1}, which creates 100 different data partitions, each with -10\% of the samples for training and 90\% for validation. The other -arguments of this function are: the logistic weight function with -steepness \texttt{-0.1} and midpoint \texttt{50} to \code{weight.fun}; -the frequency of the temporal patterns to 8 days \code{freq = 8}, and -GAM smoothing formula to \code{formula = y ~ s(x)}, where function -\code{s} sets up a spline model, with \code{x} the time and \code{y} a -satellite band (for details see \code{?mgcv::gam} and \code{?mgcv::s}). -The output is an object of class \code{twdtwCrossValidation} which -includes the accuracy for each data partition. The object has two slots, -the first called \code{partitions} has the index of the samples used for -training, the second called \code{accuracy} has overall accuracy, user's -accuracy, producer's accuracy, error matrix, and the data used in the -calculation, i.e., reference classes, predicted classes, and TWDTW -distance measure. - -\begin{CodeChunk} - -\begin{CodeInput} -R> set.seed(1) -R> log_fun <- logisticWeight(alpha = -0.1, beta = 50) -R> cross_validation <- twdtwCrossValidate(field_samples_ts, -R> times = 100, p = 0.1, freq = 8, formula = y ~ s(x, bs = "cc"), -R> weight.fun = log_fun) -\end{CodeInput} -\end{CodeChunk} - -\autoref{fig:plot-accuracy} and \autoref{tab:cross-validation} show the -95\% confidence interval of the mean for user's and producer's accuracy -derived from the hundred-fold cross-validation analysis. The user's -accuracy gives the confidence and the producer's accuracy gives the -sensitivity of the method for each class. In our analysis all classes -had high user's and producer's accuracy, meaning that TWDTW has high -confidence and sensitivity for the classes included in the analysis. The -cross-validation results show that if we randomly select 10\% of our -samples to create temporal patterns we can get an overall accuracy of at -least 97\% in the classification of the remaining samples with 95\% -confidence level. - -\begin{table}[!ht] -\centering -\begin{tabular}{rlllllllll} - \hline - & \multicolumn{3}{c}{User's} & \multicolumn{3}{c}{Producer's} & \multicolumn{3}{c}{Overall}\\ -\multicolumn{1}{c}{Class} & \multicolumn{1}{c}{$\mu$} & \multicolumn{1}{c}{$\sigma$} & \multicolumn{1}{c}{ci*} & \multicolumn{1}{c}{$\mu$} & \multicolumn{1}{c}{$\sigma$} & \multicolumn{1}{c}{ci*} & \multicolumn{1}{c}{$\mu$} & \multicolumn{1}{c}{$\sigma$} & \multicolumn{1}{c}{ci*}\\ - \hline -Cotton-fallow & 0.96 & (0.01) & [0.96-0.96] & 1.00 & (0.00) & [1.00-1.00] & 0.98 & (0.02) & [0.97-0.98] \\ - Forest & 1.00 & (0.00) & [1.00-1.00] & 1.00 & (0.00) & [1.00-1.00] & & & \\ - Soybean-cotton & 0.99 & (0.03) & [0.98-1.00] & 0.89 & (0.02) & [0.89-0.89] & & & \\ - Soybean-maize & 0.94 & (0.05) & [0.93-0.95] & 1.00 & (0.01) & [1.00-1.00] & & & \\ - Soybean-millet & 1.00 & (0.01) & [1.00-1.00] & 0.98 & (0.05) & [0.96-0.99] & & & \\ - \hline -\end{tabular} -\caption{\label{tab:cross-validation} User's and producer's accuracy of the TWDTW cross-validation using 100 resampling-with-replacement. The table shows the standard deviation ($\sigma$) and the 95\% confidence interval (ci) of the mean ($\mu$).} -\end{table} - -\begin{CodeChunk} - -\begin{CodeInput} -R> plot(cross_validation, conf.int = .95) + -R+ geom_jitter(size = 0.2, width = 0.1) -\end{CodeInput} -\begin{figure}[!ht] - -{\centering \includegraphics{dtwSat_files/figure-latex/plot-accuracy-1} - -} - -\caption[User's and producer's accuracy of the TWDTW cross-validation using 100 resampling-with-replacement]{User's and producer's accuracy of the TWDTW cross-validation using 100 resampling-with-replacement. The plot shows the 95\% confidence interval of the mean.}\label{fig:plot-accuracy} -\end{figure} -\end{CodeChunk} - -\hypertarget{creating-temporal-patterns}{% -\subsection{Creating temporal -patterns}\label{creating-temporal-patterns}} - -In the last section we observed that the land cover classes based on our -samples are separable using the TWDTW algorithm with high confidence -level. Now we randomly select 10\% of our samples for training and keep -the remaining 90\% for validation. The first set of samples are used to -create temporal patterns and classify the raster time series, and the -second set of samples to assess the final maps. Ideally we would need a -second independent set of samples to assess the map, but it would be -very difficult to identify different crops without field work. -Therefore, we use the same samples used in the cross-validation (section -\ref{assessing-the-separability-of-temporal-patterns}). - -\begin{CodeChunk} - -\begin{CodeInput} -R> library(caret) -R> set.seed(1) -R> I <- unlist(createDataPartition(field_samples[ , "label"], p = 0.1)) -R> training_ts <- subset(field_samples_ts, I) -R> validation_samples <- field_samples[-I, ] -\end{CodeInput} -\end{CodeChunk} - -We use the function \code{createPatterns} to produce the temporal -patterns based on the training samples. For that, we need to set the -desired temporal frequency of the patterns and the smoothing function -for the GAM model. In the example below, we set \code{freq = 8} to get -temporal patterns with a frequency of 8 days, and the GAM smoothing -formula \code{formula = y ~ s(x)}, such as in section -\ref{assessing-the-separability-of-temporal-patterns}). - -\begin{CodeChunk} - -\begin{CodeInput} -R> temporal_patterns <- -R+ createPatterns(training_ts, freq = 8, formula = y ~ s(x)) -\end{CodeInput} -\end{CodeChunk} - -The result of the function \code{createPatterns} is an object of the -class \code{twdtwTimeSeries}. We use the plot method -\code{type = "patterns"} to show the results of the -\code{createPatterns} in \autoref{fig:temporal-patterns}. - -\begin{CodeChunk} - -\begin{CodeInput} -R> plot(temporal_patterns, -R+ type = "patterns") + theme(legend.position = c(.8, .21)) -\end{CodeInput} -\begin{figure}[!h] - -{\centering \includegraphics{dtwSat_files/figure-latex/temporal-patterns-1} - -} - -\caption[Temporal patterns of Forest, Cotton-fallow, Soybean-cotton, Soybean-maize, and Soybean-millet based on the ground truth samples]{Temporal patterns of Forest, Cotton-fallow, Soybean-cotton, Soybean-maize, and Soybean-millet based on the ground truth samples.}\label{fig:temporal-patterns} -\end{figure} -\end{CodeChunk} - -Our method is not restricted to cases where the temporal patterns are -obtained from the set of images, such as in the example above. One can -also use patterns from a different set of images or defined in other -studies, as long as these temporal patterns stand for the study area and -their bands match the bands in the unclassified images. - -\hypertarget{classifying-the-image-time-series}{% -\subsection{Classifying the image time -series}\label{classifying-the-image-time-series}} - -After obtaining a consistent set of temporal patterns, we use the -function \code{twdtwApply} to run the TWDTW analysis for each pixel -location in the raster time series. The input raster time series in the -object \code{twdtwRaster} should be longer or have approximatly the same -length as the temporal patterns. This function retrieves an object of -class \code{twdtwRaster} with the TWDTW dissimilarity measure of the -temporal patterns for each time period. The arguments \code{overwrite} -and \code{format} are passed to \code{raster::writeRaster}. The -arguments \code{weight.fun} and \code{overlap} are described in -\autoref{classifying-a-time-series}. Here we set the parameters of the -time weight (logistic function) base on our the experience about the -phenological cycle of the vegetation in the study area. In the next -example, we classify the raster time series using the temporal patterns -in \code{temporal_patterns} obtained as described above. The result is a -\code{twdtwRaster} with five layers; each layer contains the TWDTW -dissimilarity measure for one temporal pattern over time. We use the -plot type \code{distance} to illustrate the TWDTW dissimilarity for each -temporal pattern in 2008, cf., \autoref{fig:plot-dissmilarity2008}. - -\begin{CodeChunk} - -\begin{CodeInput} -R> log_fun <- logisticWeight(alpha = -0.1, beta = 50) -R> twdtw_dist <- twdtwApply(x = raster_timeseries, y = temporal_patterns, -R+ overlap = 0.5, weight.fun = log_fun, overwrite = TRUE, format = "GTiff") -\end{CodeInput} -\end{CodeChunk} - -\begin{CodeChunk} - -\begin{CodeInput} -R> plot(x = twdtw_dist, type = "distance") -\end{CodeInput} -\begin{figure}[!ht] - -{\centering \includegraphics{dtwSat_files/figure-latex/plot-dissmilarity2008-1} - -} - -\caption[Illustration of the TWDTW dissimilarity from each temporal pattern in 2008]{Illustration of the TWDTW dissimilarity from each temporal pattern in 2008. The blue areas are more similar to the pattern and the red areas are less similar to the pattern.}\label{fig:plot-dissmilarity2008} -\end{figure} -\end{CodeChunk} - -The results of the example above can be used to create categorical land -cover maps. The function \code{twdtwClassify} selects the most similar -pattern for each time period and retrieves a \code{twdtwRaster} object -with the time series of land cover maps. The resulting object includes -two layers, the first has the classified categorical maps and the second -has the TWDTW dissimilarity measure. - -\begin{CodeChunk} - -\begin{CodeInput} -R> land_cover_maps <- -R+ twdtwClassify(twdtw_dist, format = "GTiff", overwrite = TRUE) -\end{CodeInput} -\end{CodeChunk} - -\hypertarget{looking-at-the-classification-results}{% -\subsection{Looking at the classification -results}\label{looking-at-the-classification-results}} - -The classification results can be visualised using the \code{plot} -methods of the class \code{twdtwRaster}, which supports four plot types: -``maps'', ``area'', ``changes'', and ``distance''. The -\code{type = "maps"} shows the land cover classification maps for each -period, cf., \autoref{fig:plot-map}. - -\begin{CodeChunk} - -\begin{CodeInput} -R> plot(x = land_cover_maps, type = "maps") -\end{CodeInput} -\begin{figure}[!h] - -{\centering \includegraphics{dtwSat_files/figure-latex/plot-map-1} - -} - -\caption[Land cover maps for each year from 2008 to 2013]{Land cover maps for each year from 2008 to 2013.}\label{fig:plot-map} -\end{figure} -\end{CodeChunk} - -Using the plot \code{type = "area"} we show the area of each class over -time (\autoref{fig:plot-area}). - -\begin{CodeChunk} - -\begin{CodeInput} -R> plot(x = land_cover_maps, type = "area") -\end{CodeInput} -\begin{figure}[!h] - -{\centering \includegraphics{dtwSat_files/figure-latex/plot-area-1} - -} - -\caption[Percentage of area for each land cover class from 2008 to 2013]{Percentage of area for each land cover class from 2008 to 2013.}\label{fig:plot-area} -\end{figure} -\end{CodeChunk} - -Users can also view the land cover transition for each time period, by -setting \code{type = "changes"}. For each land cover class and each -period, the plot shows gains and losses in area from the other classes. -This is the visual equivalent of a land transition matrix, cf., -\autoref{fig:plot-change}. - -\begin{CodeChunk} - -\begin{CodeInput} -R> plot(x = land_cover_maps, type = "changes") -\end{CodeInput} -\begin{figure}[!h] - -{\centering \includegraphics{dtwSat_files/figure-latex/plot-change-1} - -} - -\caption[Gains and losses in area from the other classes]{Gains and losses in area from the other classes. The $y$ axis shows the actual class; the positive direction of $x$ axis shows the gains and the negative direction of $x$ axis shows the losses of the classes indicated in $y$. Colors indicate which class the gain/losse belong.}\label{fig:plot-change} -\end{figure} -\end{CodeChunk} - -Using the plot \code{type = "distance"} we can visualise the -dissimilarity of each classified pixel to the original temporal pattern, -\autoref{fig:plot-dissmilarity}. - -\begin{CodeChunk} - -\begin{CodeInput} -R> plot(x = land_cover_maps, type = "distance") -\end{CodeInput} -\begin{figure}[!h] - -{\centering \includegraphics{dtwSat_files/figure-latex/plot-dissmilarity-1} - -} - -\caption[TWDTW dissimilarity measure for each pixel over each classified period]{TWDTW dissimilarity measure for each pixel over each classified period. The blue areas have high confidence and the red areas have low confidence in the classification.}\label{fig:plot-dissmilarity} -\end{figure} -\end{CodeChunk} - -\hypertarget{assessing-classification-accuracy}{% -\subsection{Assessing classification -accuracy}\label{assessing-classification-accuracy}} - -In this section we show how to assess the classification. \pkg{dtwSat} -provides a function called \code{twdtwAssess}, which computes a set of -accuracy metrics, and adjusted area such as proposed by -\citet{Olofsson:2013} and \citet{Olofsson:2014}. The inputs of this -function are the classified map (an object of class \code{twdtwRaster}), -and a set of samples for validation (an object of class -\code{data.frame} or \code{sp::SpatialPointsDataFrame}). Besides -coordinates, the samples should also have starting dates, ending dates, -and lables compatible with the labels in the map (for details see -section \ref{input-data}). The output of \code{twdtwAssess} is an object -of class \code{twdtwAssessment}, which includes four slots: 1) -\code{accuracyByPeriod} is a list of metrics for each time period, -including overall accuracy, user's accuracy, produce's accuracy, error -matrix (confusion matrix), and adjusted area; 2) \code{accuracySummary} -has the accuracy and adjusted area accumulated over all time periods; 3) -\code{data} is a \code{SpatialPointsDataFrame} with sample ID, period -ID, starting date, ending date, reference label, predicted label, and -TWDTW distance; and 4) \code{map} is a \code{twdtwRaster} with the -raster maps. The next example uses \code{twdtwAssess} to compute the -accuracy of the maps (\code{land_cover_maps}) using the validation -samples (\code{validation_samples}) with a 95\% confidence level. - -\begin{CodeChunk} - -\begin{CodeInput} -R> maps_assessment <- twdtwAssess(land_cover_maps, y = validation_samples, -R+ proj4string = proj_str, conf.int = .95) -\end{CodeInput} -\end{CodeChunk} - -The results of the assessment in \autoref{tab:map-error-matrix}, -\ref{tab:map-accuracy}, and \ref{tab:map-adjusted-area} are accumulated -over the whole time period, i.e., the total mapped area is equal to the -surface area times the number of maps. It is possible to assess and -visualise each period independently from each other. However, our -samples are irregularly distributed over time and some classes do not -have samples in all time period, which limits the analysis of each time -period independently from each other. - -As we can see in \autoref{tab:map-error-matrix} only nine samples were -misclassified, all of them from the reference class ``Soybean-cotton''. -From these samples six were classified as ``Soybean-maize'', and three -as ``Cotton-fallow''. As we see in \autoref{tab:map-accuracy} the only -class with producer's accuracy lower than \(100\%\) was -``Soybean-cotton'', reaching \(72\%\) with high uncertainty -(\(\pm13\%\)). The user's accuracy for all classes was higer than -\(95\%\), with maximun uncertainty of \(\pm5\%\). - -\begin{table}[!ht] -\centering -\begin{tabular}{rrrrrrrrrr} - \hline - &\multicolumn{6}{c}{Reference class}&&\\ -\multicolumn{1}{c}{Map class} & \rotatebox[origin=l]{90}{Cotton-fallow} & \rotatebox[origin=l]{90}{Forest} & \rotatebox[origin=l]{90}{Soybean-cotton} & \rotatebox[origin=l]{90}{Soybean-maize} & \rotatebox[origin=l]{90}{Soybean-millet} & \rotatebox[origin=l]{90}{unclassified} & Total & Area & w\\ - \hline -Cotton-fallow & 61 & 0 & 3 & 0 & 0 & 0 & 64 & 47600561 & 0.148 \\ - Forest & 0 & 124 & 0 & 0 & 0 & 0 & 124 & 74701218 & 0.232 \\ - Soybean-cotton & 0 & 0 & 62 & 0 & 0 & 0 & 62 & 18836299 & 0.059 \\ - Soybean-maize & 0 & 0 & 6 & 120 & 0 & 0 & 126 & 110227229 & 0.343 \\ - Soybean-millet & 0 & 0 & 0 & 0 & 165 & 0 & 165 & 70300716 & 0.219 \\ - unclassified & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0.000 \\ - Total & 61 & 124 & 71 & 120 & 165 & 0 & 541 & 321666022 & 1.000 \\ - \hline -\end{tabular} -\caption{\label{tab:map-error-matrix}Error matrix of the map classification based on TWDTW analysis. The area is in the map unit, in this case $m^2$. $w$ is the proportion of area mapped for each class.} -\end{table} - -\begin{table}[!ht] -\centering -\begin{tabular}{rllllllllll} - \hline - &\multicolumn{6}{c}{Reference class}&&&&\\ -\multicolumn{1}{c}{Map class} & \rotatebox[origin=l]{90}{Cotton-fallow} & \rotatebox[origin=l]{90}{Forest} & \rotatebox[origin=l]{90}{Soybean-cotton} & \rotatebox[origin=l]{90}{Soybean-maize} & \rotatebox[origin=l]{90}{Soybean-millet} & \rotatebox[origin=l]{90}{unclassified} & Total & User's* & Producers's* & Overall*\\ - \hline -Cotton-fallow & 0.14 & 0.00 & 0.00 & 0.00 & 0.00 & 0.00 & 0.14 & 0.95$\pm$0.05 & 1.00$\pm$0.00 & 0.98$\pm$0.01 \\ - Forest & 0.00 & 0.23 & 0.00 & 0.00 & 0.00 & 0.00 & 0.23 & 1.00$\pm$0.00 & 1.00$\pm$0.00 & \\ - Soybean-cotton & 0.01 & 0.00 & 0.06 & 0.02 & 0.00 & 0.00 & 0.08 & 1.00$\pm$0.00 & 0.72$\pm$0.13 & \\ - Soybean-maize & 0.00 & 0.00 & 0.00 & 0.33 & 0.00 & 0.00 & 0.33 & 0.95$\pm$0.04 & 1.00$\pm$0.00 & \\ - Soybean-millet & 0.00 & 0.00 & 0.00 & 0.00 & 0.22 & 0.00 & 0.22 & 1.00$\pm$0.00 & 1.00$\pm$0.00 & \\ - unclassified & 0.00 & 0.00 & 0.00 & 0.00 & 0.00 & 0.00 & 0.00 & 1.00$\pm$0.00 & 1.00$\pm$0.00 & \\ - Total & 0.15 & 0.23 & 0.06 & 0.34 & 0.22 & 0.00 & 1.00 & & & \\ - \hline -\end{tabular} -\caption{\label{tab:map-accuracy}Accuracy and error matrix in proportion of area of the classified map. * 95\% confidence interval.} -\end{table} - -\newpage - -The user can visualise misclassified samples on top of the maps using -the plot \code{type = "map"} for objects of class -\code{twdtwAssessment}. The argument \code{samples} can also be set to -show correctly classified samples \code{samples = "correct"}, or to see -all samples \code{samples = "all"}. The -\autoref{fig:plot-map-incorrect-samples} shows that the misclassified -samples are all in the map from 2012. The six samples of -``Soybean-cotton'' classified as ``Soybean-maize'' are within a big area -of ``Soybean-maize'' and the three samples of ``Soybean-cotton'' -classified as ``Cotton-fallow'' are near the border between this two -classes. This errors might be related to the mixture of different -classes in the same pixel. - -\begin{CodeChunk} - -\begin{CodeInput} -R> plot(x = maps_assessment, type = "map", samples = "incorrect") -\end{CodeInput} -\begin{figure}[!ht] - -{\centering \includegraphics{dtwSat_files/figure-latex/plot-map-incorrect-samples-1} - -} - -\caption[Incorrect classified samples]{Incorrect classified samples.}\label{fig:plot-map-incorrect-samples} -\end{figure} -\end{CodeChunk} - -\newpage - -In \autoref{tab:map-adjusted-area} we can see the mapped and the -adjusted area. This is the accumulated area over the whole period, i.e., -the sum of all maps from 2008 to 2013. As the ``Forest'' and -``Soybean-millet'' did not have omission (\(100\%\) producer's accuracy) -or comission (\(100\%\) user's accuracy) erros, we immediately see that -their mapped area is equal to their adjusted area -(\autoref{tab:map-adjusted-area}). To help the analysis of the other -classes we use the plot \code{type = "area"} for class -\code{twdtwAssessment}, such that -\texttt{plot(x\ =\ maps\_assessment,\ type\ =\ "area",\ perc\ =\ FALSE)}. -\autoref{fig:plot-area-and-uncertainty} shows the accumulated area -mapped and adjusted for all classes. In this figure we see that our -method overestimated the area of ``Soybean-maize'', i.e., the mapped -area (\(110173564\;m^2\)) is bigger than the adjusted area -(\(104927204\;m^2\)) plus the confidence interval \(4113071\;m^2\). -Meanwhile we underestimated the area of ``Soybean-cotton'', i.e., its -mapped area (\(18782634\;m^2\)) is smaller than the adjusted area -(\(26260270\;m^2\)) plus the confidence interval (\(4805205\;m^2\)). The -mapped area of ``Cotton-fallow'' (\(47600561\;m^2\)) is within the -confidence interval of the adjusted area (\(45369285\pm2484480\;m^2\)). -To improve the accuracy assessment and area estimations the field -samples should be better distributed over time, which would also allow -for better land cover changes assessment. - -\begin{table}[!ht] -\centering -\begin{tabular}{rlll} - \hline - \multicolumn{1}{c}{Class} & Mapped area & Adjusted area & Margin of error*\\ - \hline -Cotton-fallow & 47600561 & 45369285 & $\pm$2484480 \\ - Forest & 74701218 & 74701218 & $\pm$0 \\ - Soybean-cotton & 18836299 & 26316491 & $\pm$4806920 \\ - Soybean-maize & 110227229 & 104978313 & $\pm$4115074 \\ - Soybean-millet & 70300716 & 70300716 & $\pm$0 \\ - unclassified & 0 & 0 & $\pm$0 \\ - \hline -\end{tabular} -\caption{\label{tab:map-adjusted-area}Mapped and adjusted, accumulated over the whole period, i.e., the sum of the maps from 2008 to 2013. The area is in the map unit, in this case $m^2$. * 95\% confidence level.} -\end{table} - -\begin{CodeChunk} -\begin{figure}[!ht] - -{\centering \includegraphics{dtwSat_files/figure-latex/plot-area-and-uncertainty-1} - -} - -\caption[Mapped and adjusted, accumulated over the whole period, i.e., the sum from the sum of the maps from 2008 to 2013]{Mapped and adjusted, accumulated over the whole period, i.e., the sum from the sum of the maps from 2008 to 2013. The area is in the map unit, in this case $m^2$.}\label{fig:plot-area-and-uncertainty} -\end{figure} -\end{CodeChunk} - -\hypertarget{conclusions-and-discussion}{% -\section{Conclusions and Discussion}\label{conclusions-and-discussion}} - -The overall accuracy of the classification with a 95\% confidence level -is within 97\% and 99\%. With same confidence level, user's and -producer's accuracy are between 90\% and 100\% for all classes, except -for ``Soybean-cotton'', which has wide confidence interval for user's -accuracy, between 59\% and 85\%. A small sample size will likely have -large confidence intervals \citep{Foody:2009}, therefore, this analysis -could be improved by increasing the number of ``Soybean-cotton'' -samples. In addition, our access to field information is limited to a -set of samples irregularly distributed over time, which are not enough -to assess each mapped period independently from each other. -Nevertheless, the results of the accuracy assessment show that the TWDTW -has great potential to classify different crop types. - -DTW based approaches have achieved good results for land cover -classification \citep{Petitjean:2012, Maus:2016}, however, a reduced -number of points in the time series will negatively impact the accuracy. -Remotely sensed images often present noise and poor coverage due to -clouds, aerosol load, surface directional effects, and sensor problems. -This leads to large amount of gaps in satellite image time series. -Therefore, methods that deal with irregular temporal sampling, i.e., -irregular sampling intervals, have great potential to fully exploit the -available satellite images archive. DTW is known to be one of the most -robust methods for irregular time series -\citep{Keogh:2005, Tormene:2009}. It was successfully applied for -satellite time series clustering using FORMOSAT-2 \citep{Petitjean:2012} -and using MODIS \citep{Maus:2016}. \citet{Petitjean:2012}, for example, -showed that clustering based on DTW is consistent even when there are -several images missing per year because of cloud cover. However, the -effect of a reduced number of samples in the time needs to be better -evaluated in order to point out the limiting gap size for satellite -image time series analysis using DTW based methods. - -DTW searches for matches of a temporal pattern, therefore the number of -points in the time series should represent the phenological cycles of -the different land cover types. The number of available observations -might be a limitation for sensors with lower temporal resolution, such -as Landsat. We believe that this limitation could be addressed, for -example, by combining TWDTW analysis with pixel-based compositing -techniques \citep{Griffiths:2013, White:2014}. These approaches have -become more popular with the opening of the USGS Landsat archive and -could be used to increase the availability of gap-free time series -\citep{Gomez:2016}. - -\pkg{dtwSat} provides a dissimilarity measure in the n-dimensional -space, allowing multispectral satellite image time series analysis. Our -experience using MODIS data sets has shown that n-dimensional analysis, -i.e., using RED, NIR, NDVI, EVI, and NDVI, increases the separability -among classes when compared to single band analysis, for example using -only EVI or NDVI. Further studies on multispectral data using TWDTW -analysis will help to optimize the selection of bands. - -The main goal of \pkg{dtwSat} package is to make TWDTW accessible for -researchers. The package supports the full cycle of land cover -classification using image time series, ranging from selecting temporal -patterns to visualising and assessing the results. The current version -of the \pkg{dtwSat} package provides a pixel-based time series -classification method. We envisage that future versions of the package -could include local neighborhoods to reduce border effects and improve -classification homogeneity. - -The \pkg{dtwSat} package provides two in-built functions for linear and -logistic time weight. In the current version of the package the -parameters of the weight functions are set manually to the same value -for all land cover classes. Future versions could include methods to -search for the best parameters for each land cover class using field -data. - -Nowadays, there are large open archives of Earth Observation data, but -few open source methods for analysing them. With this motivation, this -paper provides guidance on how to use the Time-Weighed Dynamic Time -Warping (TWDTW) method for remote sensing applications. As we have -discussed in a companion paper \citep{Maus:2016}, the TWDTW method is -well suited for land cover change analysis of satellite image time -series. - -The TWDTW algorithm is computationally intensive and for large areas one -should consider parallel processing. The algorithm is pixel time series -based, i.e., each time series is processed independently from each -other, and therefore, it can be easily parallelized. To aim for maximum -usage by the scientific community, the \pkg{dtwSat} package described in -this paper works with well-known \proglang{R} data classes such as -provided by \pkg{raster}, which offers the option to work with raster -data sets stored on disk that are too large to be loaded into memory -(RAM) at once \citep{Hijmans:2015}. We are planning improvements, so -that \pkg{dtwSat} can also be combined with array databases, such as -SciDB \citep{Stonebraker:2013}. We believe that combining array -databases with image time series analysis software such as presented -here is one way forward to scaling the process of information extracting -from very large Earth Observation data. - -\section*{Acknowledgments} - -Victor Maus has been supported by the Institute for Geoinformatics, -University of Münster (Germany), and by the Earth System Science Center, -National Institute for Space Research (Brazil). Gilberto Camara's term -as Brazil Chair at IFGI has been supported by CAPES (grant -23038.007569/2012-16). Gilberto's work is also supported by FAPESP -e-science program (grant 2014-08398-6) and CNPq (grant 312151/2014-4). - -\bibliography{references} - - -\end{document} - diff --git a/vignettes/dtwSat_files/figure-latex/alignments-all-patterns-1.pdf b/vignettes/dtwSat_files/figure-latex/alignments-all-patterns-1.pdf index 77caeea..6028bc2 100644 Binary files a/vignettes/dtwSat_files/figure-latex/alignments-all-patterns-1.pdf and b/vignettes/dtwSat_files/figure-latex/alignments-all-patterns-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/example-timeseries-1.pdf b/vignettes/dtwSat_files/figure-latex/example-timeseries-1.pdf index fb4f4b2..a747d2b 100644 Binary files a/vignettes/dtwSat_files/figure-latex/example-timeseries-1.pdf and b/vignettes/dtwSat_files/figure-latex/example-timeseries-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/logist-time-weight-1.pdf b/vignettes/dtwSat_files/figure-latex/logist-time-weight-1.pdf index d000c0b..19eb585 100644 Binary files a/vignettes/dtwSat_files/figure-latex/logist-time-weight-1.pdf and b/vignettes/dtwSat_files/figure-latex/logist-time-weight-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/plot-accuracy-1.pdf b/vignettes/dtwSat_files/figure-latex/plot-accuracy-1.pdf index 5fe9cd1..1efa826 100644 Binary files a/vignettes/dtwSat_files/figure-latex/plot-accuracy-1.pdf and b/vignettes/dtwSat_files/figure-latex/plot-accuracy-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/plot-area-1.pdf b/vignettes/dtwSat_files/figure-latex/plot-area-1.pdf index ff65fad..d93c4fe 100644 Binary files a/vignettes/dtwSat_files/figure-latex/plot-area-1.pdf and b/vignettes/dtwSat_files/figure-latex/plot-area-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/plot-area-and-uncertainty-1.pdf b/vignettes/dtwSat_files/figure-latex/plot-area-and-uncertainty-1.pdf index 460fd2d..24ee645 100644 Binary files a/vignettes/dtwSat_files/figure-latex/plot-area-and-uncertainty-1.pdf and b/vignettes/dtwSat_files/figure-latex/plot-area-and-uncertainty-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/plot-change-1.pdf b/vignettes/dtwSat_files/figure-latex/plot-change-1.pdf index 4a8a59d..1f20bda 100644 Binary files a/vignettes/dtwSat_files/figure-latex/plot-change-1.pdf and b/vignettes/dtwSat_files/figure-latex/plot-change-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/plot-dissmilarity-1.pdf b/vignettes/dtwSat_files/figure-latex/plot-dissmilarity-1.pdf index b120f97..22bd256 100644 Binary files a/vignettes/dtwSat_files/figure-latex/plot-dissmilarity-1.pdf and b/vignettes/dtwSat_files/figure-latex/plot-dissmilarity-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/plot-dissmilarity2008-1.pdf b/vignettes/dtwSat_files/figure-latex/plot-dissmilarity2008-1.pdf index e751ee4..d9fdec4 100644 Binary files a/vignettes/dtwSat_files/figure-latex/plot-dissmilarity2008-1.pdf and b/vignettes/dtwSat_files/figure-latex/plot-dissmilarity2008-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/plot-map-1.pdf b/vignettes/dtwSat_files/figure-latex/plot-map-1.pdf index f994206..99d13ff 100644 Binary files a/vignettes/dtwSat_files/figure-latex/plot-map-1.pdf and b/vignettes/dtwSat_files/figure-latex/plot-map-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/plot-map-incorrect-samples-1.pdf b/vignettes/dtwSat_files/figure-latex/plot-map-incorrect-samples-1.pdf index 963a951..6530e0d 100644 Binary files a/vignettes/dtwSat_files/figure-latex/plot-map-incorrect-samples-1.pdf and b/vignettes/dtwSat_files/figure-latex/plot-map-incorrect-samples-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/temporal-patterns-1.pdf b/vignettes/dtwSat_files/figure-latex/temporal-patterns-1.pdf index 3405996..a977c1e 100644 Binary files a/vignettes/dtwSat_files/figure-latex/temporal-patterns-1.pdf and b/vignettes/dtwSat_files/figure-latex/temporal-patterns-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/temporal-patterns-soy-cot-mai-1.pdf b/vignettes/dtwSat_files/figure-latex/temporal-patterns-soy-cot-mai-1.pdf index 1c68377..e074e4c 100644 Binary files a/vignettes/dtwSat_files/figure-latex/temporal-patterns-soy-cot-mai-1.pdf and b/vignettes/dtwSat_files/figure-latex/temporal-patterns-soy-cot-mai-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/time-series-classification-1.pdf b/vignettes/dtwSat_files/figure-latex/time-series-classification-1.pdf index 01d6773..54cedb3 100644 Binary files a/vignettes/dtwSat_files/figure-latex/time-series-classification-1.pdf and b/vignettes/dtwSat_files/figure-latex/time-series-classification-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/twdtw-example-1.pdf b/vignettes/dtwSat_files/figure-latex/twdtw-example-1.pdf index ceb0a97..d3febc2 100644 Binary files a/vignettes/dtwSat_files/figure-latex/twdtw-example-1.pdf and b/vignettes/dtwSat_files/figure-latex/twdtw-example-1.pdf differ diff --git a/vignettes/dtwSat_files/figure-latex/twdtw-matches-1.pdf b/vignettes/dtwSat_files/figure-latex/twdtw-matches-1.pdf index dc5eadf..b940bc4 100644 Binary files a/vignettes/dtwSat_files/figure-latex/twdtw-matches-1.pdf and b/vignettes/dtwSat_files/figure-latex/twdtw-matches-1.pdf differ