PCDATA.TXT    Documentation for PCDATA    2002/05/10

     PCDATA reads each record of a DataFile, calculates the area
weighted average of selected grid cell values for each record, and
produces an output LinePlotFile containing one data row for each
record.


Invocation
----------
     When PCDATA is invoked without arguments, it writes to the console
a brief description of its required arguments and usage.  When invoked
with arguments, the first command line argument is the name of a
DataFile.  Subsequent pairs of arguments are longitude and latitude
indicies that correspond to Model (I,J) grid cells.  Each such argument
can be a single index or a range of indicies (minimum index, a minus
sign, and a maximum index with no blanks in between).


Calculation of area weighted mean
---------------------------------

     Each Model grid cell has a horizontal area.  The area weighted
value of a quantity is calculated as:
[sum over cells (area*value)] / [sum over cells (area)].  If the value
of a grid cell is less than or equal to -999999 (missing data), that
cell is ignored in the summations.


Determination of the X coordinate
---------------------------------
     The X coordinate for each record is derived from the year and
month data of the record's title.  The fractional part of the X
coordinate is determined from the month: 1/24 for "Jan", 3/24 for
"Feb", ..., 23/24 for "Dec", and 0 for anything else.  The integral
part of the X coordinate is determined from the year.  If the year is a
number, it is used directly and the X coordinate label will say
"Years".  If the last character of the year is an X, only the first
three digits of the year are used and the X coordinate label will say
"Decades".  The year is located in columns 65-68 of the record title,
and the month is located in columns 70-72.


LinePlotFile output
-------------------
     PCDATA spews the LinePlotFile output to the console or, by using
redirected output, to a file.  The LinePlotFile title line is identical
to the first title of the DataFile.  The X coordinate label should be
either "Years" or "Decades".  The Y coordinate label is the first 50
characters of the first title.  The fourth line of the LinePlotFile
should have the tokens "Years" or "Decades", "Mean", and the (I,J)
indicies of the first five grid cells indicated from the command line.

     Each record of the DataFile produces a single row in the
LinePlotFile.  Each row contains an X coordinate and several Y values.
If a single grid cell is is indicated from the command line, then the
single Y value of that cell appears.  If several grid cells are
indicated, then the first Y value is the area weighted value of all
cells followed by the values of the first five individual grid cells.


Sample usage of PCDATA
----------------------
     Produce a LinePlotFile of the annual soil moisture amount in Iowa
using the C090 experiment (assuming the present working directory is
C:\AOM which contains PCDATA and subdirectory A1):
"PCDATA A1\SOILM.087 18 34".

     Produce a LinePlotFile of monthly surface air temperature over the
northern hemisphere using C089 and store it into a file:
"PCDATA M10\TAS.089 1-72 24-46 > TASNH089.LP".

     Produce a LinePlotFile of decade annual averages of precipitation
over the St.Lawrence river basin using C092:
"PCDATA A10\PREC.092 20-21 34 19-22 35 22-23 36".
The St. Lawrence river basin, including the Great Lakes, as defined by
the Model can be deduced from the river direction data given in the
file RD72X46a.ASCII .