Welcome to Fish Bioenergetics 4.0

You can download the latest version of FB4 by clicking a button on this web page. The FB4 software, User Manual, and sample input files are all in the same zipped file. Instructions for getting started are in the User Manual (included in the zip file) and are also summarized below.

We are today (1/26/2023) releasing Version 1.1.5 of the FB4 software. Details for this update are explained at the bottom of this page.

FB4 v1.1.4 was released on 1/21/2023.

FB4 v1.1.3 was released on 5/26/2021.

FB4 v1.1.2 was released on 3/4/2019.

FB4 v1.1.1 was released on 1/28/2019.

FB4 v1.1.0 was released on 10/31/2018.

FB4 v1.0.3 was released on 1/7/2018.

FB4 v1.0.2 was released on 12/13/2017.

FB4 v1.0.1 was released on 12/6/2017.

FB4 v1.0.0 was released on 12/1/2017.

The Open Access article by Deslauriers et al. (2017) gives an introduction to this R-based modeling application.

There are two main goals of this website:

We hope to add information such as the following:

Instructions

Steps to download, install and run Fish Bioenergetics 4.0

Fish Bioenergetics 4.0 (FB4) uses R as a computing language and Shiny through RStudio as the supporting interface. You will need both of these programs in order to be able to run FB4 on your computer.

Note: In some versions of RStudio, the Run App tab does not appear. In that case, type runApp() in the Console window (lower left window) and insert the FB4 folder path inside the parentheses. The folder path should be inside quotation marks and should look something like: runApp(“/Users/david/Desktop/Fish Bioen 4.0”) Once done, press Enter and the application should run.

A similar set of instructions for getting started is in the FB Wiki: FB Wiki

Simulation Setup

Setting up the files needed to run bioenergetics simulations

Once you successfully install and open FB4 you are ready to run bioenergetics simulations. To run a basic simulation, you will need to supplement the program with Initial Settings and Input Files.

Initial Settings

You must first decide on the species you want to use for the simulation. Under the Initial Settings tab, select the species of interest by scrolling through the dropdown menu under Species. You can see the species’ common and scientific name, along with the reference and parameters value on the right-hand side of the screen.

You must then select the duration of your simulation. The duration of the simulation must not exceed the length of time found in the Input Files. In addition, the simulation days are arbitrary and do not fall under any calendar constraints (i.e., day of year). Type your first day in the Initial Day box and your last day in the Final Day box. The days you input here will be used to determine the range of data from the input files to run the simulations.

All simulations require you to input an initial weight (in grams of wet weight) for the fish used in the simulation. Make sure you use a relevant weight that corresponds to the life stage of the species model you are using.

This parameter is used to convert oxygen consumption into an energy unit (Joules/grams of O2) that is compatible with the modeling process. The default value was taken from Stewart et al. (1983) but be aware that all species do not require the same coefficient (see Elliot & Davison 1975 for more information).

This is where you decide what kind of simulation you want to run. By selecting Final Weight, you are telling the program that you want your fish’s final weight (in grams of wet weight) to equal the value you input in the box. The program will then iteratively adjust daily consumption so that the final weight calculated from the simulation matches the final weight you used as an input.

If you select Consumption, the program will use the value you input in the box (in grams of total prey wet weight) and assign the fish a daily consumption value so that the total consumption value from the simulation matches the consumption value you used as an input.

By selecting Ration (g), you are telling the program to feed the fish a constant number of grams of prey every day.

By selecting Ration (%), you are telling the program to feed the fish a constant % of the fish’s wet body weight every day.

Lastly, if you select P-value, the program will calculate a consumption value based on a constant proportion of maximum consumption (Cmax) on any given day. Remember that Cmax will vary depending on water temperature and fish body mass.

Input Files

Input data files contain information that might have been collected in the field, retrieved from historical archives, or obtained from scientific literature. These files are created outside FB4 and are loaded automatically by the program once it is launched. Not all simulations require the same input files but all simulations require the files in the Main Inputs folder to be filled out.

