Basic interface for detection methods

[eric-pedersen]

In our sub-group discussion, we decided that each detection method should have at least three sub-methods:

1. A method for fitting the abrupt change detection method. Should be able to take a formula of the form:

<response var name> ~ <time variable name> |< grouping variable name >) + <other model terms>.

The model should return a fitted object with everything necessary to run the other functions.

2. A method to evaluate how quickly the system is changing at different points in time (or in time and space for spatiotemporal methods). We discussed that a measure of rate of change of the community is more fundamental than a way of segmenting the community. This function could optionally take arguments of what measure of rates of change is desired, plus possibly a se.fit argument to calculate uncertainties on those rates of change.

3. A method to segment a time series into a set of "regimes", based on rates of change. This method would take a fitted model and possibly optional control parameters and return the timing of change points for each time series (or for each location in each time series in spatiotemporal models). This method would optionally return uncertainty intervals for the timing of those change points, although how those methods would be calculated would vary from method to method.

I think each fitted method should also have a plot() and print() method associated with it.

Does this effectively summarize our discussion? And is the best way to include this detail in the package as a .Rmd document spelling out how new methods should be implemented?

[gavinsimpson]

Three methods:

• abrupt_fit.default()
• abrupt_fit.data.frame()
• abrupt_fit.formula()

Interface:

#' Abrupt change estimation
#'
#' @param y a data frame of response variables, each column is a time series. If a
#'   single time series `y` will be a data frame with a single column.
#' @param t data frame of a single time ordering variable.
#' @param x data frame of one or more covariates.
#' @param method character; abrupt change method.
#' @param ... arguments passed to change point methods.
abrupt_fit.default <- function(y, t, x, method = NULL, ...) {

}

arguments

• y a data frame of response variables, each column is a time series. If a single time series y will be a data frame with a single column.
• t data frame of a single time ordering variable
• x data frame of a single time ordering variable
• method character; abrupt change method.
• ... other arguments passed to other methods

Example implementation

Default method

abrupt_fit.default <- function(y, t, x = NULL, method = NULL, ...) {
    # code
    METHODS <- c("coniss", "hgam")
    # code to call the method function
}

Data frame method for tibbles

abrupt_fit.data.frame <- function(data, y, t, x = NULL, method = NULL, ...) {
    # code
}

Internal abrupt change fitting function

Internal functions implementing the specific abrupt change methodologies. Functions should be named <method>_abrupt_fit

Below is the skeleton for a CONISS methodology used in palaeoecology:

coniss_abrupt_fit <- function(y, # data frame of spp
  t, # data frame single time variable
  x, # data frame of additional covariates, ignored in coniss
  clustering = c("coniss", "conslink"), # CONISS method
  dissimilarity = "euclidean", # type of dissimilarity needed
  ...) {
    dij <- vegdist(y, method = dissimilarity)
    model <- chclust(d, method = clustering)

    # df <- foo # create the results object 

    out <- list(results = df, model = model, data = list(y, t, x))
    class(out) <- c("coniss_fit", "abrupt_fit")
    out
}