cdmt_int: Pixel-wise Change Detection by Multispectral Trends

In donato-morresi/cdmt: Change Detection by Multispectral Trends

Pixel-wise Change Detection by Multispectral Trends

Description

This is the internal function called by cdmt to operate at the pixel level.

Usage

cdmt_int(
  x,
  nb,
  ny,
  yrs,
  ev = NA,
  dir,
  th_const = 1.2,
  noise_rm = TRUE,
  as_list = FALSE
)

Arguments

x	numeric vector or matrix. If x is a numeric vector, it should contain sequences of yearly values for each band. If x is a matrix, each row should contain time-ordered data relative to an individual band.
nb	integer. The number of bands in the time series.
ny	integer. The number of years.
yrs	numeric vector. The sequence of years to be analysed.
ev	logical vector. A vector containing NA values to be used in case of processing failure.
dir	numeric vector. Direction of change caused by a disturbance in each band. Valid values are either 1 or -1.
th_const	numeric. Constant controlling the change threshold employed by the HiTS procedure during thresholding. Typical values are comprised in the interval [1, 1.4].
noise_rm	logical. If TRUE the impulsive noise filter is used.
as_list	logical. If TRUE the output is a list. Otherwise, the output is a numeric vector.

Details

cdmt_int() is not directly called by the user. It analyses inter-annual Landsat time series to detect changes in spectral trends at the pixel level. Time series can include single or multiple spectral bands/indices, hereafter referred to as bands. Input data can be a numeric vector extracted from a SpatRaster or a matrix. Impulsive noise, i.e. outliers in the time series, can be removed through an iterative procedure by the relevant filter. One-year gaps in the time series are filled using either linear interpolation or extrapolation. Changes in the intercept, slope or both of linear trends are detected using the High-dimensional Trend Segmentation (HiTS) procedure proposed by \insertCitemaeng2019adaptive;textualcdmt. The HiTS procedure aims at detecting changepoints in a piecewise linear signal where their number and location are unknown.

Value

If as_list is TRUE, a list containing the following elements.

est	Estimated values (one layer for each year and band).
cpt	Detected changepoints (one layer for each year and band).
slo	Slope of the linear segments (one layer for each year and band).
mag	Magnitude in absolute terms (one layer for each year and band).
mag_rel	Magnitude in relative terms (one layer for each year and band).
len	Length of segments (one layer per year).
cpt_id	Type of change (one layer per year). One of the following values: 101 (abrupt disturbance); 102 (abrupt greening); 201 (gradual disturbance); 202 (gradual greening); 9 (other change).
tpa	Impulsive noise (one layer per year).
d_dur	Duration of disturbance (one layer per year).
g_dur	Duration of greening (one layer per year).
d_max	Maximum disturbance change magnitude (in relative tems) throughout the time series (one layer per band).
d_fst	Change magnitude (in relative tems) associated with the first disturbance detected within the time series (one layer per band).
g_max	Maximum greening change magnitude (in relative tems) throughout the time series (one layer per band).
wgts	Weights assigned to each band (one layer per band).
d_max_md	Median among bands using values of D_MAX (single layer).
d_fst_md	Median among bands using values of D_FST (single layer).
g_max_md	Median among bands using values of G_MAX (single layer).
d_max_yr	Year corresponding to D_MAX_MD (single layer).
d_fst_yr	Year corresponding to D_FST_MD (single layer).
g_max_yr	Year corresponding to G_MAX_MD (single layer).
d_max_dr	Duration of the disturbance corresponding to D_MAX_MD (single layer).
d_fst_dr	Duration of the disturbance corresponding to D_FST_MD (single layer).
g_max_dr	Duration of the greening corresponding to G_MAX_MD (single layer).
d_max-id	Type of change (CPT_ID) of the disturbance corresponding to D_MAX_MD (single layer).
d_fst_id	Type of change (CPT_ID) of the disturbance corresponding to D_FST_MD (single layer).
g_max_id	Type of change (CPT_ID) of the greening corresponding to G_MAX_MD (single layer).
n_gap	Number of gaps in the time series, if any (single layer).
n_tpa	Number of years containing impulsive noise, if any (single layer).
n_iter	Number of iterations performed by the impulsive noise filter (single layer).

If as_list is FALSE the result is a numeric vector.

Author(s)

Donato Morresi, [e-mail]

References

\insertRef

maeng2019adaptivecdmt

Examples

library(cdmt)

# Load raster data
data(lnd_si)
lnd_si <- terra::rast(lnd_si)

# Extract values
v <- terra::values(lnd_si)[2000,]

# Process data
out <- cdmt_int(v,
                nb = 3,
                ny = 36,
                yrs = 1985:2020,
                dir = c(-1, 1, 1),
                as_list = TRUE
                )

# Plot results
bands <- c("MSI", "TCW", "TCA")
par(mfrow=c(length(bands), 1))

for(i in seq_along(bands)) {
  plot(matrix(v, nrow = 3, ncol = 36)[i,], type = "l", col = 2,
  lwd = 2, ylab = "", xlab = "", xaxt = "n")
  lines(out$est[i,], type = "l", col = 4, lwd = 2, lty = 1)
  abline(v = which(out$cpt_id == 101), lty = 2, col = 1, lwd = 2)
  axis(1, at = seq_along(1985:2020), labels = 1985:2020)
  title(main = paste(bands[i]), adj = 0)
}

donato-morresi/cdmt documentation built on June 15, 2022, 9:54 a.m.