setenv <infile A> <path name>
setenv <infile B> <path name>
setenv <reportfile> <path name>
m3diff [<infile A> <infile B> [<reportfile>]] [<DEFAULT>
<and respond to the prompts>
where infile A and infile B are the
logical names of the input files,
and reportfile is the logical name of the report file
(to which the statistical comparisoon report is printed).
If reportfile is not present, the report will go either to the
log file (if it is set) or
to the screen. If neither is present, the program will prompt the
user for both input file and report file logical names. If DEFAULT
is the last command-line argument, then m3diff does the
default statistical analysis.
M3DIFF program performs
the standard binary GRIDOPS
grid-comparison operations on pairs of
variables from a user-specified pair of
GRIDDED
BOUNDARY , or
CUSTOM
I/O API files(say "infile A" and
"infile B"), computes statistics for each
specified variable and for the specified "difference"
operation-- there being
about twenty notions of difference supported, and optionally
generate an output file containing all the results of the specified
operations. The analysis may be either the default comparison or a
user-customized one; statistical analyses of the results are written
to a report file; optionally, the gridded results themselves are
written to an output file (under user-customized output variable names,
etc.). The files must use the same grid
in order for the program to perform the comparison operations.
Note that file B can be the same as file
A; this allows you to compute the ratio of variables
O3 and NO2 within the same concentration-file,
for example, or the difference of NO2 between two
successive hours or days within a single file.
Note also that M3DIFF requires that the file types
and their grid dimensions must match.
By default, the program finds the set of variables
which occur in both files, the common-denominator time step, and for
each common time step, starting at the beginning of both files, for
each common variable reports statistics for file-A, file-B,
and for the result of the operation A - B . In the
most frequently expected application, both files will have the same
timestep, duration, starting date and time, and set of variables;
M3DIFF will then compare all variables from both files
for all time steps. In a more extreme example, if file A is
time-independent with variables V and W, file B is time dependent
starting at (1988200,000000) with variables R, S, T, U, and V, then
by default M3DIFF would compare V from file A with
V for (1988200,000000) from file B.
In a customized comparison report, the user selects the duration, starting date, and starting time for the period to be analyzed, and a set of (up to 120 of) the following:
Before you run the program, you need to assign logical names to the physical file names of both files, according to Models-3 conventions, using the operation
"setenv <lname> <pname>"
The program will prompt you for the logical names you
have chosen for the input files, and then extensively for the options
to choose; the prompts will have default responses which can be accepted
by hitting <RETURN>. The specification of starting date and time,
and duration for the analysis follow Models-3
date and time conventions.
Note that the set of analyses which can be performed by one execution of M3DIFF is quite complex and context-dependent (being determined by the files being compared). If you want to run this program in batch mode (from a script), the recommended way to develop the script is to run the program once interactively noting the pattern of responses to prompts which generate the particular analysis you want. The pattern of responses then becomes either a command-input file which is redirected into the program in the script, or becomes a "here-document" fed into the execution. The following is an excerpt of a script which does the default analysis on /tmp/myfile.A and /tmp/myfile.B, using the here-document approach:
...
setenv FOO /tmp/myfile.A
setenv BAR /tmp/myfile.B
m3diff << !DONE
FOO
BAR
Yes, I want the default analysis
# use the default run length: entire duration of the files
!DONE
...
Source code for program m3diff is available
under the GNU GPL License, Version 2,
and can be downloaded here from CMAS or
here from GitHub.
To: Models-3/EDSS I/O API: The Help Pages