Intro to fishflux

Nina M. D. Schiettekatte

2020-10-13

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:

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.

CRAN

fishflux will be available on CRAN in the future:

Downloaded package file

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

How to use fishflux?

fishflux is designed to follow three simple steps:

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
ak Element-specific assimilation efficiency _
lt Total length of individual cm
linf Asymptotic adult length (VBGC) cm
κ Growth rate parameter (VBGC) yr − 1
t0 Age at settlement (VBGC) yr
lwa Parameter length-weight relationship g cm − 1
lwb Parameter length-weight relationship _
Qk Element-specific body content percentage %
f0 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 _
Dk 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.

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).

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).

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().

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.

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.000891726 0.0008410607 0.0004495941 0.0002235730 0.001874836
#> 2   6 0.001317985 0.0012601681 0.0006045884 0.0003604474 0.002702572
#> 3   7 0.001841079 0.0017275278 0.0008691326 0.0004733955 0.003936511
#> 4   8 0.002534617 0.0023009884 0.0012327688 0.0007432622 0.005717957
#> 5   9 0.003423418 0.0030763398 0.0018116458 0.0009420382 0.007809264
#> 6  10 0.004632434 0.0039490732 0.0026695962 0.0012405763 0.010781003
#> 7  11 0.005954349 0.0051276278 0.0034472253 0.0015487553 0.014794631
#> 8  12 0.007503680 0.0066551619 0.0041033330 0.0019484337 0.017315841
#> 9  13 0.008734978 0.0079350518 0.0052942788 0.0018462042 0.021195067
#> 10 14 0.011262579 0.0096350599 0.0068389638 0.0023759476 0.027783046
#> 11 15 0.013663431 0.0113080548 0.0092562270 0.0025951915 0.035672540
#> 12 16 0.016392140 0.0140945010 0.0105683125 0.0032472243 0.042271424
#> 13 17 0.020361027 0.0169020651 0.0132857559 0.0043248799 0.052699316
#> 14 18 0.023703776 0.0209608851 0.0148130974 0.0051393534 0.060182665
#> 15 19 0.028556395 0.0235178523 0.0192920100 0.0064376224 0.076617290
#> 16 20 0.031970571 0.0276799379 0.0202742117 0.0076493719 0.072723238
#>          Fn_25%      Fn_75%      Fp_mean    Fp_median        Fp_sd      Fp_2.5%
#> 1  0.0005792635 0.001154257 0.0000832788 4.245923e-05 0.0001021371 2.511666e-06
#> 2  0.0008928070 0.001684304 0.0001558393 7.945118e-05 0.0001871685 5.291524e-06
#> 3  0.0012232373 0.002343984 0.0002695990 1.529615e-04 0.0002957108 8.579473e-06
#> 4  0.0016849313 0.003207564 0.0004491346 2.520125e-04 0.0004888446 1.600994e-05
#> 5  0.0022406034 0.004217267 0.0007534698 4.810078e-04 0.0007359472 3.232229e-05
#> 6  0.0027847600 0.005873477 0.0011405441 7.471972e-04 0.0011083002 4.725158e-05
#> 7  0.0034365678 0.007710832 0.0016540092 1.264513e-03 0.0014312339 8.913606e-05
#> 8  0.0044087932 0.009670517 0.0022057149 1.828365e-03 0.0017082551 1.110360e-04
#> 9  0.0046937011 0.011827304 0.0027040271 2.194159e-03 0.0021550377 1.684206e-04
#> 10 0.0061495882 0.014862146 0.0036866215 3.018865e-03 0.0027415857 2.750029e-04
#> 11 0.0062149813 0.018690248 0.0047425875 3.802769e-03 0.0037343887 4.066305e-04
#> 12 0.0086275102 0.022295784 0.0059248682 5.051299e-03 0.0041788032 7.979501e-04
#> 13 0.0098071300 0.028147265 0.0076292324 6.326970e-03 0.0052905994 1.269442e-03
#> 14 0.0117450007 0.032332387 0.0092231840 7.810513e-03 0.0059388269 1.804364e-03
#> 15 0.0135163339 0.038388078 0.0113879717 9.387295e-03 0.0077277492 2.612289e-03
#> 16 0.0160144072 0.043172443 0.0127362202 1.095476e-02 0.0081343242 3.093322e-03
#>        Fp_97.5%       Fp_25%       Fp_75%
#> 1  0.0003978575 2.199907e-05 0.0000950113
#> 2  0.0006706015 4.006348e-05 0.0001928382
#> 3  0.0010780287 7.386433e-05 0.0003627754
#> 4  0.0018871432 1.253108e-04 0.0006263391
#> 5  0.0026094358 2.118586e-04 0.0011448772
#> 6  0.0041347790 3.503592e-04 0.0015707360
#> 7  0.0052410844 4.936486e-04 0.0024185233
#> 8  0.0063216985 8.020833e-04 0.0032251399
#> 9  0.0078702938 9.493902e-04 0.0038971581
#> 10 0.0104168696 1.475843e-03 0.0052580048
#> 11 0.0135578974 1.655663e-03 0.0068037121
#> 12 0.0165963666 2.763253e-03 0.0082621025
#> 13 0.0209772457 3.569329e-03 0.0105884113
#> 14 0.0238011005 4.332091e-03 0.0126271466
#> 15 0.0303270626 5.330674e-03 0.0151669812
#> 16 0.0292205390 6.490108e-03 0.0171915610

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.

#>    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.000
#> 8  12        c    0.000
#> 9  13        c    0.000
#> 10 14        c    0.006
#> 11 15        c    0.024
#> 12 16        c    0.042
#> 13 17        c    0.064
#> 14 18        c    0.110
#> 15 19        c    0.152
#> 16 20        c    0.132
#> 17  5        n    0.340
#> 18  6        n    0.398
#> 19  7        n    0.466
#> 20  8        n    0.542
#> 21  9        n    0.634
#> 22 10        n    0.670
#> 23 11        n    0.736
#> 24 12        n    0.786
#> 25 13        n    0.778
#> 26 14        n    0.820
#> 27 15        n    0.792
#> 28 16        n    0.872
#> 29 17        n    0.864
#> 30 18        n    0.850
#> 31 19        n    0.832
#> 32 20        n    0.848
#> 33  5        p    0.660
#> 34  6        p    0.602
#> 35  7        p    0.534
#> 36  8        p    0.458
#> 37  9        p    0.366
#> 38 10        p    0.330
#> 39 11        p    0.264
#> 40 12        p    0.214
#> 41 13        p    0.222
#> 42 14        p    0.174
#> 43 15        p    0.184
#> 44 16        p    0.086
#> 45 17        p    0.072
#> 46 18        p    0.040
#> 47 19        p    0.016
#> 48 20        p    0.020
## Plot one variable:
fishflux::plot_cnp(model,  y = "Fp", x = "tl", probs = c(0.5, 0.8, 0.95))

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.

#>              Fn_CI        Fp_CI        Ic_CI
#> Dn_sd 2.128641e-10 0.0002407700 8.598928e-03
#> Dp_sd 1.942812e-10 0.0007203066 2.048520e-09
#> Qn_sd 2.150567e-03 0.0008392983 2.997494e-02
#> Qp_sd 1.961359e-10 0.0007365468 2.050844e-09
#> k_sd  2.008648e-10 0.0001074298 1.032979e-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.