Movatterモバイル変換

Functions for calculating life history metrics from matrix populationmodels (MPMs).

Installation

# install.packages("remotes")remotes::install_github("jonesor/Rage")

Usage

Loading an example MPM

The functions in Rage work on MPMs (or components of MPMs), so we’llstart by loading one of the example MPMs included in the Rage package(mpm1).

library(Rage)# load Ragedata(mpm1)# load data object 'mpm1'mpm1#> $matU#>         seed small medium large dormant#> seed    0.10  0.00   0.00  0.00    0.00#> small   0.05  0.12   0.10  0.00    0.00#> medium  0.00  0.35   0.12  0.23    0.12#> large   0.00  0.03   0.28  0.52    0.10#> dormant 0.00  0.00   0.16  0.11    0.17#>#> $matF#>         seed small medium large dormant#> seed       0     0   17.9  45.6       0#> small      0     0    0.0   0.0       0#> medium     0     0    0.0   0.0       0#> large      0     0    0.0   0.0       0#> dormant    0     0    0.0   0.0       0

The objectmpm1 is a list containing two elements: thegrowth/survival component of the MPM (theU matrix),and the sexual reproduction component (theF matrix).We can obtain the full MPM by adding the two components together(A =U +F).

Deriving life historytraits from an MPM

One of the most common arguments among functions in Rage isstart, which is used to specify the stage class thatrepresents the ‘beginning of life’ for the purposes of calculation.Because the first stage class inmpm1 is a ‘seed’ stage,which we might consider functionally-distinct from the ‘above-ground’stages, we’ll specifystart = 2 to set our starting stageclass of interest to the ‘small’ stage.

life_expect_mean(mpm1$matU,start =2)# life expectancy#> [1] 2.509116longevity(mpm1$matU,start =2,lx_crit =0.05)# longevity (age at lx = 0.05)#> [1] 7mature_age(mpm1$matU, mpm1$matF,start =2)# mean age at first reproduction#>    small#> 2.136364mature_prob(mpm1$matU, mpm1$matF,start =2)# prob survival to first repro#> [1] 0.4318182

Some life history traits are independent of the starting stage class,in which case we don’t need to specifystart.

net_repro_rate(mpm1$matU, mpm1$matF)# net reproductive rate#> [1] 1.852091gen_time(mpm1$matU, mpm1$matF)# generation time#> [1] 5.394253

Some life history traits are calculated from a life table rather thanan MPM. For example, traits like entropy (entropy_k_stage)and shape measures (shape_surv,shape_rep)etc. In these cases, the calculation of age trajectories (lx and or mxtrajectories) is handled internally. Nevertheless, it can still beuseful to obtain the trajectories directly, in which case we can firstuse thempm_to_ group of functions.

# first derive age-trajectories of survivorship (lx) and fecundity (mx)lx<-mpm_to_lx(mpm1$matU,start =2)mx<-mpm_to_mx(mpm1$matU, mpm1$matF,start =2)

Life tablesand the quasi-stationary distribution

Some MPMs are parameterized with a stasis loop at the maximum stageclass, which can lead to apparent plateaus in mortality or fertilitytrajectories derived using age-from-stage methods. The functionqsd_converge() can be used to identify the time it takesfor a cohort to reach the quasi-stationary distribution (QSD). Thisquantity can then be used to subset age trajectories of mortality orfertility to periods earlier than the QSD, so as to avoid artefactualplateaus in mortality or fertility.

# derive life table from MPMlt<-mpm_to_table(mpm1$matU,start =2)# calculate time to QSD(q<-qsd_converge(mpm1$matU,start =2))#> [1] 6# plot mortality trajectory w/ vertical line at time to QSDpar(mar =c(4.5,4.5,1,1))plot(qx~ x,data = lt,type ="l",ylim =c(0,0.65))abline(v = q,lty =2)

