Intro to fishflux
Nina M. D. Schiettekatte
2022-05-02
Source:vignettes/intro_to_fishflux.Rmd
intro_to_fishflux.RmdIntroduction
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.
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
| 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.
# example
fishflux::name_errors("Zebrazoma scopas")
#> Joining, by = c("Subfamily", "GenCode", "FamCode")
#> Joining, by = "FamCode"
#> Joining, by = c("Order", "Ordnum", "Class", "ClassNum")
#> Joining, by = c("Class", "ClassNum")
#> 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 = "se")
#> species lwa_m lwa_sd lwb_m lwb_sd
#> 1 Zebrasoma scopas 0.02455 0.002571429 2.98 0.0255102The 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)
#> # A tibble: 1 × 7
#> species Locality k Linf t0 method comments
#> <chr> <chr> <dbl> <dbl> <dbl> <chr> <chr>
#> 1 Sargocentron microstoma Tiahura reef, Moore… 1 18.6 NA lengt… NAFurther, 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.002571429 2.98
#> lwb_sd mdw_m f0_m f0_sd alpha_m alpha_sd
#> 1 0.0255102 0.2504833 0.001517989 3.266339e-10 0.77 0.05286288All 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.0008809183 0.0008151927 0.0004256326 0.0002336029 0.001798249
#> 2 6 0.0013016265 0.0012154231 0.0006222036 0.0003690005 0.002711545
#> 3 7 0.0018729761 0.0017504034 0.0009058180 0.0004707406 0.004014819
#> 4 8 0.0025473858 0.0023856511 0.0012428881 0.0006957930 0.005797087
#> 5 9 0.0033230280 0.0029698290 0.0017168706 0.0009837989 0.007290274
#> 6 10 0.0043701247 0.0039467860 0.0022497210 0.0011795186 0.009877475
#> 7 11 0.0053737687 0.0047270586 0.0032025823 0.0013574598 0.012970492
#> 8 12 0.0070123703 0.0061728159 0.0041015548 0.0015197960 0.016979203
#> 9 13 0.0091464164 0.0077654615 0.0054372311 0.0020567946 0.021857681
#> 10 14 0.0115453118 0.0100570630 0.0071729114 0.0023628319 0.027954356
#> 11 15 0.0126068621 0.0104438653 0.0084566267 0.0019783083 0.033638902
#> 12 16 0.0155049672 0.0133937420 0.0101838928 0.0029401987 0.038458605
#> 13 17 0.0193477989 0.0169810937 0.0120471399 0.0039738707 0.046955444
#> 14 18 0.0228930089 0.0193972686 0.0147869940 0.0055544697 0.060237609
#> 15 19 0.0272873378 0.0239675319 0.0175919659 0.0065536361 0.071973427
#> 16 20 0.0312759657 0.0280576149 0.0189901721 0.0070492683 0.074242142
#> Fn_25% Fn_75% Fp_mean Fp_median Fp_sd Fp_2.5%
#> 1 0.0005638413 0.001106534 8.322228e-05 4.059469e-05 0.0001097935 2.134812e-06
#> 2 0.0008581049 0.001687322 1.560283e-04 8.570931e-05 0.0001850421 6.040276e-06
#> 3 0.0012076115 0.002377333 3.031621e-04 1.632208e-04 0.0003368839 1.190193e-05
#> 4 0.0016356699 0.003201202 4.723046e-04 2.979534e-04 0.0004747899 1.935293e-05
#> 5 0.0020657118 0.004214409 7.070839e-04 4.629491e-04 0.0006685789 3.868201e-05
#> 6 0.0027263065 0.005623727 1.052713e-03 7.109912e-04 0.0009439354 7.220397e-05
#> 7 0.0030942310 0.006728359 1.455219e-03 1.001146e-03 0.0013161550 9.998694e-05
#> 8 0.0038549183 0.009513809 2.033079e-03 1.499564e-03 0.0016606975 1.655032e-04
#> 9 0.0050213343 0.012363498 2.869156e-03 2.314089e-03 0.0022384561 2.086473e-04
#> 10 0.0061355958 0.015547229 3.833662e-03 3.135678e-03 0.0028568768 4.927090e-04
#> 11 0.0062497711 0.017808970 4.319622e-03 3.373803e-03 0.0033946653 2.840730e-04
#> 12 0.0073570900 0.021245273 5.564146e-03 4.769517e-03 0.0040594294 5.434684e-04
#> 13 0.0094795747 0.027764314 7.285789e-03 6.174578e-03 0.0048649629 1.060091e-03
#> 14 0.0114725960 0.030170317 8.861204e-03 7.648932e-03 0.0059379496 1.902300e-03
#> 15 0.0130651629 0.036681743 1.086018e-02 9.537272e-03 0.0070460373 2.693484e-03
#> 16 0.0152336077 0.042943198 1.247017e-02 1.117295e-02 0.0076302156 2.810580e-03
#> Fp_97.5% Fp_25% Fp_75%
#> 1 0.0004141395 1.957939e-05 8.746031e-05
#> 2 0.0006617851 3.896643e-05 1.935556e-04
#> 3 0.0012484895 7.360212e-05 4.423369e-04
#> 4 0.0018146379 1.470088e-04 6.500644e-04
#> 5 0.0023825166 2.077177e-04 1.000131e-03
#> 6 0.0034778966 3.153902e-04 1.641968e-03
#> 7 0.0046524734 4.531934e-04 2.130984e-03
#> 8 0.0063497597 7.298276e-04 3.020271e-03
#> 9 0.0081577189 1.056482e-03 4.182284e-03
#> 10 0.0102697423 1.529479e-03 5.452205e-03
#> 11 0.0129653716 1.702194e-03 6.459664e-03
#> 12 0.0144771338 2.272534e-03 8.073400e-03
#> 13 0.0185829597 3.294120e-03 1.044710e-02
#> 14 0.0241886332 4.229062e-03 1.178966e-02
#> 15 0.0286991089 5.156708e-03 1.461767e-02
#> 16 0.0304047409 6.118613e-03 1.697029e-02Plot 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.000
#> 8 12 c 0.000
#> 9 13 c 0.000
#> 10 14 c 0.010
#> 11 15 c 0.028
#> 12 16 c 0.028
#> 13 17 c 0.080
#> 14 18 c 0.112
#> 15 19 c 0.154
#> 16 20 c 0.146
#> 17 5 n 0.320
#> 18 6 n 0.402
#> 19 7 n 0.490
#> 20 8 n 0.584
#> 21 9 n 0.596
#> 22 10 n 0.672
#> 23 11 n 0.700
#> 24 12 n 0.776
#> 25 13 n 0.802
#> 26 14 n 0.850
#> 27 15 n 0.824
#> 28 16 n 0.846
#> 29 17 n 0.858
#> 30 18 n 0.838
#> 31 19 n 0.822
#> 32 20 n 0.834
#> 33 5 p 0.680
#> 34 6 p 0.598
#> 35 7 p 0.510
#> 36 8 p 0.416
#> 37 9 p 0.404
#> 38 10 p 0.328
#> 39 11 p 0.300
#> 40 12 p 0.224
#> 41 13 p 0.198
#> 42 14 p 0.140
#> 43 15 p 0.148
#> 44 16 p 0.126
#> 45 17 p 0.062
#> 46 18 p 0.050
#> 47 19 p 0.024
#> 48 20 p 0.020
## 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.
fishflux::sensitivity(TL = 10, param = list(k_sd = 0.2, Dn_sd = 0.2, Dc_sd = 0.1),
par = c("k_sd","Dn_sd","Dc_sd"),
out = c("Ic", "In", "Ip", "Gc"))
#> Ic_CI In_CI Ip_CI Gc_CI
#> k_sd 0.03176650 3.811980e-03 1.270660e-03 1.219834e-02
#> Dn_sd 0.26127489 5.293361e-03 1.045100e-02 6.896989e-11
#> Dc_sd 0.01159096 2.408907e-10 8.097665e-11 6.769961e-11More 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.
references
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): 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.