Merge branch 'Documentation'

RBBGCMuso/R/setupMuso.R

@@ -1,10 +1,10 @@
 #' setupMuso
 #'
-#' This funcion is fundamental for the BiomBGC-MuSo modell related functions like spinupMuso, normalMuso, rungetMuso, because it sets the modells environment.
+#' This funcion is fundamental for the Biome-BGCMuSo model related functions like runMuso, spinupMuso, normalMuso, rungetMuso, as it sets the model's environment. The function reads the INI files from a given directory, analyzes them with error checking, and creates a data structure in R that contains the complete information content for the simulation.  
 #'
-#' @author Roland Hollos
-#' @param parallel Do you want to run multiple modell paralelly, if yes, set this variable to TRUE
-#' @param executable This parameter stores the place of the modell-executable file. In normal usage, you don't have to be set this, because a RBBgcmuso package contains allways the latest modell executable. In spite of this, if you would like to use this package for modell development or just want to use different models (for example for comparison), you will find it useful
+#' @author Roland Hollós
+#' @param parallel Set this variable to TRUE if you would like to implement parallel execution of the model 
+#' @param executable This parameter stores the location (directory) of the modell-executable file. In normal usage, you don't have to set this parameter, because a RBBGCMuso package contains allways the latest modell executable. In spite of this, if you would like to use this package for modell development or just want to use different models (for example for comparison), you will find it useful
 #' @param calibrationPar You may want to change some parameters in your epc file, before you run the modell. You have to select the appropirate modell parameters. You can refence to these with the number of the line in the epc file where the variables are. It indexes from one. You should use a vector for this, like: c(1,5,8)
 #' @param outputLoc Where should the modell puts its outputs. You should give a location for it via this variable, for example: outputLoc="/place/of/the/outputs/"
 #' @param inputLoc Usually it is the root directory, where you put the iniFiles for the modell

RBBGCMuso/inst/examples/hhs/grass_normal.ini

@@ -90,30 +90,30 @@ hegyhatsal
 
 DAILY_OUTPUT
 39 number of daily output variables
-49		0 tsoil[0]
-171		1 evapotranspiration
-159		2 soilw_evap
-397		3 litr1c_total
-398		4 litr2c_total
-399		5 litr3c_total
-400		6 litr4c_total
-518		7 soil1c_total
-519		8 soil2c_total
-520		9 soil3c_total
-521		10 soil4c_total
-313		11 fruitc
+49		1 tsoil[0]
+171		2 evapotranspiration
+159		3 soilw_evap
+397		4 litr1c_total
+398		5 litr2c_total
+399		6 litr3c_total
+400		7 litr4c_total
+518		8 soil1c_total
+519		9 soil2c_total
+520		10 soil3c_total
+521		11 soil4c_total
+313		12 fruitc
 552		13 HRV_transportC
 2520		14 proj_lai
 3017		15 total litterfall aboveground
 3018		16  total litterfall belowground
-2599		17 vwc[0] =soilw layer1 first layer 0-2 cm
+2599		17 vwc[0] soilw layer1 first layer 0-2 cm
 2600		18 vwc[1] the second 2-5 cm 
 2601		19 vwc[2] the third is at 5-10 cm
 2602		20 vwc[3] the fourth is at 10-20 cm
 2603		21 vwc[4] the fifth is at 20-50 cm
 2604		22 vwc[5] the sixth is at 50-100 
 407		23 standing dead biomass 
-3006		24 daily_npp;
+3006		24 daily_npp
 3005		25 daily_nep	
 3009		26 daily_gpp
 3010		27 daily_mr
@@ -121,12 +121,12 @@ DAILY_OUTPUT
 3012		29 daily_hr
 3051		30 litrc
 3052		31 soilc
-3037		32  cum_yieldC_HRV    (kgC/m2)
+3037		32 cum_yieldC_HRV
 74		33 GDD
 1531            34 SUM of the soil mineral NH4 in the total soil [kgN/m2]
 1532            35 SUM of the soil mineral NO3 in the total soil [kgN/m2]
 3013            36 daily soil respiration
-307             37 leafC  -----------------new
+307             37 leafC
 310             38 fine root C
 316             39 soft stem C
 

RBBGCMuso/inst/examples/hhs/hhs_1961-2014.mtc43

