---
title: "FLife"
subtitle: "Modelling Life History relationships"
author: "Laurence Kell"
date: "`r format(Sys.time(), '%d %B, %Y')`"
output: rmarkdown::html_vignette
mathjax: TRUE
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{FLife-full}
  %\VignetteEncoding{UTF-8}
  fig_width: 6 
  fig_height: 4 
bibliography: bibliography.bib
tags: [FLife FLR]
license: Creative Commons Attribution-ShareAlike 4.0 International Public License
---

```{r knitr_init, echo=FALSE, results="hide"}
library(knitr)
## Global options
opts_chunk$set(cache     =TRUE,
               echo      =!TRUE,
               eval      =TRUE,
               prompt    =FALSE,
               comment   =NA,
               message   =FALSE,
               warning   =FALSE,
               tidy      =FALSE,
               fig.height=6,
               fig.width =8)

iFig=0
```


[](#top)

[Introduction](#Introduction)  
[Life History Relationships](#Life History Relationships)   
[Dynamics](#Dynamics)  
[Simulation](#Simulation)  
[More Information](#More)    
[References](#References)  

# Introduction
Life history traits include growth rate; age and size at sexual maturity; the temporal pattern or schedule of reproduction; the number, size, and sex ratio of offspring; the distribution of intrinsic or extrinsic mortality rates (e.g., patterns of senescence); and patterns of dormancy and dispersal. These traits contribute directly to age-specific survival and reproductive functions.^[http://www.oxfordbibliographies.com/view/document/obo-9780199830060/obo-9780199830060-0016.xml] The **FLife** package has a variety of methods for modelling life history traits and functional forms for processes for use in fish stock assessment and for conducting Management Strategy Evaluation (MSE). 

These relationships have many uses, for example in age-structured population models, functional relationships for these processes allow the calculation of the population growth rate and have been used to to develop priors in stock assesments and to parameterise ecological models. 

The **FLife** package has methods for modelling functional forms, for simulating equilibrium `FLBRP` and dynamic stock objects `FLStock`.


## Quick Start

This section provide a quick way to get running and provides an overview of the functions available, their potential use, and where to seek help. 

A number of packages need to be installed from CRAN and the  
[FLR](http://www.flr-project.org) website, where  [tutorials](https://www.flr-project.org/doc/) are also available.

Extensive use is made of the packages of [Hadley Wickham](http://hadley.nz/). For example  `ggplot2`, based on the *Grammar of Graphics* ^[Wilkinson, L. 1999. *The Grammar of Graphics*, Springer. [doi 10.1007/978-3-642-21551-3_13](http://dx.doi.org/10.1007/978-3-642-21551-3_13).], is used for plotting^[<http://tutorials.iq.harvard.edu/R/Rgraphics/Rgraphics.html>]. While `reshape` and `plyr` are used for data manipulatation and analysis.

```{r}
library(ggplot2)
library(reshape)
library(plyr)
```

The simplest way to obtain **FLife** is to install it from the `FLR` repository via the R console. See help(install.packages) for more details.

```{r install,echo=TRUE,eval=FALSE}
install.packages("FLife", repos = "http://flr-project.org/R")
```

```{r install-64,echo=FALSE,eval=FALSE}
install.packages("FLife", repos = "http://flr-project.org/R", INSTALL_opts="-no_multiarch" )
```

After installing the **FLife** package load it
```{r lib,echo=TRUE}
library(FLife)
```

[Back to Top](#top)

# Life History Relationships

## Data
There is an example dataset

```{r data,echo=TRUE}
data(teleost)
```

```{r data-3,echo=TRUE}
teleost
```

This is an `FLPar`~, a form of array used by `FLR` objects with life history parameters for a number of bony fish species. These include the parameters of the von Bertalanffy growth parameters

$$ L_t = L_\infty (1 - e^{(-kt-t_0)})$$

where $L_t$ is length at time t, $L_\infty$ the asymptotic maximum length, $k$ the growth coefficient and $t_0$ the time at which an individual is theoretically of zero length; the length where 50\% of individuals are mature ($L_{50}$); and the parameters, $a$, $b$ of length-weight relationship

$$L=aW^b$$

```{r, fig.height=8,fig.cap="Relationship between life history parameters."}
library(GGally)

habitat=ifelse(attributes(teleost)$habitat=="demersal","Demersal","Other")

my_smooth <- function(data,mapping,...){
  ggplot(data=data,mapping=mapping)+
  geom_point(...,size=.5)+
  geom_smooth(...,method="lm",se=FALSE)}

my_density <- function(data,mapping,...){
  ggplot(data=data,mapping=mapping)+
  geom_density(...,lwd=1)}
  
ggpairs(cbind(transform(model.frame(teleost)[,-c(7)],
                        linf=log(linf),k=log(k),l50=log(l50))),
  lower = list(continuous = wrap(my_smooth)),
  diag=list(continuous=wrap(my_density,alpha=0.2)),
  title = "")+
  theme(legend.position ="bottom",
  panel.grid.major =element_blank(),
  axis.ticks       =element_blank(),
  axis.text.x      =element_text(angle=-45),
  axis.text.y      =element_blank(),
  panel.border     =element_rect(linetype = 1, colour="black", fill=NA))+
  theme_bw()
```


## `lhPar` method

As seen in the above plot there are relationships between life history parameters, for example $L_{\infty}$ and $L_{50}$ show a strong positive correlation, in other words at a a large species has a faster rate of growth than a small species.

The `lhPar` method can be used to fill in missing values.

### Growth

@gislason2008coexistence proposed the relationship between $k$ and $L_{\infty}$

$$k=3.15L_{\infty}^{-0.64}$$

While @pauly1979gill proposed the empirical relationship between $t_0$ and $L_{\infty}$ and $k$ 

$$log(-t_0) = -0.3922 - 0.2752 log(L_{\infty}) - 1.038 log(k)$$ 

Therefore for a value of $L_{\infty}$, or for the maximum observed size ($L_{max}$ ) since 
$L_{\infty}=0.95L_{max}$, then missing growth parameters can be estimated.

This is done by the `lhPar` method, for example create an `FLPar` object with only `linf` then estimate the missing values

```{r,echo=TRUE,fig.cap="Relationship between k and Linfinty"}
linf=teleost["linf"]

hat=lhPar(linf)

ggplot()+
  geom_line(aes(linf,k), data=model.frame(hat))+
  geom_point(aes(linf,k),data=model.frame(teleost),col="red")+
  scale_x_log10()+
  scale_y_log10()+
  xlab(expression(L[infinty]))
```


### Maturity

@beverton1992patterns proposed  a relationship between $L_{50}$ the length at which 50% of individuals are mature 

$$l_{50}=0.72L_{\infty}^{0.93}$$

### Natural Mortality

For larger species securing sufficient food to maintain a fast growth rate entails exposure to a higher natural mortality, e.g. due to predation. While many small demersal species seem to be partly protected against predation by hiding, cryptic behaviour, being flat or by possessing spines have the lowest rates of natural mortality @griffiths2007natural. Hence, at a given length individuals belonging to species with a high $L_{\infty}$ may generally be exposed to a higher M than individuals belonging to species with a low $L_{\infty}$.

 @gislason2008does proposed the empirical relationship

$$ log(M) = 0.55-1.61log(L) + 1.44log(L_{\infty}) + log(k)$$


Filling in missing parameters
```{r}
lhPar(linf)
```

### Stock recruitment relationship

exportMethods(sv)  
exportMethods(steepness)  

`lhPar` assumes a Beverton and Holt stock recruitment relationship by default

$$R=\frac{aSSB}{b+SSB} $$

@beverton1993dynamics as reformulated by @francis1992use in terms of steepness ($h$), virgin recruitment ($R_0$) and $S/R_{F=0}$, where steepness is the rat. 

$$R=\frac{0.8R_0hS}{0.2S/R_{F=0}R_{0}(1-h)+(h-0.2)S}$$


Steepness is difficult to estimate from stock assessment data sets as there is often insufficient range in biomass levels required for its estimation.

@wiff2016chilean investigated the relationship between life history parameters and the steepness of the stock recruitment relationship.

$$Logit[\mu_i]=2.706-3.698l_{50}/l_{\infty}$$
where

$$Logit[\mu_i]=Logit[\frac{\mu_i-0.2}{1-\mu_i}]$$


```{r, fig.caption="Estimates of steepness"}
y=2.706-3.698*teleost["l50"]/teleost["linf"]

invLogit<-function(y) 0.2+exp(y)/(1+exp(y))

Steepness=invLogit(y)

hist(Steepness)
```

[Back to Top](#top)

# Dynamics

## Expected dynamics

### `lhEql`

### Functional Forms

exportMethods(ages)  

#### Ogives

exportMethods(knife)  
exportMethods(logistic)  
exportMethods(sigmoid)  
exportMethods(dnormal)  

#### Growth curves

exportMethods(vonB)  
exportMethods(gascuel)  
exportMethods(richards)  
exportMethods(gompertz)  

#### Conversions
exportMethods(len2wt)  
exportMethods(wt2len)  


### Population growth rate

exportMethods(leslie)  
exportMethods(r)  

## Time series dynamics

### `lhStock`

## Density Dependence

exportMethods(grwdd)  
exportMethods(matdd)  
exportMethods(mdd)  

### Natural Mortality

exportMethods(charnov)  
exportMethods(djababli)  
exportMethods(gislason)  
exportMethods(griffiths)  
exportMethods(lorenzen)  
exportMethods(jensen)  
exportMethods(jensen2)
exportMethods(rikhter)  
exportMethods(rikhter2)  
exportMethods(petersen)  
exportMethods(roff)  


@forrest2013modelling

$$N_{t+1}=\frac{N_{t}exp[-M_{\infty}-F_t]}{1+N_t\frac{A}{M_{\infty}+F_t}\{1-exp(-M_{\infty}-F_t)]\}}$$


$$C_t=\frac{F_t}{A}ln{\huge[}1+N_t\frac{A}{M_{\infty}+F_t}[1-exp(-M_{\infty}-F_t)]{\huge]}$$

## Indicators

export(lhRef)  
export(refs)  

exportMethods(lopt)  
exportMethods(loptAge)  


[Back to Top](#top)

# Simulation

## Projections

## Stochasticity

exportMethods(rnoise)  
exportMethods(rod)  

## Management Strategy Evaluation

[Back to Top](#top)

# More Information {#More}

* You can submit bug reports, questions or suggestions on `FLife` at the `FLife` issue page ^[<https://github.com/flr/FLife/issues>], or on the *FLR* mailing list.
* Or send a pull request to <https://github.com/flr/FLife/>
* For more information on the FLR Project for Quantitative Fisheries Science in R, visit the FLR webpage ^[<http://flr-project.org>].
* The latest version of `FLife` can always be installed using the `devtools` package, by calling
```{r, devtools, echo=TRUE, eval=FALSE}
	library(devtools)
	install_github("flr/FLife")
```

## Software Versions

* `r version$version.string`
* FLCore: `r packageVersion('FLCore')`
* FLPKG: `r # packageVersion('FLPKG')`
* **Compiled**: `r date()`
* **Git Hash**: `r system("git log --pretty=format:'%h' -n 1", intern=TRUE)`

## Author information

**Laurence KELL**. laurie@seaplusplus.co.uk

## Acknowledgements

This vignette and many of the methods documented in it were developed under the MyDas project funded by the Irish exchequer and EMFF 2014-2020. The overall aim of MyDas is to develop and test a range of assessment models and methods to establish Maximum Sustainable Yield (MSY) reference points (or proxy MSY reference points) across the spectrum of data-limited stocks.

# References {#References}


[Back to Top](#top)

+ FLife-lhPar
+ data
+ knife
+ logistic
+ dnormal
+ sigmoid
+ FLife-m
+ fapex
+ lhEql
+ lhRef
+ lopt
+ lh-indicators
+ bench
+ lh-srr-sv
+ noise
+ stars
+ FLife-dd-m
+ FLife-dd-mat
+ grw-dd
+ util
+ leslie
+ calcR
+ len-index
+ power
+ spectra
+ t0
+ extendPlusGroup
+ getScriptPath
+ sim
+ knifeEdgeMsy
+ netSel
+ funcs-indicators
+ plot-bivariate
+ reverse
+ priors
+ ggpairs
+ steepness