Program M3DIFF


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.


The m3toolsM3DIFF 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
    Yes, I want the default analysis
                 # use the default run length:  entire duration of the files

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.

Previous: MCPLE


Up: Related Programs

To: Models-3/EDSS I/O API: The Help Pages