getApi: Calculate the antecedent precipitation index
In hydro-giub/hydroBE: Miscellaneous Functions of the Group of Hydrology Bern

Description Usage Arguments Details Value Author(s) References Examples

The antecedent precipitation index (API) can be used to estimate the moisture conditions of the land surface.

1	getApi(x, k = 0.9, n = 5, finite = TRUE)

`x`	numeric vector. The precipitation time series used to calculate the API. It is assumed that the time series has a constant frequency and no missing values.
`k`	real number or numeric vector. The weights to sum up the antecedent precipitation values, see 'Details' below. The elements of `k` should be in [0,1] for physical consistency.
`n`	integer. The number of antecedent time steps to consider for the API.
`finite`	logical. Use a fixed number of previous days (as specified with `n`), or set an initial API value and recursively calculate the API at time t with the API and precipitation from time t-1?

If finite=TRUE and k is a single number, the weights are derived as k^i, i=0,...,n-1.
If finite=TRUE and k is a numeric vector of length greater than one, n is ignored and k is used for the weighting procedure. In this case, the weights defined in k should increase along the vector indices.
If finite=FALSE, n is ignored and k should be a single number. The API series is initialised with x[1] and recursively calculated according to

API[t] = k*API[t-1] + x[t-1]
If k is a single number, the solutions of finite=TRUE and finite=FALSE converge for increasing values of n (see 'Examples' below).

Numeric vector, i.e. the API time series.

Simon S

Kohler, M. A., and R. K. Linsley (1924). "Predicting the runoff from storm rainfall". National Oceanic and Atmospheric Administration Weather Bureau Research Papers No. 34.

## the larger n, the closer are the solutions 
x <- rexp(1000)
api1 <- getApi(x=x,n=10)
api2 <- getApi(x=x,finite=FALSE)

x <- rexp(1000)
api3 <- getApi(x=x,n=300)
api4 <- getApi(x=x,finite=FALSE)

par(mfcol=c(2,1))
plot(x=api1,y=api2)
abline(a=0,b=1,col=2)
plot(x=api3,y=api4)
abline(a=0,b=1,col=2)

## user defined weights
x <- rexp(1000)
k <- 1/(15:1)
api <- getApi(x=x,k=k)