-------------------------------------------------------------------------------- Help Information Topics -------------------------------------------------------------------------------- * Introduction * Caveats * Program Input - Experimental Data * Default Model Fitting Parameters * Saving and Restoring Modeled Fit Parameters * Program Output - Graphical and Text * Fitting Types - Carbon Assimilation Rate vs. Leaf Internal [CO2] - Carbon Assimilation Rate vs. Illumination - Carbon Assimilation Rate vs. Temperature - Carbon Assimilation Rate: Observed vs. Modeled - Leaf Stomatal Conductance: Observed vs. Modeled * Preparing A Data File - Data Name, Data Format And Data Field Strings - Valid Field Labels and Units * Appendices - A1: Working With The Slider GUI - A2: Slider Ranges - A3: Model Parameters -------------------------------------------------------------------------------- Introduction -------------------------------------------------------------------------------- Program "Fit Plant Photosynthesis Data" is used to fit photosynthesis parameters for C3 or C4 models to: * Assimilation vs. Ci data * Assimilation vs. Illumination data * Assimilation vs. Temperature data * Assimilation Observed vs. Modeled * Stomatal Conductance Observed vs. Modeled Parameters are fit either manually or automatically. Manually fitting of the model fitting parameters is done by using sliders to adjusting the values of the model fitting parameter, running the model with the new set of parameter, and comparing the results with results obtained using a different set of parameters. Automatic fitting of the model fitting parameters is done with the click of a button, which calls a least-squares fitting routine to calculate the set of fitting parameters that minimizes the difference between the experimental data and the model results(see caveat below). -------------------------------------------------------------------------------- Caveats -------------------------------------------------------------------------------- The code is constantly being enhanced, so implementation of some features may be incomplete. Modeling with the Ball-Berry stomatal conductance code has not been implemented for C4 chemistry. The biggest caveat is that this help information is probably not current. -------------------------------------------------------------------------------- Program Input - Experimental Data -------------------------------------------------------------------------------- Experimental data for driving the model is read from Excel tab-delimited text files. However, any tab-delimited text file is acceptable. (Comma separated fields may still work.) There are a number of formatting rules for this data that must be followed. In brief: * A datafile can include multiple datasets. * Each dataset of a multi-dataset file can have a separate label. * Only a single dataset of a multi-dataset file can be analyzed at a time. * Datasets not currently being analyzed must be "commented out". * Any row starting with a ";" as the first non-whitespace character is considered a comment. * Two rows of text strings must be included in the data file to specify the datafile format. * The program requires particular labels for particular data, and associates each data label with particular units of measure. Refer to the section "Preparing A Data File For This Program" (below) for details. -------------------------------------------------------------------------------- Default Model Fitting Parameters -------------------------------------------------------------------------------- The default model fitting parameter sets are read from a file that is an Excel tab-delimited text file. These parameter sets are based upon the Biomes of Sellers et.al, J. Climate, v9:701, 1996. The different default parameter sets can be selected with the Parameters > Default Parameter Set menu item. Note that "Biome_6" is the only C4 parameter set. The default parameter file (parameters.txt) includes two rows of text strings that specify the format of the parameter file. Only one such pair of rows should be present (and uncommented) in the file, and all rows of parameters must be the same format. The default parameter file is read at program start-up, and is re-read when the Parameters > Re-Read Default Parameters button is selected. Therefore, it is possible to change a default value in the parameter set without restarting the program. Note that although it is possible to alter this file from within your favorite text editor, it is safer to alter it from within Excel. -------------------------------------------------------------------------------- Saving and Restoring Modeled Fit Parameters -------------------------------------------------------------------------------- The model fit parameters that are used to fit a dataset can be saved to a file using dialog opened with the Parameters > Save Parameters menu item. Multiple datasets can be saved in the same file. A comment and a fit name can be saved with each of the saved parameter sets. The format of these parameter set files is the same as the format used for the file of default parameter sets: an Excel tab-delimited text file. A pair of rows of text strings describe the format of each saved parameter set. However, by default, only the first of the pairs of format strings in the file is un-commented, and the parameter sets are in rows below the pair of format strings. Note that although it is possible to use your favorite text editor to alter a parameter file, e.g., to change a comment, it is safer to use Excel to make alterations. -------------------------------------------------------------------------------- Program Output -------------------------------------------------------------------------------- The program can save the plot and the values of the parameters used for the fit, as a PostScript file. The program can also save the model results in a file as columns of data for input into Excel. A subset of the input data and the values of the model fitting parameters (but not all of the model parameters) are included. In addition, the program will pass a Postscript file (printme.ps) to the GhostView program, from which the Postscript file can be printed. For Linux, 'gv' must be in the shell path. For Win XP, GSview='C:\Program Files\Ghostgum\gsview\gsview32.exe' For Mac OSX, MacGhostView ='/Applications/MacGhostView\ Folder/MacGhostView' -------------------------------------------------------------------------------- Fitting Modeling Carbon Assimilation Rate vs. Internal [CO2] -------------------------------------------------------------------------------- When modeling the assimilation rate of carbon vs. the leaf internal CO2 concentration, the parameters Vmax and Smax are fit for C3 chemistry. For C4 chemistry, parameters Vmax and rrkk are fit. For details on parameters Smax and rrkk, see the code in c3_plant.pro and c4_plant.pro, respectively. Selecting the AvC fitting type sets the active state of the sliders to the defaults for this fitting type and the current chemistry. See "Working with the Slider GUI" (below) for more information on the slider GUI. The chemistry is set from the parameter set selected. Note that C3 data is not well modeled with the C4 model, and C4 data is not well modeled with the C3 model. When using "Autofit" with the C4 model, it is often necessary to manually adjust the C4 fitting parameters to a reasonably good fit, or the fitting routine will not converge. Failure to converge is less of an issue with the C3 model. -------------------------------------------------------------------------------- Fitting Carbon Assimilation Rate vs. Illumination -------------------------------------------------------------------------------- The fitting parameters for modeling the carbon assimilation rate vs. illumination are the same for C3 and for C4, but depend upon the type of illumination data. Selecting the AvI fitting type sets the active state of the sliders to the defaults for this fitting type and the type of illumination data. See "Working with the Slider GUI" (below) for more information on the slider GUI. If the type of illumination data is PAR (PAR_umol) or short wave radiation down (swd_wpm2), then the fitting parameters are Vmax, atheta, PAR_alb and respcp. If the type of illumination data is APAR (APAR_umol), then the fitting parameters are Vmax, atheta, and respcp. The PAR albedo is included (by definition) in the APAR data, and is not when APAR illumination data id provided. The units of illumination for APAR and PAR are umol m-2 s-1, and the units of illumination for short wave radiation down are W m-2. -------------------------------------------------------------------------------- Fitting Carbon Assimilation Rate vs. Leaf Temperature -------------------------------------------------------------------------------- The parameters used for fitting the carbon assimilation rate vs. leaf temperature are the same for C3 and for C4: Vmax, hhti and respcp. Selecting the AvA the fitting type sets the active state of the sliders to the defaults for this fitting type. -------------------------------------------------------------------------------- Fitting Carbon Assimilation Rate: Observed vs. Modeled -------------------------------------------------------------------------------- Selecting the AvA fitting type sets the active state of the sliders to the defaults for this fitting type for the current chemistry and illumination units. See "Working with the Slider GUI" (below) for more information on the slider GUI. AvA fitting is intended for data sets with mixed AvC, AvI and AvT data. However, AvA fitting can be run on any set of data that can be run with another fitting type. For example, if data is run with Assimilation rate vs. leaf internal [CO2], then AvA can also be run. AvA fitting can be run with or without the Ball-Berry stomatal conductance code, but only can run BB if sufficient data is present to run the stomatal conductance code. -------------------------------------------------------------------------------- Fitting Leaf Stomatal Conductance: Observed vs. Modeled -------------------------------------------------------------------------------- Stomatal conductance is modeled using the Ball-Berry method, subject to sufficient data being read from the data file. The presence of adequate inputs is verified by the program. Selecting the GvG fitting type opens a separate GUI of sliders, and a small "Stomatal Parameters" window. The active state of the sliders are set for the current chemistry and illumination units. See "Working with the Slider GUI" (below) for more information on the slider GUI. The "Stomatal Parameters" window displays a plot of An*hs/cs vs. Gsw for the data read, and sliders for the stomatal parameters Gradm and Bintc. The values to which these parameters are initially set are calculated from the slope and intercept of a linear fit to the data in the plot. The best-fit values can be overridden using the sliders in this window, or re-calculated using the "Best Fit" button. The "Reset Button" resets the values to the values in the parameter most recently loaded. Because the Ball-Berry stomatal conductance code must be used for GvG fittings, selecting GvG fitting sets the "Ball-Berry" Yes-No button to "Yes". Running the Ball-Berry stomatal conductance code requires either of the two data combinations. The first combination is for data available in gas-exchange datasets. The second combination is for the default LiCor datasets. Program labels and descriptions for gas-exchange data: Program Description and units ------- ------------------------------------------------------ Ca_ppm Ambient [CO2], umol CO2 mol air-1 Ci_ppm Leaf internal [CO2], umol CO2 mol air-1 assimn_umol Net carbon assimilation rate, umol m-2 s-1 gsw_mol Stomatal Conductance, mol m-2 s-1 pwa_Pa Ambient water vapor pressure, Pa Cs_ppm Leaf surface [CO2], ppm Hs_pct Relative humidity at leaf surface, % LiCor names, program labels and descriptions for LiCor data: LiCor Program Description and units ----- ------- ------------------------------------------------------ CO2S Ca_ppm Ambient (sample chamber) CO2, umol CO2 mol air-1 Ci Ci_ppm Leaf interior [CO2], umol CO2 mol air-1 Photo assimn_umol Net photosynthesis rate, umol CO2 m-2 s-1 Cond gsw_mol Stomatal conductance to H2O, mol H2O m-2 s-1 BLCond BLcond_mol TOTAL boundary layer conductance, mol m-2 s-1 StmRat StmRat Stomatal "ratio" - *fraction* of stomatal conductances of one side of the leaf to the other, unitless Press ptot_kPa Atmospheric Pressure, kPa Trmmol E_mmol Transpiration rate, mmol H2O m-2 s-1 H2OS ea_mmol Ambient (sample chamber) water vapor mixing ratio,, mmol H2O mol-1 These last 5 data in the LiCor default datasets are used to calculate the last three data of the gas-exchange datasets: pwa_Pa, Cs_ppm and Hs_pct. See file "filemenu_ops.pro" for the code that performs these calculations. In addition to the above listed data, leaf temperature and illumination data will presumably also be provided when modeling stomatal conductance. However, if these are are not provided, default parameter file values will be used. Tc or Tk - Leaf temperature (C or K) PAR_umol or APAR_umol - PAR or Absorbed PAR or PAR, umol quanta m-2 s-1 LiCor names, program labels and descriptions for LiCor data: LiCor Program Description and units ----- ------- ------------------------------------------------------ Tleaf Tc Leaf temperature,C PARi PAR_umol In-chamber PAR, umol m-2 s-1 -------------------------------------------------------------------------------- Preparing A Data File For This Program -------------------------------------------------------------------------------- This discussion is dated. To get the program to run with IDL 6.0 Run Time, the READCOL program may need to be replaced with the IDL READ_ASCII program, which uses a different format specification method. Currently the program can read tab-delimited text files saved from Excel. Format strings can be in separate Excel fields, but must be separated by commas. A new keyword "data_name" has been implemented so that each dataset within a multi dataset file can have a unique name. data_name "this is the data name" The quotes are not required. When saving a Postscript or text output file, this data_name string gets converted to a filename with the base as 'this_is_the_data_name' plus a three letter extension. - begin original discussion - The columns of data in the datafile are read by the public routine READCOL, http://www.astro.washington.edu/deutsch-bin/getpro/library32.html?READCOL A data file for this program must have data in white space or comma separated columns. The program reads columns of data from the data file based upon a format specified by "format" and "fields" strings that must be edited into the data file above the start of the data. Comments can be included in the data files by starting the comment line with a "%", "#" or a ";" character (see FYI note, below). "Format" and "fields" strings must be inserted in the data file on non-comment lines. These strings are used with the READCOL routine to read columns of data from the data file into program arrays. The "fields" string is also used by the program to determine which data is being supplied. The "format" string is a comma separated list of letters specifying an IDL data type for each column of data to be read. This string is passed to READCOL with the input keyword "FORMAT". Letters of interest in this program are: F - floating point, D - double precision, I - Integer, L - longword, and X - skip a column. The autofit routine seems to work better with double precision data. Here is an example of a "format" string: format L,F,F,X,X,X,F,F,X,X The "fields" string is a comma separated list that contains the names of the arrays into which READCOL copies the data columns. This string is turned into an argument list for READCOL. Here is an example of a "fields" string: fields date, APAR_umol, assim_umol, Ci_ppm, Tc See the header in file READCOL.pro for more information on READCOL. The words "format" and "fields" are keywords that must proceed the strings, and be separated from the strings that follow on the line by whitespace. For example, here are two rows of comments and three rows of data (in 10 columns): ;Field 2 3 4 5 6 7 8 9 10 ;DATE I A GS HS CS CI TL VPD GSTAR 82890 1457 2.1 0.77 0.836 59 54 24.9 516.314 38.2842 82890 1457 5.5 0.88 0.848 87 76 24.8 475.687 38.0696 82890 1457 14.4 0.93 0.853 170 144 24.8 460.04 38.0696 For this example, the following "format" and "fields" lines are inserted into the data file before the data so that the program can read the illumination, gross carbon assimilation rate, internal [CO2] and leaf temperature data columns: ;Field 1 2 3 4 5 6 7 8 9 0 format L,F,F,X,X,X,F,F,X,X fields date, APAR_umol, assim_umol, Ci_ppm, Tc NOTE: No comma at the end of the line! Although whitespace is required immediately after the keywords "format" and "fields", other whitespace on these lines ignored. The numbering of the fields as shown here is helpful for keeping track of the data columns, but is not required. Each 'X' in the "format" string indicates a column that is to be ignored when reading the data file. In the above example, the GS, HS, CS, VPD and GSTAR columns are to be ignored. The first column in this example ("DATE") must be evaluated so that READCOL doesn't read any comment lines as data. Note that this first column must be read as a long because the data value (82890) overflows an integer (and caused a program error). FYI note: READCOL doesn't actually have a "comment" symbol. Rather READCOL drops rows that cannot match the format given by the "format" and "fields" strings. Thus, READCOL skips the "format" and "fields" string definitions, and rows in which the first character cannot be interpreted as an integer, because the format of the row does not match the expected format. -------------------------------------------------------------------------------- Valid Field Labels and Units -------------------------------------------------------------------------------- With the field labels, spelling is important but the character case is ignored when parsing the "fields" string for the label. The labels for AvC, AvI and AvT data are: Ci_ppm - Internal CO2 concentration, umole mole-1 Either gross or net carbon assimilation rate: assim_umol - Gross rate of C assimilation, umol m-2 sec-1 assimn_umol - Net rate of C assimilation, umol m-2 sec-1 One of the illumination data types: PAR_umol - PAR, umol quanta m-2 sec-1 APAR_umol - APAR, umol quanta m-2 sec-1 swd_wpm2 - Short wave radiation down, watts/meter^2 Leaf temperature in either Celsius or Kelvin: Tc - Leaf temperature, C Tk - Leaf temperature, K Note that if using AvC fitting, only leaf interior [CO2] and assimilation data are required, for AvI fitting, only illumination and assimilation data are required, and for AvT only, only temperature and assimilation data are required. In each of these cases, when possible, default values in the current parameter file will be substituted for missing observed data. The default LiCor LI-6400 dataset includes this basic data. The mapping between LiCor data name and program data labels is: LiCor Program Description and units ----- ------- --------------------- Ci Ci_ppm Leaf interior [CO2], umol CO2 mol air-1 Photo assimn_umol Net photosynthesis rate, umol CO2 m-2 s-1 PARi Apar_umol In-chamber PAR, umol m-2 s-1 Tleaf Tc Leaf temperature,C To run the model with the Ball-Berry stomatal conductance code, additional data is required. This is the additional data available from gas-exchange datasets: Program Description and units ------- --------------------- gsw_mol Stomatal Conductance, mol m-2 s-1 Ca_ppm Ambient [CO2] pwa_Pa Ambient water vapor pressure, Pa Cs_ppm Leaf surface [CO2], ppm Hs_pct Relative humidity at leaf surface, % The default LiCor dataset does not include pwa_Pa, Cs_ppm or Hs_pct. These data are calculated by the program from the available LiCor data. To run the Ball-Berry stomatal conductance code using the default LiCor dataset, the following additional data is needed: LiCor Program Description and units ----- ------- --------------------- Cond gsw_mol Stomatal conductance to H2O, mol H2O m-2 s-1 (Eqn 1-9, Fig 15-11)) CO2S Ca_ppm Ambient (sample chamber) CO2, umol CO2 mol air-1 BLCond BLcond_mol TOTAL boundary layer conductance, mol m-2 s-1 (Eqn 14-31) StmRat StmRat Stomatal ratio - *fraction* of stomatal conductances of one side of the leaf to the other, unitless (Eqn 1-10, Eqn 14-31) Press ptot_kPa Atmospheric Pressure, kPa Trmmol E_mmol Transpiration rate, mmol H2O m-2 s-1 H2OS ea_mmol Ambient (sample chamber) H2O, mmol H2O mol-1 ADDITIONAL NOTES ---------------- * Invalid (or mis-spelled!) data labels are ignored with a warning. * The Ci_ppm label and associated data is required for all model fit types. * It is required that there either be an assim_umol or an assimn_umol label and associated data, but not both! Ball-Berry requires net assimilation rate. * Only one of the three illumination labels is permitted. * Only one of the two temperature labels is permitted. * If temperature or illumination data is undefined in the data file, then the default parameter value is used. * See above for Ball-Berry stomatal conductance code data requirements. -------------------------------------------------------------------------------- A1: Working With The Slider GUI -------------------------------------------------------------------------------- Each parameter used for fitting the model has a slider and an I/O button on the slider panel. The I/O button associated with each slider toggles whether the slider is active. If a slider is active, then the parameter value can be adjusted manually with the slider, and the autofit routine uses the parameter as fitting parameter. If the slider is inactive, then the parameter value cannot be adjusted manually and the autofit routine does not use that parameter as a fitting parameter. When a slider is inactive but used for the current chemistry, the parameter value displayed with the slider is used in the calculation. When a different fit type is selected from the pull-down menu, the active state of the panel sliders are set for that fit type, dependent upon the current chemistry and illumination units, and the slider panel is displayed. The slider panel can be displayed with the Edit > Show Fit Parameters menu button. If the current fit type is again selected from the pull-down menu, the active state of the sliders are reset to the default state for the selected fit type. -------------------------------------------------------------------------------- A2: Slider Ranges -------------------------------------------------------------------------------- The sliders ranges are set in the "srange" structure at the beginning of the main routine, gui_fit, which is located at the end of the file gui_fit.pro. If the range of a slider is inappropriate, edit the values in the "srange" structure, recompile the file with the command ".compile gui_fit", and restart the program. NOTE: The ranges set in the "srange" structure also used to constrain the range in which the parameters may be adjusted by the Autofit least-squares routine. -------------------------------------------------------------------------------- A3: Model Parameters -------------------------------------------------------------------------------- * These parameters fit by the model. Name Description, Units ------------ ---------------------------------------------------------------- chemistry Photosynthetic pathway, 'c3' or 'c4' *vmax_umol Max. leaf catalytic (Rubisco) capacity, umol m-2 s-1 *smax c3 only - POS factor, unitless zkc_p c3 only - Rubisco CO2 Km (carboxylation) zko_p c3 only - Rubisco O2 Km (oxygenation) *rrkk_p c4 only - rrkk parameter leaf_Tc Input leaf temperature, oC apar_umol PAR absorbed, umoles quanta m-2 s-1 Pseudo constants: Ca_ppm Canopy CO2 concentration, ppm = CO2 in Pa divided by atm pressure in Pa times 1.e6 = (35./101.3e3)*1.e6 ptot Atmospheric Pressure, Pa *PARalb PAR albedo emis Longwave emissivity (used in energy budget calculation) nitratefac O2 total production factor due to nitrogen reduction (unused in the calculations) *rstfac1 Water stress parameter Biome dependent physiological properties (SE-96,Table 5): effcon Maximum quantum yield = intrinsic quantum efficiency, mol mol-1 btheta Curvature parameter in second quadratic (Collatz91), unitless *hhti High temperature photosynthesis stress factor, K hlti Low temperature photosynthesis stress factor, K *respcp Leaf respiration factor, unitless Biome independent physiological properties (SE-96,Part 2,Table 5): atheta Curvature parameter in first quadratic (Collatz'91), unitless shti High temperature photosynthesis stress factor, K-1 slti Low temperature photosynthesis stress factor, K-1 trda High temperature respiration stress factor, K-1 trdm High temperature respiration stress factor, K Ball-Berry equation parameters (Collatz'91, see eqn 1): **gradm Stomatal slope parameter for B-B, unitless **bintc Intercept parameter B-B (minimum stomatal conductance), mol m-2 s-1 ** When running the Ball-Berry code, these parameters are calculated in the program but can also be set manually. $Id: help.hlp,v 1.4 2003/10/27 23:24:48 bhaxo Exp $