DEBtool Toolbox: animal

Toolbox animal deals with the standard DEB model and some variants of this model.
Thousands of examples of applications of functions in this toolbox can be found in the predict-files of the add_my_pet collection.
Typified models are delineated as variations on model std

life cycle

Several functions apply to the full life cycle of the individual. The function animal runs a demo for the standard model, after editing parameter values in pars_animal:

shmics: temp correction, embryo weights, reproduction, reserve residence times
shtime_animal: length, reprod, weight, survival
shphase: phase diagram
shflux: fluxes of compounds
shflux_struc: structure-specific fluxes
shflux_weight: weight-specific fluxes
shratio: Repiration, Watering, Urination Quotients
shpower: powers and specific powers
shscale: variables versus species' max body weight
shssd_iso: population characteristics versus functional response

The standard model accounts for:
effects of food availability (X) and temperature (T).
These environmental parameters are taken to be constant in this demo, but the theory handles varying environmental parameters.

The animal (or other organism) is decomposed in:
structure (V) and reserve (E)
Organic compounds:
X = food, V = structure, E = reserve, P = faeces
Mineral compounds:
C = carbon dioxide, H = water, O = dioxygen, N = nitrogen waste

The animal develops through an embryonic, juvenile and adult phase.
Assimilation is switched on at birth
Allocation to maturation is redirected to reproduction at puberty

Uptake is proportional to surface area, which is taken to be proportional to the structural volume^(2/3): isomorph

The heating length (this is the volumetric length reduction due to the energy drain that goes into heating or osmotic work) is set to a fixed length in this implementation. The DEB theory has a module on the water balance, with implications for the costs of heating. These implications make the heating length a function of other variables.

All lengths refer to volumetric lengths. Lengths should be divided by a shape coefficients to arrive at shape-specific lengths.

Script shtraject runs a simulation of the stochastic variant, where food searching is a time-inhomogeneous Poisson process. DEB theory quantifies aging directly in terms of the hazard rate, so for the aging process no deterministic equivalent is available. The scripts plot variables as function of scaled time since birth. Function shphase presents phase diagrams, which indicate how reserve and structure chnage relative to each other.

Script statistics computes quantities that depend on food density, while script parscomp computes quantities that are independent of food density, so functions of parameters, called compound parameters.

Function shpower plots the various powers as function of scaled length. It is based on scaled_power. It is similar to shflux for mass fluxes and shflux_struc for structure-specific mass fluxes and shflux_weight for body weight-specific mass fluxes. Likewise shratio plots ratio's of mineral fluxes.

Maturity is, at constant food density, found from length by functions maturity, maturity_j, maturity_s. The functions relate to non-acceleration, tyupe M acceleration and delayed type M acceleration. They can be applied for the full life cycle (although maturity remains constant for adults).

Since food denisity trajectories uniquely determine state trajectories, the inverse mapping also exists: from states trajectories to trajectories of scaled functional response. The pair of functions f2o and o2f is and example for (fish) otoliths, where otoliths are considered to be products, with contributions from assimilations, dissipation and growth. See section 4.11.4 of the DEB book. Isotops, their dynamics is discussed in Section 4.7, add to the reconstruction to include temperature trajectories as well. See function isotope

embryo

The scaled initial reserve is computed by get_ue0 for eggs and get_ue0_foetus for foetusses. The latter amounts to the cumulative energy investment till birth. The functions initial_scaled reserve and initial_scaled reserve_foetus are shells around these function for vector-arguments and they are not scaled down to dimensionless quantities.

Scaled maturity at birth should not exceed a threshold that is computed in get_vHb.

The scaled length at birth is computed by get_lb, get_lb1, get_lb2, and get_lb3. The functions differ in numerical method, from fast and dirty to slow and robust. Use function get_lb_foetus for foetal development.

The scaled time at birth is computed by get_tb, get_tb1 and get_tb_foetus. These functions also compute scaled length at birth. Age, reserve, length (and maturity) at birth is produced by get_ael, get_aulh, get_tul and get_tul_i for egg development and get_ael_f and get_aulh_f for foetal development. The results are obtained by integration and can to used to check the results of other embryo-functions. The numerical methods differ between these functions.

The scaled reserve density at which growth and/or maturition ceases at birth is computed by get_eb_min_G, get_eb_min_R and get_eb_min. The levels can be seen as minimum levels to reach birth.

The cumulative energy investment to the various endpoints at birth can be obtained numerically with functions get_EMJHG and get_EMJHG_foetus, and graphically with functions birth_pie and birth_pie_foetus.

juvenile

