RBBGCMuso

#+BEGIN_HTML <img width="200px" align="right" position="absolute" style="position: absolute; top: 0; right: 0; border: 0;" src="https://raw.githubusercontent.com/hollorol/RBBGCMuso/master/images/logo.jpg" alt="Fork me on GitHub"> #+END_HTML

• The RBBGCMuso Package #+AUTHOR: Roland HOLLÓS, Zoltán BARCZA, Erzsébet KRISTÓF

Please cite this work as follows: Hollós, R., Kristóf, E., Fodor, N., Hidy, D., Horváth, F., Barcza, Z. (2024). RBBGCMuso: an R package to support the application of the [[http://nimbus.elte.hu/bbgc/][Biome-BGCMuSo]] biogeochemical model. URL https://github.com/hollorol/RBBGCMuso.

Current version: 0.7.0

RBBGCMuso is an R package which supports the easy but powerful application of the [[http://nimbus.elte.hu/bbgc/][Biome-BGCMuSo]] biogeochemical model in R environment. It also provides some additional tools for the model such as Biome-BGCMuSo optimized Monte-Carlo simulation and global sensitivity analysis. If you would like to use the framework, please read the following description.

** Installation You can install the RBBGCMuso package in several ways depending on the operating system you use. Up to now RBBGCMuso was tested only in Linux and MS Windows environment, so Mac OS X compatibility cannot be guaranteed yet. In MS Windows you can install the package from binary or from source installer. In Linux you can only install the software from source.

*** Installation in Linux and MS Windows from Source (proposed method) If you would like to install the RBBGCMuso package from Source, you have two options. a) Clone this repository, then build and run the package (further information is available here: [[http://kbroman.org/pkg_primer/pages/build.html][package build and install]]) or b) Install the remotes package first (recommended): #+BEGIN_SRC R :eval no install.packages("remotes") #+END_SRC

Then copy the following line into the R session and execute it: #+BEGIN_SRC R :eval no remotes::install_github("hollorol/RBBGCMuso/RBBGCMuso",upgrade="never") #+END_SRC

We provide support to Biome-BGCMuSo v6 via a separate branch: #+BEGIN_SRC R :eval no remotes::install_github("hollorol/RBBGCMuso/RBBGCMuso",ref="version6",upgrade="never") #+END_SRC

If you use Linux, with Debian (version 8+) you can automate the whole installation process with curl via copying the following line into the Linux terminal: #+BEGIN_SRC bash :eval no bash <(curl -s https://raw.githubusercontent.com/hollorol/RBBGCMuso/Documentation/debianInstaller.sh) #+END_SRC

*** Installation in MS Windows (only for experts) Alternatively, you can also install the latest RBBGCMuso by copying the following line into the R console (using R or RStudio): #+BEGIN_SRC R :eval no source("https://raw.githubusercontent.com/hollorol/RBBGCMuso/master/installWin.R") #+END_SRC

** Quick usage *** Preparation

To start using RBBGCMuso you have to load the package in R with the following command: #+BEGIN_SRC R :eval no library(RBBGCMuso) #+END_SRC

In order to use the RBBGCMuso framework, you have to set up the environment, as you would normally do when you use the model without the RBBGCMuso framework. It means that according to the Biome-BGCMuSo terminology you have to have the proper INI file set, the meteorology input file, the soil input file, and the ecophysiological constants file (EPC) as minimum input. Additional files might be included by the user including nitrogen deposition, management handlers, etc. Please read the corresponding documentation in the [[http://nimbus.elte.hu/bbgc/files/Manual_BBGC_MuSo_v6.1.pdf][actual Biome-BGCMuSo User's Guide]].

If you do not yet have a complete, operational model input dataset, you may want to use the so-called copyMusoExampleTo function (part of RBBGCMuso) which downloads a complete sample simulation set to your hard drive:

#+BEGIN_SRC R :eval no copyMusoExampleTo() #+END_SRC

Once this command is executed in R, it will invoke a small Graphical User Interface (GUI) where you can select the target site for the sample simulation. At present only the "hhs" site is available, which is the abbreviation of the Hegyhátsál eddy covariance station in Hungary. After selecting the site (hhs in this example) the GUI will ask the user to specify a directory (=folder) where the dataset will be stored. In this example we suppose that the user works under MS Windows, and he/she created a directory called C:\model as target directory. It means that after selection of the site the user will select the C:\model directory. Once the copyMusoExampleTo command is finished, the model input dataset and the model executable (called muso.exe and cygwin1.dll) are available in the C:\model folder. The user might check the content of the files using his/her favourite text editor (we propose Editpad Lite as it can handle both Windows and Linux text files). Note that file extension might be hidden by Windows which could cause problems, so we propose to adjust Windows so that file extensions are visible. Visit [[https://www.thewindowsclub.com/show-file-extensions-in-windows][this website]] to learn how to show file extensions in Windows.

In this example the C:\model directory will contain the following files:

• muso.exe - this is the Biome-BGCMuSo model executable for Windows (version might change in the future)
• cygwin1.dll - a so-called DLL file that supports the model execution under Windows
• c3grass_muso7.epc - ecophysiological constants input file for the model (C3 grass in this case)
• n.ini - initialization file for the model, normal mode (INI file controls the entire simulation)
• s.ini - initialization file for the model spinup (also known as self-initialization or equilibrium run)
• hhs_muso7.soi - soil file for the Hegyhátsál simulation
• hhs.mtc43 - meteorology input file
• hhs_muso7.mgm - management definition file for the simulation
• hhs.mow - ancillary management file for mowing
• Ndep.txt - Nitrogen deposition file for the simulation
• CO2.txt - CO_{2} file for the simulation
• parameters.csv - parameter interval file for the sensitivity analysis and optimization
• parameters2.csv - alternative parameter interval file for the optimization that contains allocation parameter intervals
• HU-He2_2012_MEASURED.txt - sample observation file for the Hegyhátsál site (eddy covariance data for 2012)

In the followings we will demonstrate the usability of RBBGCMuso with the hhs example dataset. If you have your own model input data set, you might need to change the commands accordingly.

---

Important note on file naming convention

We propose to use the following filename convention for the INI files. For practical considerations, name your spinup INI file as something_s.ini, and the normal INI file as something_n.ini, where something is arbitrary (note the _s and _n convention). It is not obligatory, but if you do not follow this convention then you have to generate the settings variable manually with the setupMuso command. However, if you do follow this convention, then RBBGCMuSo will automatically recognize your spinup and normal INI file name and content, so the work will be much easier. (See help of setupMuso command in R.) In our example s.ini and n.ini follows this convention, so by default RBBGCMuso will use these files for spinup and normal run, repsectively.

*** Running the model

Now as we have a complete set of input data, we are ready to run the model. You can run the model in spinup mode, in normal mode, or in both phases (including the so-called transient run; see the [[http://nimbus.elte.hu/bbgc/files/Manual_BBGC_MuSo_v6.1.pdf][Biome-BGCMuSo User's Guide]]). Using the runMuso function (that is part of RBBGCMuso) you will be able to execute the the model in both spinup or normal phase, and you can also simplify the execution of both phases consecutively. (Note that runMuso is the same as the obsolete calibMuso function.)

In order to execute the simulation, first you have to set the working directory in R so that RBBGCMuso will find the model and the input files. In our example this is as follows:

#+BEGIN_SRC R :eval no setwd("c:/model") #+END_SRC

(Note the "/" symbol which is different from the "\" that is typically used in Windows!)

In order to run the model as it is provided, simply use the following command in R or RStudio:

#+BEGIN_SRC R :eval no runMuso(skipSpinup = FALSE) #+END_SRC

Note that by default runMuso skips the spinup simulation (in order to speed up the model execution), but in our case we do not yet have the result of the spinup run (the so-called endpoint file which is the initial condition for the normal simulation), so spinup simulation is obligatory. This is performed with the skipSpinup=FALSE parameter. Note that according to the naming convention described above, the model will use s.ini and n.ini for spinup and normal phase, repsectively (this can be changed with the parameters of runMuso if needed). As n.ini represents a grass simulation, the results will provide simulation data on C3 grass ecosystem with management defined by the hhs.mgm file.

If the simulation is successful, the results can be found in the C:\model directory. In our example two files were created with .log extension that contain some information about the spinup and the normal phase. The hhs.endpoint file is the result of the spinup (and optional transient) run, and can be considered as initial conditions for the normal run. (Here we have to note that now runMuso can be called without the skipSpinup parameter which means that the simulation will be restricted to the normal phase only.) The results of the simulation (carbon fluxes, state variables, whatever was set by the user in the DAILY_OUTPUT block of the normal INI file) are available in the file hegyhatsal.dayout. Note that annual output was not requested in this case. Also note that in the hhs example file set binary daily output is created and further processed by RBBGCMuso. One of the most attractive features