@@ -1,4 +1,4 @@
-Hegyhatsal 1961-2014  FORESEE alapjan
+Hegyhatsal 1961-2014 based on FORESEE database
 MTCLIM v4.3 OUTPUT FILE : Wed Jul 29 14:02:27 2015
   year  yday    Tmax    Tmin    Tday    prcp      VPD     srad  daylen
              (deg C) (deg C) (deg C)    (cm)     (Pa)  (W m-2)     (s)

RBBGCMuso/inst/examples/hhs/hhs_2013-2016.mtc43

@@ -1,4 +1,4 @@
-Hegyhatsal FORESEE alapjan
+Hegyhatsal based on FORESEE database
 MTCLIM v4.3 OUTPUT FILE
 year	yday	Tmax	Tmin	Tday	prcp	VPD	srad	daylen
               (degC)   (degC)  (degC)   (cm)    (Pa)   (Wm-2)     (s)

RBBGCMuso/inst/examples/hhs/maize.epc

@@ -166,7 +166,7 @@ CH4 PARAMETERS
 0.010	(DIM) 		param1 for CH4 calculations (empirical function of Tsoil)
 ----------------------------------------------------------------------------------------
 PHENOLOGICAL (ALLOCATION) PARAMETERS (7 phenological phases)
-csirazas  	keles   	levelnov_felfut levelnov_lin	viragzas	szemtelitodes	erett   (text) name of the phenophase
+germination  	emergence   	leafunfold      leafunfoldlin	flowering	grainfilling	maturity (text) name of the phenophase
 0		45		225		630		90		730		10000	 (Celsius) length of phenophase (GDD)
 0.0		0.5		0.60		0.30		0.05		0.0  		0.	 (ratio) leaf ALLOCATION 	                                                                                                                                                                                                                                                           
 0.0		0.5		0.35		0.25		0.20		0.15  		0.	 (ratio) fine root ALLOCATION

RBBGCMuso/inst/examples/hhs/n.ini

@@ -90,23 +90,23 @@ hegyhatsal
 
 DAILY_OUTPUT
 39 number of daily output variables
-49		0 tsoil[0]
-171		1 evapotranspiration
-159		2 soilw_evap
-397		3 litr1c_total
-398		4 litr2c_total
-399		5 litr3c_total
-400		6 litr4c_total
-518		7 soil1c_total
-519		8 soil2c_total
-520		9 soil3c_total
-521		10 soil4c_total
-313		11 fruitc
+49		1 tsoil[0]
+171		2 evapotranspiration
+159		3 soilw_evap
+397		4 litr1c_total
+398		5 litr2c_total
+399		6 litr3c_total
+400		7 litr4c_total
+518		8 soil1c_total
+519		9 soil2c_total
+520		10 soil3c_total
+521		11 soil4c_total
+313		12 fruitc
 552		13 HRV_transportC
 2520		14 proj_lai
 3017		15 total litterfall aboveground
 3018		16  total litterfall belowground
-2599		17 vwc[0] =soilw layer1 first layer 0-2 cm
+2599		17 vwc[0] soilw layer1 first layer 0-2 cm
 2600		18 vwc[1] the second 2-5 cm 
 2601		19 vwc[2] the third is at 5-10 cm
 2602		20 vwc[3] the fourth is at 10-20 cm
@@ -126,7 +126,7 @@ DAILY_OUTPUT
 1531            34 SUM of the soil mineral NH4 in the total soil [kgN/m2]
 1532            35 SUM of the soil mineral NO3 in the total soil [kgN/m2]
 3013            36 daily soil respiration
-307             37 leafC  -----------------new
+307             37 leafC
 310             38 fine root C
 316             39 soft stem C
 

RBBGCMuso/inst/examples/hhs/parameters.csv

@@ -1,7 +1,7 @@
 NAME,INDEX,MIN,MAX
 BASETEMP,25,3,9
 WPM,36,0,1
-keles,170.61,0,1000
+EMERGENCE,170.61,0,1000
 CN_lv,38,10,50
 CN_li,39,32,70
 CN_root,40,20,90

RBBGCMuso/inst/examples/hhs/sensitivity.csv

