stef_monitor: Detects forest cover disturbances as extreme events in...
In hamun001/STEF: Space-time change analysis of earth observation data for forest cover change monitoring and detection

Description Usage Arguments Details Value Author(s) References See Also Examples

This function detects extreme events (observations) at sub-annual scales in the space-time data cubes of satellite images. Extreme observations are identified at pixel level, and the extremeness is defined based on percentile (e.g 5th percentile). The observations in the data cube are normalised spatially to reduce seasonality, a procedure carried out within this function, if specified, otherwise it is assumed that data have been normlised already. The function is intended for near real-time deforestation monitoring using satellite image time series.It is scalable to multiple cores (See usage example). NOTE: This function must always be called within the rasterEngine function. See the usage example

1 2	stef_monitor(inraster, my_dates, mYear, spatiaNormPercentile, threshold, densityPlot, windowwidth, tryCatchError, sPatioNormalixse, ...)

`inraster`	Input raster stack. Note that this input is literally the a local spac-time data cube whose dimensions are defined by the user.
`my_dates`	A vector containing the acquisition date for each image/layer in the image stack.
`mYear`	The start datetime for the minotoring period. This parameter has to be defined either as a decimal year (e.g. 2015.356) if the start of the monitoring period is not at the begining of the year or as a integer year (e.g. 2015) if the monitoring period start at the begining of the year.
`spatiaNormPercentile`	The upper percentile ( e.g. 95 percentile ) for determining the value to use to spatially normalise the values in the local data cube. Spatial normalisation is done to reduce seasonal variation in the data cube and also to reduce inter-sensor differences in the time series (data cube) when using multi-sensor time series.
`threshold`	A percentile/ extremeness for determining if the observation being monitored (typically newly acquired observation) is an extreme. Typically the value should be below 5th percentile
`densityPlot`	Logical. If TRUE, for every pixel in the entire raster stack, the observations in the local data cube would be plotted as density function when detecting deforestation.
`windowwidth`	A numeric value specifying the spatial extent (deminsions) of the data cube. The data cube always has a square spatial extent, hence one numeric value as input, and the windowwidth can only be defined as an odd number,larger than 1
`tryCatchError`	Logical. If TRUE, pixels were the algorithm faces an error during processing would be ignored, and NA values would be return for each of such pixel. If FALSE, the process would stop.
`sPatioNormalixse`	Logical. If TRUE, pixel values at each timestep will be normalised spatially using spatiaNormPercentile value, and normalisation wil be local (within the data cube)

To be completed.

Per pixel, it returns 18 values. (1) Numeric (e.g. 2017.353) - The date of the image in which the potential forest disturbnace is detected. (2) Number of valid observations in the local data cube over the reference period. (3) Continuous value - Standard deviation of the observations in the reference period of a local data cube. (4) Continuous value - The threshold for identifying negative anomalies, computed from the local data cube over the reference period, corresponding to the specified percentile(5th percentile). (5) Magnitude of change (the difference between the actual threshold and the negative anomalies, (5) Discrete-Numeric value - Number of consecutive negative anomalies (is either 2 for two consecutive negative anomalies or 1 if only the last observation in the time series is a negative anomaly). (6) Discrete-Numeric value - Number of 8-connected neigbours for the focal pixel which also experienced negative anomalies at T1. (7) Binary (yes =1, no =0) value - Indicates whether any of the 8-connected neighbours for the focal pixel also experienced negative anomalies at T1. (8) Discrete-Numeric value - Number of 8-connected neighbours of the focal pixel which are also experiencing negative anomalies at T2. (9) Binary (yes =1, no =0) value - Indicates whether any of the 8-connected neighbours of the focal pixel is also experiencing negative anomalies at T2. (10) Discrete-Numeric value - Number of pixels in the local data cube which also experienced negative anomalies at T1. (11) Discrete-Numeric value - Number of pixels in local data cube with Negative anomalies at T2. (12) Binary (yes =1, no =0) value - Indicates whether any of the 8-connected neighbours for the focal pixel is already non-forest in the reference period. (13) Discrete-Numeric value - Number of the 8-connected neighbours for the focal pixel which are already non-forest in the reference period. 14) Discrete-Numeric value - Number of pixels within the local data cube which have been masked as non-forest in the reference period. (16) Continuous value - Cumulative sum of residuals for spatial variability at T1. (17) Continuous value - Cumulative sum of resdiuals for spatial variability at T2. (18) Continuous value - Temporal linear trend in spatial variability.

Eliakim Hamunyela

1. Hamunyela, E., Verbesselt, J., Herold, M. (2016) Using spatial context to improve early detection of deforestationfrom Landsat time series. Remote Sensing of Environment,172, 126â€“138. http://dx.doi.org/10.1016/j.rse.2015.11.006

2. Hamunyela, E., Verbesselt, J.,de Bruin, S., Herold, M. (2016). Monitoring Deforestation at Sub-Annual Scales as Extreme Events in Landsat Data Cubes. Remote Sensing, 8(8), 651. http://dx.doi.org/10.3390/rs8080651

3. Hamunyela, E., Reiche, J., Verbesselt, J., & Herold, M. (2017). Using space-time features to improve detection of forest disturbances from Landsat time series. Remote Sensing, 9

rasterEngine

## Not run: 

#create a raster stack
ra <- raster(ncols=360, nrows=180)
ra[] <- rnorm(ncell(ra))
for (i in 1: 86){
ro <- raster(ncols=360, nrows=180)
ro[] <- rnorm(ncell(ro))
ra <- stack(ra, ro)
}
 #generate fake  date stamps for layers
imagedate <- decimal_date(seq(as.Date("2010-1-1"), as.Date("2016-12-30"), by = "month"))

#single pixel processing example:
rad <- rasterEngine(inraster=rasterBrick, fun=stef_monitor,window_dims=c(windowwidth=15,windowwidth =15),
                   args=list(mYear = 2014,density = F,my_dates =imagedate,threshold = 0.01,spatiaNormPercentile =95, windowwidth =15,tryCatchError=T))

#paralell processing example:
## register the cores
sfQuickInit(cpus=5)
rad <- rasterEngine(inraster=ra, fun=stef_monitor,window_dims=c(windowwidth=15,windowwidth =15),
                   args=list(mYear = 2014,density = F,my_dates =imagedate,threshold = 0.01,spatiaNormPercentile =95, windowwidth =15,tryCatchError=T, sPatioNormalixse =T))
writeRaster(rad, filename="test.tif",datatype ="FLT4S", overwrite=TRUE)
# Unregister the cores
sfQuickStop()

## End(Not run)