Program M3PAIR


setenv  <infile A>   <path name>
setenv  <infile B>   <path name>
setenv  <outfile>    <path name>
m3pair [<infile A> <infile B> <reportfile>] 
    <and respond to the prompts>
where infile A and infile B are the logical names of the input files, and outfile is the logical name of the output file to which the ASCII pairing is printed.


Paired-value ASCII output for I/O API files (e.g., to feed into Kaleidagraph or xmgr).

The M3PAIR program constructs an ASCII file of value-pairs for a pair of variables from a user-specified pair of GRIDDED Models-3 files (say "infile A" and "infile B"). The files must use the same grid in order for the program to perform the comparison operations. The comparison takes values from a user-selected window into the common grid, defined in terms of column, row, and layer subscript ranges; the default window is the entire grid.

Note that file B can be the same as file A; this allows you to pair variables O3 and NO2 from the same file, for example, or to pair NO2 between two successive hours or days within that file.

By default, the program finds the common-denominator time step, and for each common time step, starting at the beginning of both files, constructs paired output for variable-A and variable-B for a user-selected window into the (common) grid. In the most frequently expected application, both files will have the same timestep, duration, starting date and time, and set of variables; M3PAIR will then compare two variables, one from each file, for all time steps. In a more extreme example, if file A is time-independent with variables V, etc., and file B is time dependent starting at (1988200,000000) with variable W, etc., then M3PAIR might compare V from file A with all time steps of W from file B.

Before you run the program, you need to assign logical names to the physical file names of all three files, according to Models-3 conventions, using the operation

        "setenv <lname> <pname>"
The program will prompt you for the needed 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 pairings which can be performed by one execution of M3PAIR 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 pairing on the first variable from each of /tmp/myfile.A and /tmp/myfile.B, using the here-document approach:

    setenv FOO  /tmp/myfile.A
    setenv BAR  /tmp/myfile.B
    setenv QUX  /tmp/myfile.C
    m3pair  FOO BAR QUX <<  !DONE


Source code for program m3pairis available under the GNU GPL License, Version 2, and can be downloaded here from CMAS or here from GitHub.

Previous: m3merge

Next: m3probe

Up: Related Programs

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