README.Rmd

---
output: github_document
---

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

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```
# rfishprod

<!-- badges: start -->
<!-- badges: end -->

Implements a framework to generate individual-level estimates
    of fish productivity, with a focus on reef fishes. This individual
    approach works by combining estimates of somatic growth through the
    von Bertalanffy Growth Model, and deterministic or stochastic natural
    mortality using instantaneous mortality rates.

## Installation

You can install rfishprod from [GitHub](https://github.com/renatoamorais/rfishprod) with:

``` r
devtools::install_github("renatoamorais/rfishprod")
```

To get [`devtools`](https://cran.r-project.org/web/packages/devtools/index.html), simply use `install.packages("devtools")`.

Although not a dependency, I recommend using R 4.5.2 (or higher). This is mainly because [`xgboost`]( https://CRAN.R-project.org/package=xgboost), the machine behind internal prediction, demands R 4.3.0 as a minimum and you don't want to be stuck with an older R version.

## NEWS!

Some time ago (August 2022), I started working on the package again. Then I had to stop it. It gets tricky to catch up with old projects... I have just now (May 2026) updated predKmax to ensure it is compatible with the new argument structure from xgboost. If you've been finding issues running rfishprod, remove and reinstall the package and xgboost, and please let me know if issues continue. People were get the following errors: 1) negative Kmax estimates; 2) errors with factors. First case stems from the distribution of the predKmax xgboost model (Gamma) not being passed on to xgboost due to argument mismatches. The new fix solves issue (all of this is handled internally, so nothing changes in the code, it just means that predKmax should work again). Thanks Erin Dillon for pointing out the problem! The second error typically stems from not checking and standardising variables. I have now updated tidytrait so that it handles the most common forms of mismatch (often due to misspelling) within its own structure. 

## Previous updates

On ***08.08.2022***: included an alternative parameterisation of the VBGM, the original one specifying the intercept (L0 or length at age 0). This is a biologically intuitive and more relevant form. It also ends arbitrarities of the rare instances when surveyed fishes were smaller than the estimated L0 from the model. This more natural form is recommended, but requires specifying for each fish its settlement size. In practice it is just another column in the data. If L0 is not specified, model keeps running business as usual.

On ***02.08.2022***: included the empirical equation to estimate instant mortality from Lorenzen et al (2022) Fish Res 252:106327. Also changed the method = 'Function' to leave the exponent of the relationship between mortality and body length adjustable by the user (it was fixed as -0.75) given evidence of the same paper that this exp could be closer to -1 (value of -0.91 set as default, see Table 2, model 3 in this ref).


## Example


```{r example, eval = F}
library(rfishprod)

# Check dataset repdata #
(repdata <- rfishprod:::repdata)

# Getting levels ready #
repdata <- tidytrait(repdata, db)

# Formula from Morais and Bellwood (2018) #
fmod <- formula(~ sstmean + MaxSizeTL + Diet + Position + Method)

# Predicting Kmax, the standardised VBGF parameter (Recommendation: use 100s to 1000s iterations) #
datagr <- predKmax(repdata, 
                   dataset = db,
                   fmod = fmod,
                   niter = 10,
                   return = 'pred')

datagr <- datagr$pred

# Predicting M/Z: the instantaneous mortality rate (Recommendation: see help file for) #
# Using the Lorenzen equation
datagr$Md <- with (datagr, 
					predM (Lmeas = Size, 
						     Lmax = MaxSizeTL, 
						     Kmax = Kmax, 
						     method = 'Lorenzen'))
# But also the Gislason one
datagr$Md <- with (datagr, 
					predM (Lmeas = Size, 
						     Lmax = MaxSizeTL, 
						     Kmax = Kmax, 
						     method = 'Gislason'))
						   

# Positioning your fish in their growth trajectory #
# aka. what's the size they're supposed to have on the next day? #
# now using L0, i.e., size at settlement, to constrain the curve #
with(datagr, applyVBGF(Lmeas = Size,
                       Lmax = MaxSizeTL,
                       Kmax = Kmax,
                       L0   = L0))
						 
# Compare with their size on the previous day #
datagr$Size

# Estimating gross somatic growth (g) #
with(datagr, somaGain(a = a,
                      b = b,
                      Lmeas = Size,
                      Lmax = MaxSizeTL,
                      Kmax = Kmax))
						      
# Applying stochastic mortality #
applyMstoch(datagr$Md)


# Alternatively, estimating per capita mass loss due to mortality #
with(datagr, somaLoss(M = Md,
                      Lmeas = Size,
                      a = a,
                      b = b))

```

## Citation

If you're using `rfishprod`, please make sure you cite the works that originated it. The citations for the package can be obtained from:

```{r, eval = FALSE}
citation("rfishprod")
```


## Issues

Please [report issues or bugs](https://github.com/renatoamorais/rfishprod/issues) or shoot me an email (just hit `?rfishprod`)