From the life table derived frommpm1, we can see aplateau in the mortality rate (qx) beginning around age 5. However, thisplateau corresponds to the QSD and is therefore probably an artefact ofthe stasis loop rather than a biological reality for the populationrepresented bympm1.

One approach to accounting for this artefactual plateau in subsequentlife history calculations is to limit our life table to the period priorto the QSD.

# calculate the shape of the survival/mortality trajectoryshape_surv(lt$lx)# based on full lx trajectory#> [1] -0.04681254shape_surv(lt$lx[1:q])# based on lx trajectory prior to the QSD#> [1] -0.06573764

Standardized vital rates

The transition rates that make up MPMs generally reflect products oftwo or more vital rates (sometimes called ‘lower-level vital rates’).Assuming a post-breeding census design, we can retroactively break aparteach transition rate into at least two vital rate components: survival,and ‘something’ conditional on survival. That ‘something’ might begrowth, shrinkage, stasis, dormancy, fecundity, or clonality.

Stage-specific vital rates(vector)

To summarize vital rateswithin stage classes, we can usethevr_vec_ group of functions. We’ll use theexclude argument here to exclude certain stage classes(‘seed’ and ‘dormant’) from the calculation of certain vital rates(e.g. we don’t consider the large-to-dormant transition to actuallyrepresent ‘growth’).

vr_vec_survival(mpm1$matU)#>    seed   small  medium   large dormant#>    0.15    0.50    0.66    0.86    0.39vr_vec_growth(mpm1$matU,exclude =c(1,5))#>      seed     small    medium     large   dormant#>        NA 0.7600000 0.4242424        NA        NAvr_vec_shrinkage(mpm1$matU,exclude =5)#>      seed     small    medium     large   dormant#>        NA        NA 0.1515152 0.2674419        NAvr_vec_stasis(mpm1$matU)#>      seed     small    medium     large   dormant#> 0.6666667 0.2400000 0.1818182 0.6046512 0.4358974vr_vec_dorm_enter(mpm1$matU,dorm_stages =5)#>      seed     small    medium     large   dormant#>        NA        NA 0.2424242 0.1279070        NAvr_vec_dorm_exit(mpm1$matU,dorm_stages =5)#>      seed     small    medium     large   dormant#>        NA        NA        NA        NA 0.5641026vr_vec_reproduction(mpm1$matU, mpm1$matF)#>     seed    small   medium    large  dormant#>       NA       NA 27.12121 53.02326       NA

MPM-specific vital rates(scalar)

To summarize vital ratesacross stage classes, we can usethevr_ group of functions. By default these functions takea simple average of the stage-specific vital rates produced by thecorrespondingvr_vec_ function. However, here we’lldemonstrate how to specify aweighted average across stages,based on the stable stage distribution at equilibrium (w).

# derive full MPM (matA)mpm1$matA<- mpm1$matU+ mpm1$matF# calculate stable stage distribution at equilibrium using popdemo::eigslibrary(popdemo)#> Welcome to popdemo! This is version 1.3-0#> Use ?popdemo for an intro, or browseVignettes('popdemo') for vignettes#> Citation for popdemo is here: doi.org/10.1111/j.2041-210X.2012.00222.x#> Development and legacy versions are here: github.com/iainmstott/popdemow<- popdemo::eigs(mpm1$matA,what ="ss")# calculate MPM-specific vital ratesvr_survival(mpm1$matU,exclude_col =c(1,5),weights_col = w)#> [1] 0.5963649vr_growth(mpm1$matU,exclude =c(1,5),weights_col = w)#> [1] 0.6602975vr_shrinkage(mpm1$matU,exclude =c(1,5),weights_col = w)#> [1] 0.1960601vr_stasis(mpm1$matU,exclude =c(1,5),weights_col = w)#> [1] 0.2824323vr_dorm_enter(mpm1$matU,dorm_stages =5,weights_col = w)#> [1] 0.1984209vr_dorm_exit(mpm1$matU,dorm_stages =5,weights_col = w)#> [1] 0.5641026vr_fecundity(mpm1$matU, mpm1$matF,weights_col = w)#> [1] 37.07409

