
<!-- README.md is generated from README.Rmd. Please edit that file -->

# luckieR

<!-- badges: start -->

<!-- badges: end -->

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

We are working on releasing the package to CRAN. You can always install
the development version of `luckieR` from [Github](https://github.com/)
as follows:

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

# Github direct installation
# install.packages("pak")
pak::pak("chrissy3815/luckieR")
```

## 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:

``` r
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.

``` r
# 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)
```
