gm-data-viewer:

User's manual
Most recent update: Feb 2007 )
gm-data-viewer is a small data plotting program written for the MS Windows Operating System
by Roman Shekhtman of the UBC Geophysical Inversion Facility (UBC-GIF). Note that the program
is not intended to be a sophisticated data plotter - it is a utility to help visualize data sets while
working with UBC-GIF modelling and inversion tools.
Installing the program:
Simply extract the executable program from it's archived into any directory on your MS Windows
computer, and follow the instructions for use.

Input file format

Input data must be in one of three formats. Attempts to feed other types of data files to gm-dataviewer will result in unpredictable behaviour.
The first format is a simple XYZ columns separated by spaces or tabs. No example is given here,
but the following notes apply:
Any text following an "!" mark is ignored.
The first line (not including comments) must contain only one integer giving the number of
data points in the data set.
Data are listed in the rest of the file with one datum per row. The columns are:
X-location | Y-location | datum value
Columns must be separated by spaces or tabs
Values can be integer, float, or scientific types, and in any units.
There must be the correct number of data, as identified on the first line (not including
comments).
Use the Options menu to adjust the title and axis/scale labels.
The second format is the one used for gravity data sets by UBC-GIF codes. It can also be used for
any XYZV data set. !comment
2601
0 0 1
0 2 1
0 4 1
0 6 1

43.2
41.7
38.6
37.6

4.3
4.2
3.9
3.8

Any text following an "!" mark is ignored.

The first line (not including comments) contains only one integer giving the number of data
points in the data set.
Data are listed in the rest of the file with one datum per row. The columns are:
X-location | Y-location | elevation | datum value | error on datum
Notes on columns:
columns must be separated by spaces or tabs
elevations can be plotted in gm-data-viewer (versions following 20060609 - see help
menu). Even if you don't have elevations, the column should contain place holders.
values can be integer, float, or scientific types, and in any units.
errors are not required, but if present they can be plotted (see below).

 There must be the correct number of data, as identified on the first line (not including
comments).
By default, plots of data provided in this format will be labelled as "Observed Gravity Data".
This can be changed using the Options menu.
The third format is very similar to the second, and it is used by UBC-GIF magnetics data:

!comment
!comment2
-10.00 30.00 50000.00 !! incl, decl, geomag
-10.00 30.00 !! aincl, adecl: anomaly
2601 !! # of data
0 0 1 43.2 4.3
0 2 1 41.7 4.2
0 4 1 38.6 3.9
0 6 1 37.6 3.8

Any text following an "!" mark is ignored.

The five numbers in the top two lines are reserved for use in UBC-GIF programs. They are not
used by gm-data-viewer except to complete the plot titles, but there must be place holder numbers
there for gm-data-viewer to work.
The third line (not including comments) is an integer giving the number of data points in the data set.
Data are listed in the rest of the file with one datum per row. the columns are:
X-location | Y-location | elevation | datum value | error on datum
Notes on columns - same as "second format" above.
There must be the correct number of data, as identified on the third line (not including
comments).
Plots of data provided with this format will be labelled as "Observed Magnetic Data", with
inclination, declination, and field strength. This can be changed using the Options menu.

Features
A list of features is given here. See the menu description for more details. The image to the
right shows a small magnetic data set.
One or two data sets can be plotted (one is shown to the right). By default the first data set is plotted
one above the second, but they can be plotted side-by-side using View => arrangement.
When data are in second or third formats, elevation can be plotted as the second data set using
View => elevation, or the right-most toolbar button.
The image can be saved to the Window's clipboard, and then pasted into any other application
that can accept a "*.bmp" image (such as a wordprocessor). *.bmp images tend to be large so
you are advised to convert to *.gif or *.jpg images or any other formats using a bitmap image
editing tool.
Instead of contour plotting, the data can be plotted as dots coloured according to the colour
scale. See via mouseover on the figure above.
Contouring: Data do not have to be on a grid, but only a fairly simple triangulation algorithm
is used for interpolation onto a grid. This step is automatic. Two types of pixel interpolation
are provided, giving either a blocky "pixelated" look, or a smoother appearance.
The image can be enlarged or shrunk (magnify + and - buttons).
Locations of actual data points can be overlayed on the plot as dots (as shown on this image).

 By default, the colour scale is labelled mGals if a "gravity" style data set was used, and with
