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

cdmt	R Documentation

Change Detection by Multispectral Trends

Description

This is the main function of the package.

Usage

cdmt(
  sr_data,
  si_data,
  out_path = NULL,
  sr = NULL,
  si = NULL,
  years,
  cng_dir,
  th_const = 1.2,
  noise_rm = TRUE,
  cores = 1
)

Arguments

`sr_data`	character. Yearly surface reflectance data. Either the name of a `SpatRaster` object in the global environment or the full path where rasters (in .tif format) are stored. Each layer name should include the year preceded by an underscore ( `_` ). If `NULL` only spectral indices are used.
`si_data`	character. Yearly spectral indices. Either the name of a `SpatRaster` object in the global environment or the full path where rasters (in .tif format) are stored. Each layer name should include the year preceded by an underscore ( `_` ). If `NULL` only reflectance bands are used.
`out_path`	character. The path where output rasters (in .tif format) will be saved. Folders are created recursively if they do not exist. If `NULL` the output is a `SpatRaster` object created by the terra package.
`sr`	numeric vector. Layer indices (positive integers) of reflectance bands in each raster to be included in the time series. If `NULL` all layers are used. Ignored if `sr_data` is a `SpatRaster`.
`si`	numeric vector. Layer indices (positive integers) of spectral indices in each raster to be included in the time series. If `NULL` all layers are used. Ignored if `si_data` is a `SpatRaster`.
`years`	numeric vector. Time interval (years) to be analysed.
`cng_dir`	numeric vector. Direction of change caused by a disturbance in each spectral band/index. 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 employed.
`cores`	positive integer. Number of CPU cores used during analysis.

Details

cdmt() maps changes in spectral trends at the pixel level by analysing inter-annual Landsat time series. Time series can include single or multiple spectral bands/indices, hereafter referred to as bands. Impulsive noise, i.e. outliers in the time series, are removed through an iterative procedure. One-year gaps in the time series are filled using either linear interpolation or extrapolation. Input bands are SpatRaster objects created by the terra package. 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

A SpatRaster containing the following layers.

`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 terms) throughout the time series (one layer per band).
`D_FST`	Change magnitude (in relative terms) 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 a valid out_path is provided, output rasters in *.tif format are directly written in the output folder.

Author(s)

Donato Morresi, donato.morresi@gmail.com

References

\insertRef

maeng2019adaptivecdmt

Examples

library(cdmt)

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

# Process data
rsout <- cdmt(sr_data = "lnd_sr",
              si_data = "lnd_si",
              years = 1985:2020,
              cng_dir = c(-1, -1, 1, 1),
              cores = 2
              )

# Plot the maximum disturbance magnitude
terra::plot(rsout[["D_MAX_MD"]])

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