For a variety of data processing and plotting tasks there is a need to acknowledge that
a data point is missing or unassigned. In the ``old days'' such information was passed
by letting a value like -9999.99 take on the special meaning of ``this is not really a
value, it is missing''. The problem with this scheme is that -9999.99 (or any other
floating point value) may be a perfectly reasonable data value and in such a scenario
would be skipped. The solution adopted in GMT is to use the IEEE concept Not-a-Number
(NaN) for this purpose. Mathematically, a NaN is what you get if you do an undefined
mathematical operation like ; in ASCII data files they appear as the textstring NaN.
This value is internally stored with a particular bit pattern
defined by IEEE so that special action can be taken when it is encountered by programs.
In particular, a library function called isnan is used to test if a floating point
is a NaN. GMT uses these tests extensively to determine if a value is suitable for plotting
or processing (if a NaN is used in a calculation the result would become NaN as well). Data points
whose values equal NaN are not normally plotted (or plotted with the special NaN color given in
.gmtdefaults4). Several tools such as xyz2grd, gmtmath, and
grdmath can convert user data to NaN and vice versa, thus facilitating arbitrary
masking and clipping of data sets. Note that a few computers do not have native IEEE hardware
support. At this point, this applies to some of the older Cray super-computers. Users on such
machines may have to adopt the old `-9999.99'' scheme to achieve the desired results.
Data records that contain NaN values for the x or y columns (or the z column for cases when 3-D Cartesian data are expected) are usually skipped during reading. However, the presence of these bad records can be interpreted in two different ways, and this behavior is controlled by the NAN_RECORDS defaults parameter. The default setting (gap) considers such records to indicate a gap in an otherwise continuous series of points (e.g., a line), and programs can act upon this information, e.g., not to draw a line across the gap or to break the line into separate segments. The alternative setting (bad) makes no such interpretation and simply reports back how many bad records were skipped during reading.