The scaled times at weaning (for mammals) get_tx and start acceleration get_ts and metamorphosis get_tj and get_tj_foetus and puberty get_tp and get_tp_foetus are computed in combination with other scaled times and scaled lengths at life history events. If you only need scaled lengths, it is more economic to use the corresponding get_l* functions: get_ls, get_lj, get_lj_foetus, get_lp, get_lp_foetus. If you only need states at birth, see under embryo

The scaled reserve density at which growth and maturition ceases at puberty is computed by get_ep_min without acceleration, get_ep_min_metam with acceleration.

Scaled functional response is reconstructed from scaled length by functions l2f and l2f1. They apply to the juvenile and adult stages.

The reserve residence time as function of length is computed by res_time and fluxes of masses for parameters and states by flux. It applies to the juvenile and adult stages.

adult

The reproduction rate as function of time can be obtained with functions reprod_rate and reprod_rate_foetus. In case of type M acceleration, use functions reprod_rate_j or reprod_rate_s.

Likewise, the cumulative reproduction as function of time can be obtained with function cum_reprod. In case of type M acceleration, use functions cum_reprod__j or cum_reprod_s.

The cumulative energy investment in milk production (most by mammals) from birth to weaning is computed by milk.

The median age at death due to ageing is computed by get_t50_s for short growth periods. The scaled mean age at death due to aging is computed by get_tm_s for short growth periods and for arbitrary growth periods by get_tm and get_tm_foetus.

Functions get_evh and get_leh get state variables as functions of time over the whole life cycle.

pars-data

Functions get_pars_* obtain compound DEB parameters from easy-to-observe quantities and the functions iget_pars_* do the reverse, which can be used for checking. The theory is discussed in Kooijman et al 2008. The heating length L_T is assumed to be zero in all get_pars_* functions. An example of use is given in mydata_get_pars. The routines are organized as follows:

	get_pars			iget_pars
food level	one	several		one	several
constraint	k_J = k_M	k_J != k_M	k_J = k_M	k_J = k_M	k_J != k_M	k_J = k_M
growth	`get_pars_g`	`get_pars_h`	`get_pars_i`	`iget_pars_g`	`iget_pars_h`	`iget_pars_i`
growth & reprod	`get_pars_`	`get_pars_s`	`get_pars_t`	`iget_pars_r`	`iget_pars_s`	`iget_pars_s`

Functions for several food levels do not use age at birth data. If one food level is available, we have to make use of the assumption of stage transitions at fixed amounts of structure (k_M = k_J). If several food levels are available, we no longer need to make this assumption, but it does simplify matters considerably. Functions elas_pars_g and elas_pars_r give elasticity coefficients. Function get_pars_u converts compound parameters into unscaled primary parameters at abundant food.

Another group of get_pars functions obtain primary (rather than compound) parameters from data at abundant food. The theory behind the mapping of data to parameters, and vice versa, is given in Lika et al 2014. This mapping comes with assumptions about particular (chemical) parameter values (chemical potentials and the like). Again, all functions assume absence of surface-area linked maintenance. They don't make use of the assumption k_J = k_M, but assume that k_J is known. By increasing the number of known parameters, we can decrease the amount of data that is needed to get the remaining parameters, as reflected in the different get_pars varieties: get_pars_9, get_pars_8, get_pars_7, get_pars_6, get_pars_6a, get_pars_5, get_pars_4, get_pars_3, get_pars_2, get_pars_2a. Functions iget_pars_9 and iget_pars_8 are inverse functions, from parameters to data. Functions get_pars_9_foetus and iget_pars_9_foetus are for foetal development. One strategy to set values of "known" parameters is to use the generalized animal settings of Table 8.1 in the DEB-book. The maximum number of parameters than can be obtained at abundant food only is 9.

Functions filter_pars_9 and filter_data_9 filter allowable parameter and data combinations in the case of 9 parameters (including type M acceleration). Functions filter_pars_8 and filter_data_8 filter allowable parameter and data combinations in the case of 8 parameters (no acceleration).

population

The specific population growth rate at constant food density is obtained by sgr_mod, where mod is one of the 10 DEB models std, stf, stx, ssj, sbp, abj, asj, sbp, hep, hex. The mean age, length, squared and cubed length in the population at constant food density is computed by ssd_mod, where mod is again rplaced by one of the 10 DEB models.

The scaled functional response at which the specific population growth rate is zero is found by f_ris0_mod. Population characteristics are plotted against scaled functional response by shssd_iso. See further the popDyn page of Amp.

comparison

Parameter values are individual-specific, but the general idea is that intra-specific variations are small relative to inter-species variations. With this idea in mind, we can concieve the parameter values of a species as a kind of mean among all individuals of that species. DEB theory has rules for the co-variation of parameter values. Function scale obtains eco-physiological qantities as function of the zoom-factor and function shscale plots these quanties against maximum body weight, which itself is just one such quantity.