DBEST (version 1.8)

DBEST: Detecting Breakpoints and Estimating Segments in Trend (DBEST)

Description

A program for analyzing vegetation time series, with two algorithms: 1) change detection algorithm that detects trend changes, determines their type (abrupt or non-abrupt), and estimates their timing, magnitude, number, and direction; 2) generalization algorithm that simplifies the temporal trend into main features. The user can set the number of major breakpoints or magnitude of greatest changes of interest for detection, and can control the generalization process by setting an additional parameter of generalization-percentage.

Usage

DBEST(data, data.type, seasonality = -1, algorithm, breakpoints.no = -1, 
generalization.percent = -1, change.magnitude = -1, first.level.shift, 
second.level.shift, duration, distance.threshold, alpha, plot = -1)

Arguments

data

univariate time-series to be analysed. This should be an object of class 'ts'/'zoo' with a frequency greater than one without NA's or a vector without NA's. If the input data is a vector the algorithm will automatically assign a start year.

data.type

the data type. There are two options: "cyclical" for time series with a seasonal cycle, or "non-cyclical" for time series without seasonal cycle (e.g. deseasonalized data)

seasonality

the seasonality period as a number. If the input data type is non-cyclical this variable should be omitted or set to 'none'/'null'. This parameter will overwrite the frequency value of an input object of class 'ts'/'zoo'. However, if the input data is an object of class 'ts'/'zoo' and the seasonality period is omitted, then the algorithm will use as a seasonality period the frequency value from the input data.

algorithm

the algorithm mode. There are two options: "change detection" and "generalization".

breakpoints.no

the number of greatest changes to be detected (change detection algorithm); the number of major breakpoints to be included in the generalized trend (generalization algorithm). This parameter should be omitted if 'generalization.percent' or 'change.magnitude' is in use.

change.magnitude

the lowest magnitude for the changes to be detected (change detection algorithm); the largest variation allowed within a generalized segment (generalization algorithm). This parameter should be omitted if 'breakpoints.no' or 'generalization.percent' is in use.

generalization.percent

the highest percent (between 0 to 100) the trend should be generalized; (0 = the least-simplified trend; 100 = the most-simplified trend). This parameter should be omitted if 'breakpoints.no' or 'change.magnitude' is in use.

first.level.shift

the first level-shift-threshold value. This parameter corresponds to the lowest absolute difference in the time-series data between the level-shift point (abrupt change) and the next data point.

second.level.shift

the second level-shift-threshold value. This parameter corresponds to the lowest absolute difference in the means of the data calculated over the duration period before and after the level-shift point.

duration

the duration threshold value. This parameter corresponds to the lowest time period (time steps) within which the shift in the mean of the data level, before and after the level-shift point, persists; and, the lowest spacing (time steps) between successive level-shift points.

distance.threshold

the distance threshold value. This correspond to the the lowest perpendicular distance from farthest data point to the straight line passing through every pair of successive peak and valley points. The algorithm will estimate a distance threshold if this parameter is set to 'default'.

alpha

the statistical significance level value used for testing the significance of detected changes.

plot

display figures. This parameter could be omitted or set to: "on", "fig1", "fig2" or "off". The "fig1" option will display the input data and the estimated trend, plus the trend local change. The "fig2" option will display a graph with the decomposition of the time-series, including the actual data, the trend, the seasonal component and the remainder. The "on" option displays both 'figure 1' and 'figure 2'. The "off" option displays no figure.

Value

BreakpointNo

the number of breakpoints or changes detected.

SegmentNo

the number of segments estimated by the algorithm.

Start

a list with numbers representing the starting points of the changes as time-steps.

Duration

a list with numbers representing the durations of the changes as time-steps.

End

a list with numbers representing the ending points of the changes as time-steps.

Change

a list with the values of the changes.

ChangeType

a list with the types of the changes as numbers which could be 0 or 1. The numbers correspond to a non-abrupt change (0) or abrupt change (1).

Significance

a list with the statistical significances of the changes as numbers which could be 0 or 1. The numbers correspond to a statistically in-significant change (0) or significant change (1).

RMSE

the calculated Root Mean Squares Error of the fit.

MAD

the calculated Maximum Absolute Difference of the fit.

Details

An object of the class "DBEST" is a list with elements depending on whether the generalization algorithm or change detection algorithm is used.

References

Jamali S, J<U+00F6>nsson P, Eklundh L, Ard<U+00F6> J, Seaquist J (2015). Detecting changes in vegetation trends using time series segmentation. Remote Sensing of Environment, 156, 182-195. http://dx.doi.org/10.1016/j.rse.2014.09.010

Tomov H (2016). Automated temporal NDVI analysis over the Middle East for the period 1982 <U+2013> 2010. http://lup.lub.lu.se/student-papers/record/8871893

See Also

plot.DBEST for plotting of DBEST() results.

Examples

