LDS_reconstruction {ldsr}

Learn LDS model.

Description

The initial conditions can either be randomized (specifiled by num.restarts) or provided beforehand.

Usage

LDS_reconstruction(
  Qa,
  u,
  v,
  start.year,
  method = "EM",
  transform = "log",
  init = NULL,
  num.restarts = 50,
  return.init = FALSE,
  ub = NULL,
  lb = NULL,
  num.islands = 4,
  pop.per.island = 250,
  niter = 1000,
  tol = 1e-05,
  return.raw = FALSE
)

Arguments

Qa

Observations: a data.frame of annual streamflow with at least two columns: year and Qa.

u

Input matrix for a single-model reconstruction, or a list of input matrices for an ensemble reconstruction.

v

Same as u.

start.year

Starting year of the climate proxies, i.e, the first year of the paleo period. start.year + nrow(pc) - 1 will determine the last year of the study horizon, which must be greater than or equal to the last year in Qa.

method

By default this is "EM". There are experimental methods but you should not try.

transform

Flow transformation, either "log", "boxcox" or "none". Note that if the Box-Cox transform is used, the confidence interval after back-transformation is simply the back-transform of the trained onfidence interval; this is hackish and not entirely accurate.

init

A list, each element is a vector of initial values for the parameters. If NULL, will be created by make_init(). See make_init for details.

num.restarts

The number of initial conditions to start the EM search; ignored if init is provided.

return.init

If TRUE, the list of initial values (init) will be returned. This can be useful if you want to reproduce the model from this one set of initial values.

ub

Upper bounds, a vector whose length is the number of parameters

lb

Lower bounds

num.islands

Number of islands (if method is GA; experimental)

pop.per.island

Initial population per island (if method is GA; experimental)

niter

Maximum number of iterations, default 1000

tol

Tolerance for likelihood convergence, default 1e-5. Note that the log-likelihood is normalized by dividing by the number of observations.

return.raw

If TRUE, state and streamflow estimates without measurement updates will be returned.

Value

A list of the following elements

• rec: reconstruction results, a data.table with the following columns

  • year: calculated from Qa and the length of u

  • X: the estimated hidden state

  • Xl, Xu: lower and upper range for the 95\

  • Q: the reconstructed streamflow

  • Ql, Qu: lower and upper range for the 95\

• theta: model parameters

• lik: maximum likelihood

• init: the initial condition that resulted in the maximum likelihood (if return.init = TRUE).

Examples

# Make a shorter time horizon so that this example runs fast
u <- v <- t(NPpc[601:813])
# We run this example without parallelism
foreach::registerDoSEQ()
LDS_reconstruction(NPannual, u, v, start.year = 1800, num.restarts = 1)
# Please refer to the vignette for the full run with parallel options. It takes a second or two.