The Main Input files include: Temperature, Prey Energy Density (Prey_E), Prey Proportions (Diet_prop), Predator Energy Density (Pred_E), and Indigestible Prey (only if using Equation 3 for waste losses; see Stewart et al. 1983). All files are saved in .csv format (comma separated values). Default files have been provided with the Fish Bioen 4.0 folder but these can be modified to reflect your own data. To do so, simply replace the days and input data with your own data and save the .csv file before launching FB4. Data are linearly interpolated for the days where the data are missing. You must always have the same number of prey items for each of the input files (except Predator Energy Density) that you plan on using for the simulations.

The mortality file is the one case where daily values are not interpolated. The value specified for one day remains in effect until a different value is specified (see User Manual for details).

Note: All input files must start on day 1. Failure to do so will result in FB4 using the wrong set of days for the simulation.

Once you give FB4 the input data you want to use for your simulation, you can visualize them by selecting the Input Files tab. However, you must make sure that you entered the Initial Day and Final Day sections under the Initial Settings tab. This will allow you to visualize the input data for the time range for which you want to run your simulation. You will also notice that the plots generated under the Input Files tab are reactive. This means that the plots will automatically adjust to reflect the Initial Day and Final Day of your simulation.

Output (to run the program)

Once you have inspected your input data and arranged your initial settings, you can run your simulation. To do so, click on the Output tab and the program will run. As the program runs, a progress bar will be displayed in the lower right corner of the browser window.

After the program finishes running, you will see three tabs under the Output tab: Table, Plot, and Summary.

Under the Table tab, you can see the results of the simulation on a daily basis. To view different outputs, select within the Variables box and many output options will become available. Select the ones of interest and they will appear in the table. Once you have all the data you need, you can download them into a .csv file onto the Fish Bioen 4.0 folder; select the Download button and save the file to the folder.

It is also possible to visualize the outputs in a plot format. To do so, select the Plot tab. This will bring you to a plot with 2 y-axes. You can modify the variables found on either y-axes or the x-axis by scrolling down the dropdown menus below Plot Output.

Finally, by selecting the Summary tab, you will be able to see the final weight, consumption and p-value calculated or used for the simulation. Keep in mind that the p-value is irrelevant if you choose to run a simulation using the Fit to: Ration options.

Design File

It is possible to set up what we call a Design_File to run a series of simulations, one right after the other; this is often called running simulations in batch mode. Using a Design File lets you easily document the initial values and files you used for a set of runs, easily repeat your set of runs if changes are needed, and obtain a summary of the simulation output in a single log file (with one row of summary output per run). Several Design Files are included as examples.

There will be one row in the Design File for each run you do. In the Design File you must specify the input values for each run, which can include different initial weights, final weights, different temperture files, etc. You have more flexibility in naming input files (e.g., Temp_20C.csv, Temp_25C.csv, Temp_30C.csv) compared to running simulation “by hand,” (where the temperature file must be Temperature.csv). You also specify the name of a Log File, which will contain the summary information for each run in the Design File, including final weight and total consumption. For some questions, all the information you need might be in the log file for a set of runs. It is possible to save the full set of daily output values for a run by setting the value of “Save_Daily_Output” for that run to TRUE and naming a corresponding daily-output file.

To run a Design File, you need to make two small changes to the R code, which is easy from RStudio. With RStudio running, look at the FB4 R code showing in the top-left RStudio window. First, around line 25, specify the Design File you want to use; follow the example code near that line. For example, you could remove the comment character (#) from line 24 to make it like this: Design_File = “FB4_Design_Example_1.csv” Second, near line 65, set UseDesignFile to TRUE. (Set UseDesignFile to FALSE to return to doing simulations “by hand.”) Then save those changes in the R code by clicking File Save in the top menu in RStudio. Now, when you click “Run App”, and the browser window opens, click on the Output tab, and the Design File will start running. Check the RStudio Console window to see the messages for each run. When all the runs have completed, open the log file to see the results for your series of runs.

See the note below for v1.1.0 for another brief explanation of how to use Design Files.

FB4 versions: