Intro to fishflux

Introduction

The fishflux package provides a tool to model fluxes of C (carbon), N (nitrogen) and P (phosphorus) in fishes. It combines basic principles from elemental stoichiometry and metabolic theory. The package offers a user-friendly interface to apply the model. fishflux is ideal for fish ecologists wishing to predict ingestion, egestion and excretion to study fluxes of nutrients and energy.

Main assets:

Provides function to model fluxes of Carbon, Nitrogen and Phosphorus for fishes
Allows for the estimation of uncertainty, dpending on the uncertainy of the input parameters
Provides some functions to help find parameters as inputs for the model
Provides functions to extract and illustrate results

Installing and loading fishflux

fishflux uses Markov Chain Monte Carlo simulations provided by stan. Therefore, the first step is to install rstan. It’s important to closely follow all the steps described on the page depending on your operating system.

GitHub

The best way to install the latest development version of fishflux is to install it from GitHub.

install.packages("devtools")
devtools::install_github("nschiett/fishflux", dependencies = TRUE) # if errors are returned, try adding `args = "--preclean"` to `install_github`
library(fishflux)

CRAN

fishflux will be available on CRAN in the future:

install.packages("fishflux")
library(fishflux)

Downloaded package file

Another option is to download the source file available on GitHub here.

install.packages(path_to_fishflux_file, repos = NULL, type = "source")
library(fishflux)

How to use fishflux?

fishflux is designed to follow three simple steps:

Find the right input parameters
Run the model simulation with those input parameters
Plot the model results and check sensitivity

Input parameters

Before running the model, the parameters have to be specified. Below, there is a table showing all parameters needed to run the model simulation. fishflux provides several functions to find some of these parameters, but note that others have to be provided by the user at this stage. Ideally, all parameters should also have a standard deviation, so that their uncertainty can be reflected in the model predictions

. Overview of inputs, including input parameters, to be specified by the user of the model. k indicates c, n or p. VBGC = von Bertalanffy growth curve.
Symbol	Description	Unit
a_k	Element-specific assimilation efficiency	_
l_t	Total length of individual	cm
linf	Asymptotic adult length (VBGC)	cm
κ	Growth rate parameter (VBGC)	yr^− 1
t₀	Age at settlement (VBGC)	yr
lw_a	Parameter length-weight relationship	g cm^− 1
lw_b	Parameter length-weight relationship	_
Q_k	Element-specific body content percentage	%
f₀	Metabolic normalisation constant independent of body mass	g Cg^− αd^− 1
alpha	Mass-scaling exponent	_
theta	Activity scope	_
v	Environmental temperature	C
h	trophic level	_
r	Aspect ratio of caudal fin	_
F0nz	Mass-specific turnover rate of N	g Ng^− 1d^− 1
F0pz	Mass-specific turnover rate of P	g Pg^− 1d^− 1
mdw	Ratio of dry mass and wet mass of fish	_
D_k	Elemental stoichiometry of diet	%

A good place to start is checking if you are using the correct scientific name of your species of interest. The function name_errors will tell you if the species name is correct. This function can be useful, especially when working with larger databases.

# example
fishflux::name_errors("Zebrazoma scopas")
#> Inaccurate species names found:
#> [1] "Zebrazoma scopas"

Once the species names are verified and/or corrected we can continue with specifying some parameters.

The find_lw function searches FishBase to find length-weight relationship parameters lw_a and lw_b extracted from Froese and Pauly (2018).

# example
fishflux::find_lw("Zebrasoma scopas", mirror = "us")
#>            species   lwa_m      lwa_sd lwb_m    lwb_sd
#> 1 Zebrasoma scopas 0.02455 0.002627551  2.98 0.0255102

The model uses parameters von Bertalanffy’s growth model (VBGM) to estimate growth rates. A quick way to get available information from FishBase is the function growth_params(). This can be a good indication, but users should interpret these estimates with a critical eye, as they come from disparate sources of varying accuracy. Alternatively, it is advised to use growth curves derived from otolith readings. In the absence of otolith data, one might consider extracting standardised estimations from Morais and Bellwood (2018).

# example
# The option otolith=TRUE filters out sources that used otoliths for the estimation of growth parameters
fishflux::growth_params("Sargocentron microstoma", otolith = FALSE)
#> Warning: `data_frame()` is deprecated as of tibble 1.1.0.
#> Please use `tibble()` instead.
#> This warning is displayed once every 8 hours.
#> Call `lifecycle::last_warnings()` to see where this warning was generated.
#> # A tibble: 1 x 7
#>   species           Locality                k  Linf    t0 method        comments
#>   <chr>             <chr>               <dbl> <dbl> <dbl> <chr>         <chr>   
#> 1 Sargocentron mic… Tiahura reef, Moor…     1  18.6    NA length-frequ… <NA>

Further, there are a couple more basic functions to get an indication of parameters that are available on FishBase such as trophic_level() and aspect_ratio(). Note that it is always better to get the approximations through analysis, measurements and otolith analysis over parameters extracted from functions, such as growth_params(), trophic_level() and aspect_ratio(). To get an overview of all parameters available, fishflux provides a wrapper function model_parameters().

# example
zebsco <- fishflux::model_parameters("Zebrasoma scopas", family = "Acanthuridae", temp = 27, mirror = "se")
## Here we set the temperature at 27 degrees as an example, this the average sea temperature in Moorea, French Polynesia

print(zebsco)
#>            species    t0 Linf     k     asp troph   lwa_m      lwa_sd lwb_m
#> 1 Zebrasoma scopas -0.49 13.3 0.425 2.02091     2 0.02455 0.002627551  2.98
#>      lwb_sd     mdw_m        f0_m        f0_sd alpha_m   alpha_sd
#> 1 0.0255102 0.2504833 0.001517989 3.248354e-10    0.77 0.05286288

All other parameters have to be provided by the user. For more information on how to acquire these parameters, take a look at (“this paper” add reference to methods paper).

Run model

Once all the parameters are collected, we can run the model through cnp_model_mcmc(). Note that this model can be run with or without specifying the standard deviation (sd) of each parameter. If the sd of a certain parameter is not provided, it will be automatically set to a very low value (1^-10). As mentioned before, it is advisable to include uncertainty of parameters. fishflux is designed to use the MCMC sampler in order to include uncertainty of predictions.

## load the example parameters for Zebrasoma scopas, a list
param_zebsco <- fishflux::param_zebsco
## Run the model, specifying the target length(s) and the parameter list
model <- fishflux::cnp_model_mcmc(TL = 5:20, param = param_zebsco)

The object model now contains all the samples generated from the MCMC simulation and a summary of all parameters generated. To extract certain variables of interest, use the extract() function. Predictions for fluxes of C, N and P are all in g / day.

