luckieR

The goal of luckieR is to provide user-friendly and generalized tools for the calculation of “luck” – moments of variation in metrics like lifespan and lifetime reproductive output. We provide tools for calculating those moments and also performing decompositions into contributions from, for example, individual traits, environmental impacts, and luck (also called individual stochasticity).

Installation

The luckieR package (v 0.1.0.0) is available on CRAN. We are actively making improvements to the package as version 0.1.0.9000, so we currently recommend using the development version. You can always install the development version of luckieR from Github as follows:

# CRAN installation:
install.packages("luckieR")

# Github development version installation
# install.packages("pak")
pak::pak("chrissy3815/luckieR")

Reporting an issue

Because we are actively improving the package, we are keen for people to try it out on their own data and let us know about anything that needs work.

Please use the Issues tab here on Github to let us know about any bugs, issues, or recommendations for improvement of the package and its documentation. Please use this reporting method even if you’ve talked to or emailed one of the developers directly!

It’s a simple text submission form, so please describe the issue as best you can, and provide example code and/or data when relevant. This helps us track the changes that we need to make, and whether we’ve solved the issue.

Example

This is a basic example which shows you how to calculate mean of lifespan and lifetime reproductive output (LRO) for a simple matrix model:

library(luckieR)

# Our matrix is separated into the Umat (survival and growth) and the Fmat (reproduction)
Umat<- matrix(c(0.5, 0.1, 0.1, 0, 0.5, 0.3, 0, 0, 0.8), ncol=3)
Fmat<- matrix(c(0.2, 0, 0, 1, 0.5, 0, 5, 3, 0), ncol=3)
Amat<- Umat+Fmat

# Lifespan:
meanL<- meanLifespan(Umat)
varL<- varLifespan(Umat)
skewL<- skewLifespan(Umat)

# LRO:
meanLrepro<- meanLRO(Umat, Fmat)
varLrepro<- varLRO(Umat, Fmat, repro_var = 'poisson')
skewLrepro<- skewLRO(Umat, Fmat, repro_var = 'poisson')

Those functions all return the values for individuals starting in any possible starting state. However, new individuals in the population are born into either state 1 or 2, but never state 3. So if we want to know the expected lifespan from birth, for a random individual born into this population, we need to take a weighted mean according to the frequency of offspring types.

We refer to the frequency distribution for calculating this kind of weighted mean as the “mixing distribution.” A standard choice for the mixing distribution is the distribution of offspring types in a cohort produced by the population at its stable distribution.

# luckieR provides a function to calculate the distribution of offspring in a cohort produced at the stable distribution:
mixdist<- calcDistOffspringCohort(Amat, Fmat)

# Now we can calculate population measures of mean, variance, and skewness:
# Lifespan:
pop_meanL<- meanLifespan(Umat, mixdist)
pop_varL<- varLifespan(Umat, mixdist)
pop_skewL<- skewLifespan(Umat, mixdist)

# LRO:
pop_meanLrepro<- meanLRO(Umat, Fmat, mixdist)
pop_varLrepro<- varLRO(Umat, Fmat, repro_var = 'poisson', mixdist)
pop_skewLrepro<- skewLRO(Umat, Fmat, repro_var = 'poisson', mixdist)