Update README.org

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
 
@@ -133,6 +134,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 +144,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). The structure of the parameters.csv file is simple. First parameter name is needed (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 real numbers are 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:
+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