--------------------------------------------------------------------------------
			    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 $
