Research Note No. 18Feburary 13, 1987
Research Note No. 18
Feburary 13, 1987
YDAVG is designed to serve as a postprocesser of CACTOS yield summary
files. CACTOS, the CAlifornia Conifer Timber Output Simulator(Wensel,
Daugherty, and Meerschaert 1986), is designed to model changes in young-growth
conifer stands, based on stand descriptions developed from plot data. YDAVG
processes the yield summary files produced by CACTOS to compute the average
and standard deviations of the predicted yields for a stratum or management
unit as a whole. YDAVG can produce an "averaged yield file" for a stratum
or management unit based on up to one hundred and fifty plots for up to forty
simulation periods. However, a lengthy growth projection is not recommended
since the growth models in CACTOS were not developed for this purpose. The
provision in YDAVG for forty simulation periods is intended to allow for
prescriptions that include multiple harvest and ingrowth simulations (e.g. a
fifty year projection with a ten year cutting cycle and ingrowth added after
each harvest would have 31 simulation entries in the yield file).
YDAVG is intended to be used in conjunction with the batch mode of
CACTOS, where a series of plots (i.e. stand descriptions) are simulated under
the same set of commands. However, nothing in the program prohibits the use
of YDAVG with files produced in the interactive mode of CACTOS, but care should
be taken to insure that yield files used are compatible for averaging (see
"compatibility specifications").
The yield averager program can also be used to quickly and easily
produce a summary of the average current stocking condition of a stratum or
management unit along with a measure of the existing variation when used in
conjunction with CACTOS batch mode. This use of YDAVG will be dicussed in more
detail in the examples below.
HOW TO USE THE YIELD AVERAGER
YDAVG is a minimally interactive program that requires only three
keyboard entries from the user: 1) the name of the input file containing input
file names (may be the same filenames file used in CACTOS batch mode), 2) a 5
character prescription code (optional), and 3) a file name for the output file
(i.e. the averaged yield file).
A. Input File Specifications
Details of the input file specifications include 1) a description of the
filenames input file, 2) the yield file compatibility specifications, and 3) the
restrictions on yield summary file makeup.
1) The filenames input file:
YDAVG requires a file that contains the the names of the yield summary
files to be included in the calculation of the averaged yield file. The program
expects that the file has one yield summary file name on each line with the file
name starting in column 1, (FORTRAN format a32). These specifications allow YDAVG
to use the same file that was used as the filenames file in CACTOS batch mode. In
batch mode the yield summary output file name is automatically created by CACTOS.
This yield summary may be a single stand description or a concatenation of several
different stand descriptions run through the same prescriotion. The concatenated
yield files produced by CACTOS batch mode have the yield streams for each stand
description separated by an asterisk which is sensed by YDAVG. The user should be
aware that all yield summaries contained in a concatenated yield file are
automatically included in the averaged yield file and there is no way to specify
otherwise.
While YDAVG can utilize the input/output filenames file used in batch mode,
any file with the yield summary file names in the format described above (i.e.
format a32) can be used as the filenames input file. An example of a CACTOS filenames
input file is shown below:
columns: 123...
\cactos\comp3\stand1.sd
\cactos\comp3\stand2.sd
\cactos\comp3\stand3.sd
\cactos\comp3\stand4.sd
\cactos\comp3\stand5.sd
\cactos\comp3\stand6.sd
Note: this example is the same as a CACTOS batch mode filenames file. YDAVG appends
the file name with the optional prescription code and substitutes the ending '.yd'
for any ending on the filename given above.
2) Yield summary compatibility specifications:
For efficiency reasons YDAVG reads the yield file labels from the first yield
file listed in the the filenames input file and assumes that the pattern of all
subsequent yield summaries are identical with the first yield file. No checks are
made or warnings given in terms of compatibility. If the yield summaries are not
compatible, YDAVG will produce erroneous results.
CACTOS yield files contain combinations of the five types of simulation entries
listed below:
1) an entry after every growth cycle
2) an entry for each harvest simulation
3) an entry for each ingrowth simulation
4) an entry for the stand after each harvest or ingrowth simulation
5) an entry for the total harvest during a simulation
YDAVG reads the yield labels from the first yield file and stores the pattern of simulation
in memory (e.g. the first yield summary indicates a pattern of 5 growth cycle entries, a
harvest entry, a stand after harvets entry, 5 more growth cycle entries, and an entry for
total harvest during simulation). The program then reads the remaining yield files, storing
the entries in the pattern found in the first yield file. If any of the yield summaries do
not follow this pattern the resulting averaged yield file will be incorrect. This type of
error will show up as an inconsistency in the averaged yield file. However as the number of
plots included in the averaged yield file increases the magnitude of the discrepancies will
decrease. Whenever an averaged yield file shows a discrepancy the user should check for
incompatibility in the yield files used as input.
The compatibility of yield files concerns only the pattern of yield entries as opposed
to the values of a given entry. The pattern of yield entries must be identical for all yield
files, but their content may vary between yield files. For example the number of species as
well as the species composition may vary between yield files.
When YDAVG is used in conjunction with a single batch run of CACTOS the compatibility of
yield files is insured because each file was produced by the same set of simulation commands
and a harvest entry is included in the yield file whenever a harvest is attempted even if a
particular stand description had too little volume to be harvested. The harvest entry in this
case would contain one line of zeros, and this line will maintain compatibility.
The cases where YDAVG is used to average yield files produced by the interactive mode of
CACTOS or by two or more separate batch runs present the greatest risk of incompatibility. In
these cases the user must take care to insure compatibility between yield files. While the lack
of internal checking for incompatibility places more responsibility on the user, it also keeps
the program smaller and faster in operation.
In addition, YDAVG assumes the same merchantability standards are used for all yield
summaries (i.e. the same min. DBH and merch top).
B. Output File Specifications
The yield averager produces one output file which is similar in format to the CACTOS
yield summary file. The file has a heading of "AVERAGED YIELD FILE". The names of any files
that could not be included in the averaged yield due to input/output (I/O) errors will be
listed at the top of the file. If all files requested in the filenames file were sucessfully
included in the average no I/O error messages will be written to the output file. The stand
identifier labels of all yield files included in the calculations are printed next followed
by the merchantability limits used. The next section lists the averaged site index and age,
along with their standard deviations by species. In the case of site index and age, the
values calculated include only those entries listed in the yield files. For example, if out
of ten yield files averaged only two contained site indicies and ages for white fir, the
average site index and age for white fir would be based on two plots. The number of plots
each average site index is based on is listed on the same line under the column heading "n".
The rest of the averaged yield file contains the average yields by species with the
standard deviations listed directly below the average values. The values listed as elasped time
"et" are not averages. The values listed under "dbar" are averages, but they are calculated
using the average basal area and the average trees per acre and thus do not have an entries for
standard deviation. An example of a YDAVG output file is included at the end of this manual.
Note: the elasped time (et) printed in the averaged yield file comes from the last yield file
included in the calculations. While elasped time may seem to provide a simple check for
incompatibility of yield files, this use of elasped time would prohibit the use of YDAVG with
yield files that were produced from stand descriptions that had a growth period adjustment value
included to align the yield steams of plots measured at different times.
C. Use of YDAVG
To use YDAVG, the user would enter the command "ydavg". The program will welcome the user
to the program and request that the user enter to continue. The program will then ask the
user to enter the name of the filenames file. After this file is sucessfully opened the program
will request a name for the averaged yield file. The program has file overwriting capabilities.
The program then asks for a five-character prescription code for correcting the file names file.
Once these user entries are completed the program begins processing the yield files, printing the
stand identifier of the file currently being processed to the screen. Once the yield files are
read the program calculates averages and standard deviations, and writes the results to the
output file.
EXAMPLE USES OF YDAVG
The most common use of YDAVG will be to produce average yield streams for strata or
management units based on multiple plots simulations using the same set of simulation commands in
CACTOS batch mode. This type of use has been discussed throughout the guide and is the most
straightforward use of YDAVG. The stand descriptions for a stratum or management unit would be run
through CACTOS batch mode. When the batch run is successfully completed, YDAVG could be executed
using the same filenames file as used in the batch run.
A second use for YDAVG is to produce an averaged yield file for summarizing the current
average stocking and variation of a stratum or management unit. Here CACTOS is used only to
summarize the stand description, and since no growth is projected, this can be done by running
all of the plots in a given unit through CACTOS batch mode using the following command file:
command explanation
cf enter configuration
iq set quintupling option
1. inhibit quintupling option
ex exit initialization routine
ba enter batch routine
ex end simulation
Batch commands
Rx prescription code
ex exit
The yield files produced by this command file would only contain the yield entry
for elasped time of zero (i.e. current condition). The yield files produced could then be run
through YDAVG to produce average stocking and variation (i.e. standard deviation) for the unit
as a whole. Note: in the above command file record quintupling was inhibited to speed processing
time (i.e. avoid pseudo-stochastic calculations) since these calculations do not affect initial
condition. A user may also want to set mechantability standards in this type of use.
LITERATURE CITED
Wensel, Lee C., Peter J. Daugherty, and Walter J. Meerschaert. 1986.
CACTOS User's Guide: The CAlifornia Conifer Timber Output Simulator. Version 3.3 Bull.
1920. Ag. Exp. Sta., Univ. of Ca. Div. of Ag. and Nat. Res.