# NOT RUN {
# NDVI data for Site 1 and Site 2 used in Fig. 5, Jamali et al. 2015
data(NDVI.Site1)
NDVI.Site1 <- ts(NDVI.Site1, start=1982, frequency=12)

data(NDVI.Site2)
NDVI.Site2 <- ts(NDVI.Site2, start=1982, frequency=12)

# Trend of NDVI data for Site 1 and Site 2 used in Fig. 4, Jamali et al. 2015)
data(TREND.Site1)
data(TREND.Site2)

# Examples for DBEST<U+2019>s change detection algorithm 
# detecting three greatest changes in NDVI (Fig. 5a, b)
DBEST.Fig5a <- DBEST(data=NDVI.Site1, data.type="cyclical", 
                 seasonality=12, algorithm="change detection", 
                 breakpoints.no=3, first.level.shift=0.1, 
                 second.level.shift=0.2, duration=24, 
                 distance.threshold="default", alpha=0.05, plot="on")

DBEST.Fig5b <- DBEST(data=NDVI.Site2, data.type="cyclical", 
                 seasonality=12, algorithm="change detection", 
                 breakpoints.no=3, first.level.shift=0.1, 
                 second.level.shift=0.2, duration=24, 
                 distance.threshold="default", alpha=0.05, plot="on")

# detecting changes >= 0.2 NDVI units 
DBEST.examp1 <- DBEST(data=NDVI.Site1, data.type="cyclical", 
                  seasonality=12, algorithm="change detection", 
                  change.magnitude=0.2, first.level.shift=0.1, 
                  second.level.shift=0.2, duration=24, 
                  distance.threshold="default", alpha=0.05, plot="fig1")

DBEST.examp2 <- DBEST(data=TREND.Site2, data.type="non-cyclical", 
                  seasonality="none", algorithm="change detection", 
                  change.magnitude=0.2, first.level.shift=0.1, 
                  second.level.shift=0.2, duration=24, 
                  distance.threshold="default", alpha=0.05, plot="fig1")

# }
# NOT RUN {
# Examples for DBEST<U+2019>s generalization algorithm 
# the most-simplified trend 
DBEST.Fig4a <- DBEST(data=TREND.Site1, data.type="non-cyclical", 
                   seasonality="none", algorithm="generalization", 
                   generalization.percent=100, first.level.shift=0.1, 
                   second.level.shift=0.2, duration=24, 
                   distance.threshold="default", alpha=0.05, plot="fig1")
                   
DBEST.examp3 <- DBEST(data=NDVI.Site2, data.type="cyclical", 
                  seasonality=12, algorithm="generalization", 
                  generalization.percent=100, first.level.shift=0.1, 
                  second.level.shift=0.2, duration=24, 
                  distance.threshold="default", alpha=0.05, plot="fig1")

# one breakpoint included in the generalized trend
DBEST.Fig4b <- DBEST(data=TREND.Site1, data.type="non-cyclical", 
                 seasonality="none", algorithm="generalization", 
                 breakpoints.no=1, first.level.shift=0.1, 
                 second.level.shift=0.2, duration=24, 
                 distance.threshold="default", alpha=0.05, plot="fig1")

DBEST.examp4 <- DBEST(data=NDVI.Site2, data.type="cyclical", 
                  seasonality=12, algorithm="generalization", 
                  breakpoints.no=1, first.level.shift=0.1, 
                  second.level.shift=0.2, duration=24, 
                  distance.threshold="default", alpha=0.05, plot="fig1")

# the largest variation allowed within the generalized segments <= 0.1 NDVI units
DBEST.Fig4c <- DBEST(data=TREND.Site1, data.type="non-cyclical", 
                 seasonality="none", algorithm="generalization", 
                 change.magnitude=0.1, first.level.shift=0.1, 
                 second.level.shift=0.2, duration=24, 
                 distance.threshold="default", alpha=0.05, plot="fig1")

DBEST.examp5 <- DBEST(data=NDVI.Site2, data.type="cyclical", 
                  seasonality=12, algorithm="generalization", 
                  change.magnitude=0.2, first.level.shift=0.1, 
                  second.level.shift=0.1, duration=24, 
                  distance.threshold="default", alpha=0.05, plot="fig1")

# the least-simplified trend
DBEST.Fig4d <- DBEST(data=TREND.Site1, data.type="non-cyclical", 
                 seasonality="none", algorithm="generalization", 
                 generalization.percent=0, first.level.shift=0.1, 
                 second.level.shift=0.2, duration=24, 
                 distance.threshold="default", alpha=0.05, plot="fig1")

DBEST.examp6 <- DBEST(data=NDVI.Site2, data.type="cyclical", 
                  seasonality=12, algorithm="generalization", 
                  generalization.percent=0, first.level.shift=0.1, 
                  second.level.shift=0.2, duration=24, 
                  distance.threshold="default", alpha=0.05, plot="fig1")
# }
# NOT RUN {
 
# }
# NOT RUN {
<!-- % end don't run -->
# }
# NOT RUN {
                  
# }