fishflux::extract(model, c("Fn","Fp"))
#>    TL      Fn_mean    Fn_median        Fn_sd      Fn_2.5%    Fn_97.5%
#> 1   5 0.0008918562 0.0008408784 0.0004290515 0.0002122659 0.001882956
#> 2   6 0.0013114791 0.0012538201 0.0005820036 0.0003810248 0.002631462
#> 3   7 0.0017916098 0.0017089589 0.0008197724 0.0004750130 0.003690186
#> 4   8 0.0025252432 0.0023823468 0.0011681076 0.0007163050 0.005232352
#> 5   9 0.0033911162 0.0030632887 0.0016920209 0.0009403430 0.007550389
#> 6  10 0.0044714257 0.0039054159 0.0023777045 0.0011027718 0.010135643
#> 7  11 0.0057631713 0.0051318031 0.0030890481 0.0013312617 0.013048207
#> 8  12 0.0072336574 0.0065548283 0.0042108854 0.0012578079 0.017067008
#> 9  13 0.0087987793 0.0073719195 0.0054584248 0.0017185809 0.021351379
#> 10 14 0.0116119577 0.0095763834 0.0077379339 0.0022133043 0.031315227
#> 11 15 0.0133856743 0.0117694307 0.0089816563 0.0025272862 0.034922238
#> 12 16 0.0161412155 0.0143993671 0.0106035025 0.0027939475 0.042336007
#> 13 17 0.0199343871 0.0165407515 0.0135289619 0.0040952040 0.052088361
#> 14 18 0.0230752920 0.0193133953 0.0151656193 0.0047323777 0.058654079
#> 15 19 0.0275501454 0.0236823706 0.0180283432 0.0062460980 0.072338950
#> 16 20 0.0315909305 0.0277399383 0.0193087005 0.0074598633 0.075179137
#>          Fn_25%      Fn_75%      Fp_mean    Fp_median        Fp_sd      Fp_2.5%
#> 1  0.0005821678 0.001139030 8.872333e-05 4.495178e-05 0.0001100336 2.025139e-06
#> 2  0.0008644103 0.001653593 1.643654e-04 8.629890e-05 0.0001933846 5.601799e-06
#> 3  0.0012210221 0.002226549 2.668265e-04 1.529679e-04 0.0002907675 1.084862e-05
#> 4  0.0017357183 0.003182602 4.604083e-04 2.609841e-04 0.0004667388 2.900103e-05
#> 5  0.0021884087 0.004261525 7.033628e-04 4.508487e-04 0.0006761813 4.084935e-05
#> 6  0.0028051983 0.005786139 1.079988e-03 7.547368e-04 0.0009840231 4.558991e-05
#> 7  0.0035102648 0.007457774 1.551110e-03 1.237120e-03 0.0012906977 1.117137e-04
#> 8  0.0038875391 0.009866511 2.107776e-03 1.716952e-03 0.0016792780 1.000819e-04
#> 9  0.0047185023 0.011454480 2.717558e-03 2.174023e-03 0.0021425323 2.280607e-04
#> 10 0.0058246645 0.015402803 3.847748e-03 3.069113e-03 0.0030848237 2.871191e-04
#> 11 0.0064968139 0.017950024 4.642032e-03 3.980764e-03 0.0036208959 3.721876e-04
#> 12 0.0077983918 0.021462165 5.868330e-03 5.125744e-03 0.0042372013 7.035444e-04
#> 13 0.0092982886 0.027171171 7.519234e-03 6.232803e-03 0.0054087620 1.229475e-03
#> 14 0.0109347084 0.031682809 8.915068e-03 7.440432e-03 0.0059985435 1.685726e-03
#> 15 0.0130779505 0.037074002 1.094682e-02 9.376824e-03 0.0071438557 2.432880e-03
#> 16 0.0159683412 0.044149427 1.255751e-02 1.115052e-02 0.0076530095 3.010821e-03
#>        Fp_97.5%       Fp_25%       Fp_75%
#> 1  0.0004274985 2.239211e-05 9.502876e-05
#> 2  0.0007343192 4.425307e-05 2.117746e-04
#> 3  0.0010838957 7.664087e-05 3.519734e-04
#> 4  0.0017003880 1.291384e-04 6.576977e-04
#> 5  0.0024758050 2.235132e-04 9.913880e-04
#> 6  0.0036208764 3.441885e-04 1.659160e-03
#> 7  0.0049700091 5.299704e-04 2.154811e-03
#> 8  0.0061495849 6.903495e-04 3.159714e-03
#> 9  0.0077409294 1.019603e-03 3.898876e-03
#> 10 0.0108232286 1.546497e-03 5.538932e-03
#> 11 0.0134547233 1.903011e-03 6.522498e-03
#> 12 0.0163889710 2.549493e-03 8.063435e-03
#> 13 0.0208474530 3.257939e-03 1.032295e-02
#> 14 0.0230779831 4.115967e-03 1.214417e-02
#> 15 0.0289591636 5.310323e-03 1.489879e-02
#> 16 0.0300117277 6.410905e-03 1.755868e-02

Plot results

To visualize main outputs of the model, fishflux contains a plotting function. The function limitation() returns the proportion of iterations of the model simulation that had limitation of C, N and P respectively. The function plot_cnp() plots the predicted output of the model.

