Find the name of a model by its features

A model_name concisely specifies the structure of a metabolism model. From a model_name, an appropriate set of model specifications (parameters and runtime options) can be generated with specs. From a complete specs list, a metabolism model can be run with metab.

Usage

mm_name(
  type = c("mle", "bayes", "night", "Kmodel", "sim"),
  pool_K600 = c("none", "normal", "normal_sdzero", "normal_sdfixed", "linear",
    "linear_sdzero", "linear_sdfixed", "binned", "binned_sdzero", "binned_sdfixed",
    "complete"),
  err_obs_iid = c(TRUE, FALSE),
  err_proc_acor = c(FALSE, TRUE),
  err_proc_iid = c(FALSE, TRUE),
  err_proc_GPP = c(FALSE, TRUE),
  ode_method = c("trapezoid", "euler", "rk2", "lsoda", "lsode", "lsodes", "lsodar",
    "vode", "daspk", "rk4", "ode23", "ode45", "radau", "bdf", "bdf_d", "adams",
    "impAdams", "impAdams_d", "Euler", "pairmeans", "NA"),
  GPP_fun = c("linlight", "satlight", "satlightq10temp", "NA"),
  ER_fun = c("constant", "q10temp", "NA"),
  deficit_src = c("DO_mod", "DO_obs", "DO_obs_filter", "NA"),
  engine = c("stan", "nlm", "lm", "mean", "loess", "rnorm"),
  check_validity = TRUE
)

Arguments

type

character. The model type. Options:

mle: maximum likelihood estimation (see also metab_mle)
bayes: bayesian hierarchical models metab_bayes
night: nighttime regression (see also metab_night)
Kmodel: regression of daily estimates of K600.daily versus discharge, time, etc., usually for 3-phase estimation of K alone (by MLE or nighttime regression), K vs discharge (using this model), and then GPP and ER with fixed K (by MLE) (see also metab_Kmodel)
sim: simulation of DO.obs 'data' for testing other models (see also metab_sim)

pool_K600

character. [How] should the model pool information among days to get more consistent daily estimates for K600? Options (see Details for more):

none: no pooling of K600
normal: \(K600 ~ N(mu, sigma)\)
linear: \(K600 ~ N(B[0] + B[1]*Q, sigma)\)
binned: \(K600 ~ N(B[Q_bin], sigma)\) where \(mu ~ N(mu_mu, mu_sigma)\) and \(sigma ~ N(sigma_mu, sigma_sigma)\)
complete: applicable only for type='Kmodel', which is generally used in conjunction with preceding estimates of K (e.g., by type='mle' or type='night') and subsequent estimates of GPP and ER (e.g., by type='mle' with daily K600 values specified)

err_obs_iid

logical. Should IID observation error be included? If not, the model will be fit to the differences in successive DO measurements, rather than to the DO measurements themselves.

err_proc_acor

logical. Should autocorrelated process error (with the autocorrelation term phi fitted) be included?

err_proc_iid

logical. Should IID process error be included?

err_proc_GPP

logical. Should IID process error in GPP be included? This kind of error occurs only during the day and is used to adjust GPP before passing that adjusted GPP into the dDO/dt equation. The GPP_inst variable is the corrected GPP, and a new variable, GPP_inst_partial, contains the pre-adjustment GPP estimates

ode_method

character. The method to use in solving the ordinary differential equation for DO. Options:

euler, formerly Euler: the final change in DO from t=1 to t=2 is solely a function of GPP, ER, DO, etc. at t=1
trapezoid, formerly pairmeans: the final change in DO from t=1 to t=2 is a function of the mean values of GPP, ER, etc. across t=1 and t=2.
for type='mle', options also include rk2 and any character method accepted by ode in the deSolve package (lsoda, lsode, lsodes, lsodar, vode, daspk, rk4, ode23, ode45, radau, bdf, bdf_d, adams, impAdams, and impAdams_d; note that many of these have not been well tested in the context of streamMetabolizer models)

GPP_fun

character. Function dictating how gross primary productivity (GPP) varies within each day. Options:

linlight: GPP is a linear function of light with an intercept at 0 and a slope that varies by day.
GPP(t) = GPP.daily * light(t) / mean.light
- GPP.daily: the daily mean GPP, which is partitioned into timestep-specific rates according to the fraction of that day's average light that occurs at each timestep (specifically, mean.light is the mean of the first 24 hours of the date's data window)
satlight: GPP is a saturating function of light.
GPP(t) = Pmax * tanh(alpha * light(t) / Pmax)
- Pmax: the maximum possible GPP
- alpha: a descriptor of the rate of increase of GPP as a function of light
satlightq10temp: GPP is a saturating function of light and an exponential function of temperature.
GPP(t) = Pmax * tanh(alpha * light(t) / Pmax) * 1.036 ^ (temp.water(t) - 20)
- Pmax: the maximum possible GPP
- alpha: a descriptor of the rate of increase of GPP as a function of light
NA: applicable only to type='Kmodel', for which GPP is not estimated