@@ -1,16 +0,0 @@
-"","x"
-"BASETEMP",1.33
-"WPM",0.18
-"CN_lv",0.67
-"CN_li",5.72
-"CN_root",0.34
-"CN_fruit",0.13
-"CN_stem",0.59
-"CLEC",4.67
-"FLNR",26.17
-"STOMA",0.79
-"ROOTDEPTH",18.98
-"SWCGERMIN",0.01
-"MAXLIFETIME",0.09
-"NH4MOBILEPROP",0.33
-"keles",39.99

README.org

@@ -55,17 +55,18 @@ Once this command is executed in R it will invoke a small Graphical User Interfa
 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 5.0 model (version might change in the future)
-- cygwin1.dll - a so-called DLL file that supports the model execution
+- muso.exe - this is the Biome-BGCMuSo 5.0 model executable for Windows (version might change in the future)
+- muso - this is the model executable for Linux
+- cygwin1.dll - a so-called DLL file that supports the model execution under Windows
 - c3grass.epc - ecophysiological constants input file for the model (C3 grass in this case)
 - maize.epc - another ecophysiological constants input file (C4 maize in this case)
 - n.ini - initialization file for the model, normal mode (INI file controls the entire simulation)
-- normal_grass.ini - another initialization file for the model, for the C3 grass simulation
+- grass_normal.ini - another initialization file for the model, for the C3 grass simulation
 - s.ini - initialization file for the model spinup (also known as self-initialization or equilibrium run)
-- parameters.csv - a simple text file to support sensitivity analysis and parameter sweel (see below)
-- hhs_1961-2014.mtc43 - meteorology input file; this file is used for spinup simulation
+- parameters.csv - a simple text file to support parameter sweep and sensitivity analysis (see below)
+- hhs_1961-2014.mtc43 - meteorology input file; in this example this file is used for spinup simulation
 - hhs_2013-2016.mtc43 - meteorology input file for the normal simulation
-- CO2_from1961.txt - CO_{2} file for the normal simulation
+- CO2_from1961.txt - CO_{2} file for the transient simulation
 
 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. 
 
@@ -74,7 +75,7 @@ In the followings we will demonstrate the usability of RBBGCMuso with the hhs ex
 ----------
 *Important note on file naming convention*
 
-We propose to use the following filename convention for the INI files. For practical reasons, 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 
+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. 
 ----------
@@ -98,9 +99,9 @@ In order to run the model as it is provided simply use the following command in
 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), 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, repsectivelt. It means that the 3rd ini file is not used in this case. As n.ini represents a maize simulation, the results will provide simulation data on C4 maize monoculture with predefined management defined by the n.ini file. 
+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), 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). It means that the 3rd ini file is not used in this case (grass_normal.ini). As n.ini represents a maize simulation, the results will provide simulation data on C4 maize monoculture with predefined management defined by the n.ini 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 of RBBGCMuso is that the model output is handled by the package which means that it will be directly available for the user for further processing in R. 
+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 of RBBGCMuso is that the model output is handled by the package which means that it will be directly available for the user as a variable for further processing in R. 
 
 *** Visualization of the model output
 
@@ -125,6 +126,12 @@ plot(gpp*1000)
 #+END_SRC
 
 Note that the 1000 multiplier is needed to get GPP in gC/m^{2}/day units.
+The result should look like this image:
+
+#+BEGIN_HTML
+<img width="600px"  
+src="https://raw.githubusercontent.com/hollorol/RBBGCMuso/Documentation/images/gpp01.png" alt="GPP plot">
+#+END_HTML
 
 Now get the 4th year from the dataset and plot it:
 
@@ -133,6 +140,8 @@ gpp4<-gpp[(3*365+1):(4*365)]
 plot(gpp4*1000,type="l")
 #+END_SRC
 
+Advanced visualization of the results is possible with plotMuso.
+
 *** Perform Quick experiments
 
 Assume that we would like to dig a bit deeper with the model and understand the effect of changing ecophysiological variables on the model results. This can easily be performed with RBBGCMuso. Execute the following command in R/RStudio:
@@ -141,23 +150,24 @@ Assume that we would like to dig a bit deeper with the model and understand the
 musoQuickEffect(calibrationPar = 25, startVal = 0, endVal = 9, nSteps = 5, outVar = 3009)
 #+END_SRC
 