## limitation
fishflux::limitation(model)

#>    tl nutrient prop_lim
#> 1   5        c    0.000
#> 2   6        c    0.000
#> 3   7        c    0.000
#> 4   8        c    0.000
#> 5   9        c    0.000
#> 6  10        c    0.000
#> 7  11        c    0.002
#> 8  12        c    0.000
#> 9  13        c    0.002
#> 10 14        c    0.000
#> 11 15        c    0.014
#> 12 16        c    0.048
#> 13 17        c    0.076
#> 14 18        c    0.130
#> 15 19        c    0.148
#> 16 20        c    0.154
#> 17  5        n    0.354
#> 18  6        n    0.424
#> 19  7        n    0.468
#> 20  8        n    0.556
#> 21  9        n    0.600
#> 22 10        n    0.668
#> 23 11        n    0.730
#> 24 12        n    0.774
#> 25 13        n    0.810
#> 26 14        n    0.850
#> 27 15        n    0.840
#> 28 16        n    0.850
#> 29 17        n    0.864
#> 30 18        n    0.826
#> 31 19        n    0.824
#> 32 20        n    0.832
#> 33  5        p    0.646
#> 34  6        p    0.576
#> 35  7        p    0.532
#> 36  8        p    0.444
#> 37  9        p    0.400
#> 38 10        p    0.332
#> 39 11        p    0.268
#> 40 12        p    0.226
#> 41 13        p    0.188
#> 42 14        p    0.150
#> 43 15        p    0.146
#> 44 16        p    0.102
#> 45 17        p    0.060
#> 46 18        p    0.044
#> 47 19        p    0.028
#> 48 20        p    0.014
## Plot one variable:
fishflux::plot_cnp(model,  y = "Fp", x = "tl", probs = c(0.5, 0.8, 0.95))

## Plot multiple variables:
fishflux::plot_cnp(model,  y = c("Fp", "Gp", "Ip", "Wp"), x = "tl", probs = 0.5)

Sensitivity

The function sensitivity() looks at how the distribution of the input variables affects the uncertainty of the model predictions. Basically, the model is run for each input parameter, while keeping all the others fixed. The output of the function gives a matrix of the width of the 95% CI for all model predictions (columns), depending on the input variables (rows). The input parameters and output variables of interest can be specified by arguments “par” and “out” respectively.

## General overview:
fishflux::sensitivity(TL = 10, param = param_zebsco, par = c("Dn_sd", "Dp_sd", "Qn_sd", "Qp_sd", "k_sd"), out = c("Fn", "Fp", "Ic"))

#>              Fn_CI        Fp_CI        Ic_CI
#> Dn_sd 2.033096e-10 0.0002628752 9.388400e-03
#> Dp_sd 2.152683e-10 0.0007523628 2.238387e-09
#> Qn_sd 2.032472e-03 0.0007932098 2.832892e-02
#> Qp_sd 2.083888e-10 0.0007376145 2.156959e-09
#> k_sd  2.115789e-10 0.0001053685 1.013159e-02

More information

For more information on the theoretical framework of the model, see Schiettekatte et al. (2020) ( paper ). Every function of fishflux has a help page with more documentation. In the case of errors, bugs or discomfort, you are invited to raise an issue on GitHub. fishflux is always in development and we are happy to take your comments or suggestions into consideration.

Froese, R., and D. Pauly. 2018. “FishBase.” World Wide Web Electronic Publication.

Morais, Renato A, and David R Bellwood. 2018. “Global Drivers of Reef Fish Growth.” Fish and Fisheries 19 (5). Wiley Online Library:874–89.

Schiettekatte, N.M.D., D.R. Barneche, S. Villéger, J.E. Allgeier, D.E. Burkepile, S.J. Brandl, J.M. Casey, et al. 2020. “Nutrient Limitation, Bioenergetics, and Stoichiometry: A New Model to Predict Elemental Fluxes Mediated by Fishes.” Functional Ecology, no. Accepted Author Manuscript. https://doi.org/10.1111/1365-2435.13618.