ER_fun

character. Function dictating how ecosystem respiration (ER) varies within each day. Options:

constant: ER is constant over every timestep of the day.
ER(t) = ER.daily
- ER.daily: the daily mean ER, which is equal to instantaneous ER at all times
q10temp: ER at each timestep is an exponential function of the water temperature and a temperature-normalized base rate.
ER(t) = ER20 * 1.045 ^ (temp.water(t) - 20)
- ER20: the value of ER when temp.water is 20 degrees C
NA: applicable only to type='Kmodel', for which ER is not estimated

deficit_src

character. From what DO estimate (observed or modeled) should the DO deficit be computed? Options:

DO_mod: the DO deficit at time t will be (DO.sat(t) - DO_mod(t)), the difference between the equilibrium-saturation value and the current best estimate of the true DO concentration at that time
DO_obs: the DO deficit at time t will be (DO.sat(t) - DO.obs(t)), the difference between the equilibrium-saturation value and the measured DO concentration at that time
DO_obs_filter: applicable only to type='night': a smoothing filter is applied over the measured DO.obs values before applying nighttime regression
NA: applicable only to type='Kmodel', for which DO deficit is not estimated

engine

character. With which function or software should the model fitting be done?

for type='mle': nlm only (the default)
for type='bayes': stan only (the default), an external software package that runs MCMC chains for Bayesian models (see http://mc-stan.org)
for type='night': lm only (the default)
for type='Kmodel': mean, lm, or loess enable different types of relationships between daily K600 and its predictors (nothing, discharge, time, etc.)
for type='sim': rnorm only (the default)

check_validity

logical. if TRUE, this function checks the resulting name against mm_valid_names(type).

Details

While the Usage shows all valid values for each argument, not all argument combinations are valid; the combination will also be checked if check_validity==TRUE. For arguments not explicitly specified, defaults depend on the value of type: any argument that is not explicitly supplied (besides type and check_validity) will default to the values indicated by mm_parse_name(mm_valid_names(type)[1]).

pool_K600

Here are the essential model lines (in Stan language) that distinguish the K pooling options.

`pool_K600`	Model code
`none`	`K600_daily ~ normal(K600_daily_mu, K600_daily_sigma)`
`normal`	`K600_daily ~ normal(K600_daily_mu, K600_daily_sigma)`
	`K600_daily_mu ~ normal(K600_daily_mu_mu, K600_daily_mu_sigma)`
	`K600_daily_sigma ~ gamma(K600_daily_sigma_shape, K600_daily_sigma_rate)`
`linear`	`K600_daily_pred <- K600_daily_beta[1] + K600_daily_beta[2] * discharge_daily`
	`K600_daily ~ normal(K600_daily_pred, K600_daily_sigma)`
	`K600_daily_beta ~ normal(K600_daily_beta_mu, K600_daily_beta_sigma)`
	`K600_daily_sigma ~ gamma(K600_daily_sigma_shape, K600_daily_sigma_rate)`
`binned`	`K600_daily_pred <- K600_daily_beta[Q_bin_daily]`
	`K600_daily ~ normal(K600_daily_pred, K600_daily_sigma)`
	`K600_daily_beta ~ normal(K600_daily_beta_mu, K600_daily_beta_sigma)`
	`K600_daily_sigma ~ gamma(K600_daily_sigma_shape, K600_daily_sigma_rate)`
`complete`	[This option refers to complete pooling via `metab_Kmodel` in conjunction with preceding
	estimates of K (e.g., by `metab_mle` or `metab_night`) and subsequent estimates of GPP and ER
	(e.g., by `metab_mle` with daily K600 values specified)]

Examples

mm_name('mle')
#> [1] "m_np_oi_tr_plrckm.nlm"
mm_name('mle', GPP_fun='satlight', ER_fun='q10temp')
#> [1] "m_np_oi_tr_psrqkm.nlm"
mm_name('night')
#> [1] "n_np_pi_eu_rckf.lm"
mm_name('sim', err_proc_acor=TRUE)
#> [1] "s_np_oipcpi_tr_plrckm.rnorm"
mm_name('bayes', pool_K600='binned')
#> [1] "b_Kb_oipi_tr_plrckm.stan"

Usage

Arguments

Details

pool_K600

See also

Examples