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 |
options |
An options list for running the model, see |
globals |
Optional parameter specifying global variables used in the simulation, see |
bounds |
Optional parameter specifying the upper and lower bounds of the model's parameters, see |
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 |
globals |
Globals as specified in the |
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 |
out.dimnames |
Dimension names for the output returned by |
out.dim |
Dimensions for the output returned by |
dimnames.beta |
Dimension names for the ttr parameters object produced by |
bounds |
Bounds for all process model parameters |
timeseries |
See |
timeinvariant |
See |
y |
observations from |
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)