calcVCN.R

#' Calculate the VCN for a given period in days
#'
#' VCN means "Volume Consécutif Minimal" in French :)
#'
#' @param x [numeric] or [matrix] for respectively a time series and several times series
#' @param k [numeric] period in days
#' @param ... further parameters to send to [zoo::rollmean]
#'
#' @return A 1-length [numeric] for a single time series, a [numeric] otherwise.
#' @export
#' @rdname calcVCN
#'
#' @examples
#' m <- matrix(rnorm(1000), ncol = 10)
#' calcVCN(m, 10)
calcVCN <- function(x, k, ...) {
    UseMethod("calcVCN", x)
}

#' @rdname calcVCN
#' @export
calcVCN.matrix <- function(x, k, ...) {
    return(apply(x, 2, calcVCN.numeric, k = k))
}

#' @rdname calcVCN
#' @export
calcVCN.numeric <- function(x, k, ...) {
    slideMean <- zoo::rollmean(x, k, ...)
    return(suppressWarnings(min(slideMean)))
}

#' VCNn for a given return period
#'
#' @description
#' Calculation of VCN according to a return period. An adjustment to a Galton distribution (log-normal distribution) is realised.
#'
#' Functions named calcVCN\[k\]_\[return_period\] are also defined for commun indicators.
#'
#' @param return_period [numeric] number of years
#' @param x [data.frame] of flows (the first column should be a [POSIXct])
#' @return [numeric] VCN for the given return period
#' @rdname calcVCNn
#' @export
#'
#' @examples
#' #! load data
#' data(L0123001, package = "airGR")
#' dfQ <- data.frame(DatesR = BasinObs$DatesR, Q = BasinObs$Qls / 1000)
#'
#' # VCN10 return period of 2 years
#' calcVCNn(dfQ, 10, 5)
#'
calcVCNn <- function(x, k, return_period, ...) {
    UseMethod("calcVCNn", x)
}

#' @param x [numeric] vector of VCN of one year
#' @rdname calcVCNn
#' @export
calcVCNn.data.frame <- function(x, k, return_period, ...) {
    fcalcVCNk <- function(k) {
        function(x, ...) {calcVCN(x, k, ...)}
    }
    calcVCNk <- fcalcVCNk(k)
    assign("calcVCNk", calcVCNk, envir = globalenv())
    VCN_years <- airGR::SeriesAggreg(x, Format = "%Y", ConvertFun = rep("calcVCNk", ncol(x) - 1))
    VCNn <- apply(VCN_years[, -1, drop = FALSE], 2, calcQLogNn, return_period = return_period)
    return(VCNn)
}