make_data {TTR.PGM}R Documentation

Create data object for use with the process model

Description

This function creates an object representing a configuration of the process model including forcing data. This object is used by run_ttr().

Usage

make_data(
  input,
  options = standard_options,
  globals = standard_globals,
  bounds = list(alpha = NULL, beta = NULL),
  groups = c(),
  verbose = FALSE
)

Arguments

input

The forcing data object created by a call to get_input(), see specification in its help page

options

An options list for running the model, see options help page

globals

Optional parameter specifying global variables used in the simulation, see standard_globals help page

bounds

Optional parameter specifying the upper and lower bounds of the model's parameters, see make_data(). Bounds for additional parameters included in the statistical model need to be specified here. Bounds of the process model parameters can also be modified from their default values.

groups

Optional parameter specifying the groups of process model parameters

verbose

Print out a log detailing checks

Details

The data structure produced in this function can be handed to an external parameter estimation algorithm e.g. LaplacesDemon or DEoptim to fit the model.

The bounds of the process model's parameters need to be defined. The user can supply these to make_data() or accept the default values returned by a call to make_data(). Different model variants use different parameters and a call to make_data() returns the default bounds for the model variant specified in options.

bounds is a list of two lists; one for alpha (per-process) parameters and one for beta (per-species) parameters. The list bounds is formatted as: bounds = list(alpha = list(alpha_parameter = (lower, upper)), beta = list(beta_parameter = c(lower, upper))), where 'upper' specifies the maximum value a process model parameter can take on, and 'lower' is the corresponding minimum.

The external parameter estimation algorithm should then take Data$bounds[,1] as lower and Data$bounds[,2] as the upper bounds.

In case the user does not wish to estimate some of the parameters in the external optimisation process, the upper and lower bound of a parameter should be set to the same numeric value. In this case, the parameter will not be part of the Data$bounds matrix passed to the external parameter estimation algorithm, and its value is set internally in the get_parms() function.

For any group of parameters, e.g., CU_Ns_1 and CU_Ns_2, setting any one of the parameters to c(NA, NA) will set the whole group of parameters to a constant value that will negate the influence of this parameter group on the process model. This effectively switches off the effect of these parameters on the model's processes and removes them from Data$bounds. The constant values the parameters are set to can be observed by inspecting the output of get_parms() for a Data object.

The names of the parameters are written as YY_XX_i, where YY specifies the process being considered and XX the environmental driver and i the parameter number in the step or trapezoid function, e.g. CU_swc_1 and CU_swc_2 specify how CU (carbon uptake) is influenced by swc (soil water content) and 1 and 2 specify the lower and upper parameters of the step function.

An example for specifying all process bounds for a Model run with the standard options is given in the object 'standard_bounds'.

Value

A ttr data object, a list with the following elements:

PGF

Function used by LaplacesDemon for generating initial values.

options

Options as specified in the options and standard_options help pages

globals

Globals as specified in the standard_globals help page

n.sites

Number of sites

n.species

Number of species

n.time

Number of timesteps

n.parm

Number of parameters to be fitted

n.parm.a

Number of per-process parameters

n.parm.b

Number of per-species parameters

parm.names

Names of all parameters for this model configuration

parm.names.a

Names of per-process parameter names

parm.names.b

Names of per-species parameter names

mon.names

Required by LaplacesDemon, always set to "LP"

out

Names of the response variables returned by run_ttr()

out.dimnames

Dimension names for the output returned by run_ttr()

out.dim

Dimensions for the output returned by run_ttr()

dimnames.beta

Dimension names for the ttr parameters object produced by get_parms()

bounds

Bounds for all process model parameters

timeseries

See get_input()

timeinvariant

See get_input()

y

observations from get_input() cast to a matrix

lonlat

a matrix with lon and lat columns for the nsites rows

pos.oe

Indices of observation error parameters

pos.pe

Indices of process error parameters

parm.trap.groups

Representation of parameters that form a group for the trapezoid functions

arguments

The unprocessed arguments to this function, excluding data

Examples

#some dummy data as input
input_data <- get_input(
observations = c(1),
tcur = c(1),
tnur = c(1),
tgrowth = c(1),
tloss = c(1),
seconds = c(1),
lon = c(1),
lat = c(1),
rsds = c(1),
catm = c(1),
pet = c(1),
rain = c(1),
wp = c(1),
fc = c(1)
)
data <- make_data(
  input = input_data,
  options = standard_options,
  globals = standard_globals,
  bounds = list(
    alpha = list(
      #defining a new parameter, e.g. as part of a model function
      my_parameter = c(1,2),
      #overwriting a standard bound
      scale = c(0,500)
    ),
    #no more parameters than needed for the process model in beta, for these standard values.
    beta = list()
  )
)
#all standard values
data <- make_data(input_data, standard_options)

[Package TTR.PGM version 1.0.0 Index]