Note how we’ve chosen to exclude the ‘seed’ and ‘dormant’ stageclasses from our vital rate summaries, because we consider these to bespecial classes (e.g. ‘growth’ from the ‘seed’ stage is really‘germination’, which we may think of as separate from somatic growthfrom ‘small’ to ‘medium’, or ‘medium’ to ‘large’).

Perturbation analyses

Theperturb_matrix() function measures the response of ademographic statistic to perturbation of individual matrix elements(i.e. sensitivities and elasticities). Theperturb_vr() andperturb_trans() functions implement perturbation analysesby vital rate type (survival, growth, etc.) and transition type (stasis,retrogression, etc.), respectively.

# matrix element perturbationperturb_matrix(mpm1$matA,type ="sensitivity")#>               seed      small      medium       large     dormant#> seed     0.2173031 0.01133203 0.004786308 0.002986833 0.001150703#> small    4.4374613 0.23140857 0.097739870 0.060993320 0.023498191#> medium  10.8654599 0.56661979 0.239323184 0.149346516 0.057537001#> large   21.3053309 1.11104269 0.469270739 0.292842885 0.112820081#> dormant  3.6111989 0.18831947 0.079540419 0.049636195 0.019122779# vital rate perturbation# (we use as.data.frame here for prettier printing)as.data.frame(perturb_vr(mpm1$matU, mpm1$matF,type ="sensitivity"))#>   survival   growth  shrinkage  fecundity clonality#> 1 2.986054 1.077597 -0.1653284 0.00572764         0# transition type perturbationas.data.frame(perturb_trans(mpm1$matU, mpm1$matF,type ="sensitivity"))#>     stasis     retro    progr   fecundity clonality#> 1 1.000001 0.4174435 6.713571 0.007773141        NA

Transforming MPMs

Rage includes a variety of functions that can be used to manipulateor transform MPMs. For example, we can collapse an MPM to a smallernumber of stage classes usingmpm_collapse().

# collapse 'small', 'medium', and 'large' stages into single stage classcol1<-mpm_collapse(mpm1$matU, mpm1$matF,collapse =list(1,2:4,5))col1$matA#>      [,1]        [,2] [,3]#> [1,] 0.10 11.61331815 0.00#> [2,] 0.05  0.53908409 0.22#> [3,] 0.00  0.05728085 0.17

The transition rates in the collapsed matrix are a weighted averageof the transition rates from the relevant stages of the original matrix,weighted by the stable distribution at equilibrium. This processguarantees that the collapsed MPM will retain the same population growthrate as the original. However, other demographic and life historycharacteristics will not necessarily be preserved.

# compare population growth rate of original and collapsed MPM (preserved)popdemo::eigs(mpm1$matA,what ="lambda")#> [1] 1.121037popdemo::eigs(col1$matA,what ="lambda")#> [1] 1.121037# compare net reproductive rate of original and collapsed MPM (not preserved)net_repro_rate(mpm1$matU, mpm1$matF)#> [1] 1.852091net_repro_rate(col1$matU, col1$matF)#> [1] 1.447468

Previous releases

Specific earlier releases of this package can be installed using theappropriate@ tag.

remotes::install_github("jonesor/Rage@v1.0.0")

Citation

Jones, O. R., Barks, P., Stott, I., James, T. D., Levin, S., Petry,W. K., Capdevila, P., Che-Castaldo, J., Jackson, J., Römer, G.,Schuette, C., Thomas, C. C., & Salguero-Gómez, R. (2022).Rcompadre andRage—Two R packages tofacilitate the use of the COMPADRE and COMADRE databases and calculationof life-history traits from matrix population models.Methods inEcology and Evolution, 13, 770–781.

Contributions

All contributions are welcome. Please note that this project isreleased with aContributorCode of Conduct. By participating in this project you agree to abideby its terms.

Project	Main branch	Devel branch