nT if a "magnetics" style data set was used. For other types of data, use Options => Labels to
change plot and scale titles.

 Font size of labels can be changed. (View => font | ...) or <Alt>-<1 | 2>
The colour map can be either of several built in options via View => Colourmap ... .
Try for yourself. There is no option for user-specified colour scales. Available colour
maps are shown to the right.
Colour scales left to right:
=>
The minimum and maximum values for the colour scale
default
can be adjusted separately for the two displayed data sets.
- grayscale
A sub set (or region) of the data can be specified for
- colour 2
plotting (via Options => Region).
- colour 3
- colour 4
Once a region has been selected using Options => Region
- colour 5
the data set can be cropped (Edit => Crop) and the
- colour 6
reduced data set can be saved.
- topo 1
Data can be decimated (downsampled) using integer values via
- topo2
(Edit => Downsample data ... ). The resulting data reduced set can
be saved.
A line profile at any location through the first data set can be generated - shown above, and
see below for more details. Click outside the data region to remove the line profile.
A map of the errors specified with the first input data set can be plotted.
The difference between two data sets can be plotted, either directly, or normalized by error
values in the first data set. This is usually used to generate a misfit map which compares
observed with predicted data during an inversion.
Errors, random noise, and a constant offset can be assigned within the program and the
modified data set can be saved.
When the mouse is pointing to a data point, <SHIFT>-<Right mouse button> causes a dialog
box to open displaying data information. The user can then change error or delete the data
point.
True values of the nearest datum to the mouse pointer are shown in the program's status bar
(at the bottom of the window) when the right mouse button is clicked (as shown in the figure
above). The datum being seen is highlighted, even when data points are not shown.

Menus
Use of gm-data-viewer menus should be self explanatory. Here are a few tips:
The tool bar duplicates some menu options. Each tool button has a tool tip if the mouse
pointer is held over it for a few seconds.
The File menu contains open and save options. In the open dialogue, two files can be
specified.
This was originally included in order to view both measured and predicted data sets
while working on a geophysical inversion project.
The feature is also useful for comparing different data sets that were gathered on
identical survey areas.
NOTE the two data files must be the same type (either "gravity" or "magnetics" data
sets, and discussed above).
The "text editor" option opens the data file in Windows Notepad.

 The Edit menu contains the three modify data set options (below). The Downsample option is
here, as is the crop option (inactive unless Options => Region was used). It also includes an
image copy option which pastes a copy of the display into the Windows clipboard.
The View menu contains options for adjusting display parameters. The Elevation option is
only active if the input file is in the second or third formats.
The Options menu contains the scale min / max adjustment, region select and title changing
options.

Line profiles
As noted in "Features", and shown in the image above, this plotting tool lets you examine a line
profile anywhere on the data set. Click and Drag (using the left mouse button) from the start to the
end of any line in any direction, over the contoured data set. The program will label the line's
endpoints with A and B, and the graph will appear below the contour plot.
Click anywhere on the graph line of this profile and a horizontal line will appear at that amplitude,
with labels on the axis showing the width of the anomaly at that amplitude. Note that if there was a
second contour plot, it will be removed from the display when line profiles are created.

Modifying data sets

Errors can be assigned to all data by specifying a percent and minimum. These will be added to the
data set as it's fifth column if the File menu, save option is used.
Random Gaussien noise can be added to the data values by specifying a percent and minimum.
Each datum will have random noise added which will be included in the image, and will be saved if
the file is saved. Don't save to the original file name or you will loose the original, unchanged data
set!
A constant value can be added to all data values. Data will retain this addition if the file is saved.
Right Button>.
Single data points can be adjusted (error or value) by pointing to the datum and pressing <SHIFT Cropping a data set means throwing away all data outside the area specified using Options =>
Region . As before, if you save without changing the file name, the original data will be lost.
Downsampling by integer factors can also be done. For example, if "3" is specified (via Edit =>
Downsample data ... ) every third data point will be kept and all other values will be thrown away.

The command line

Finally, if gm-data-viewer is run from the command line with no parameters (or by double clicking
it's icon) it will open directly with a blank window. However, a data set can be loaded directly using
the following command line parameters:
gm-data-viewer datafile /pre
/pre - read a predicted data file (must be called
'maginv3d.pre' or 'gzinv3d.pre')

UBC Earth and Ocean Sciences, F. Jones.