-This command selects the 265h line in the ecophysiological constants (EPC) file (this is base temperature), then it starts to replace the original value from 0 to 9 in 5 consecutive steps. In this example GPP is selected (variable number 3009, which is the 26th variable), so the effect of varying base temperature on GPP is calculated using 9 simulations. The result is a spectacular plot where color coding is used distinguish the parameter values. 
+This command selects the 25th line in the ecophysiological constants (EPC) file (this is base temperature), then it starts to replace the original value from 0 to 9 in 5 consecutive steps. In this example GPP is selected (variable number 3009, which is the 26th variable), so the effect of varying base temperature on GPP is calculated using 5 simulations. The result is a spectacular plot where color coding is used distinguish the parameter values. 
+At present musoQuickEffect is not usable for the allocation parameters due to restrictions of the allocation fractions.  
 
 *** Study the effect of ecophysiological parameters using paramSweep
 
-The paramSweep function is the extension of the musoQuickEffect. It can test the effect of the selected parameters on the model results in once. The result of the paramSweep function is a single HTML file with embedded images. paramSweep needs a csv file called parameters.csv which defines the parameters of interest and the corresponding parameter intervals. In case of the hhs sample dataset there is an example parameters/csv file (please open it and check). Note that there is a tricky part in the parameters.csv as the parameter selection is not straightforward in case of multiple columns (see the end of the EPC file). The logic is that real numbers are used to select the appropriate parameter from multiple columns. In the provided example "keles,170.61,0,1000" means that in the 170th line of the EPC file there are 7 columns (numbering starts from 0, so it is 6), and we would like to adjust the 2nd column (marked by 1), which ends up with 170.61. 0,1000 means that sweep starts at 0 and ends with 1000. Invoke the paramSweep with simply issuing this command:
+The paramSweep function is the extension of the musoQuickEffect. It can test the effect of the multiple selected parameters on the model results in once. The result of the paramSweep function is a single HTML file with embedded images. paramSweep needs a csv file called parameters.csv which defines the parameters of interest and the corresponding parameter intervals. In case of the hhs sample dataset there is an example parameters/csv file (please open it and check). The structure of the parameters.csv file is simple. First, parameter name is needed (it can be anything but should refer to the parameter), then the line number of the EPC file is provided, then the possible minimum and maximum value of the parameter is given. Note that there is a tricky part in the parameters.csv as the parameter selection is not straightforward in case of multiple columns (see the end of the EPC file). The logic is that fractinal part of a number is used to select the appropriate parameter from multiple columns. In the provided example "emergence,170.61,0,1000" means that in the 170th line of the EPC file there are 7 columns (numbering starts from 0, so it is 6), and we would like to adjust the 2nd column (marked by 1), which ends up with 170.61. 0,1000 means that sweep starts at 0 and ends with 1000. Invoke the paramSweep with simply issuing this command:
 
 #+BEGIN_SRC R :eval no
 paramSweep()
 #+END_SRC
 
-*IMPORTANT NOTE: After the execution of this command a pop-up window will be opened to select the appropriate parameters.csv file. Due to some R related issues at present the dialog window will appear BEHIND THE MAIN R WINDOW, so it might be hidden from the user. Please check the Windows taskbar and find the dialog window, then select the parameters.csv.*
+*IMPORTANT NOTE: After the execution of this command a pop-up window will be opened to select the appropriate parameters.csv file. Due to some R related issues at present the dialog window might appear BEHIND THE MAIN R/Rstudio WINDOW, so it might be hidden from the user. Please check the Windows taskbar and find the dialog window, then select the parameters.csv.*
 In advanced mode there is possibility to select the parameters.csv file using the parameters of paramSweep. 
 
 *** Sensitivity analysis
 
-[[http://agromo.agrar.mta.hu/files/musoSensi_usage_v6_FINAL.pdf][See this link for details about the sensitivity analysis.]]
-Note that parameters.csv is provided in the hhs example dataset, so you don't have to create it manually.  
+Advanced sensitivity analysis is possible with the musoSensi function of RBBGCMuso. [[http://agromo.agrar.mta.hu/files/musoSensi_usage_v6_FINAL.pdf][See this link to read the manual of the sensitivity analysis.]]
+Note that parameters.csv is provided in the hhs example dataset, so you don't have to create it manually. At present sensitivity analysis is not possible for the allocation parameters due to restrictions of the allocation fractions.  
 
 *** Contact