Table of Contents for GEON IDV web site Introducing the GEON IDV Working with Your Data in the GEON IDV Download & Run the GEON IDV Tutorial ... How to Use the GEON IDV ... More Tips Data Formats: How to Put Your Data in the IDV The NetCDF Format: the best format for the IDV     The GIAG Format: An ASCII column format for 2D & 3D grids, and a converter to make NetCDF files     The GIAP Format: An ASCII column format for point data (irregulat lat-lon-depth), and a converter to make NetCDF files Point Data in Text Format (CSV files) UNAVCO's Interactive Data converter (for 2D grids and single parameter files only)

GIAP ASCII Format Description

GIAP is an ASCII format for "point data," data mapped on the earth where every data location has an independent latitude and longitude, depth, and time, not on a regular grid. Several parameter variables can be provided at each point. Points may have several time values in repeated rows. For gridded data use the GIAG format.

Typical data types suitable for this format include:

station observations such as GPS vectors, strain, etc.

natural events such as earthquakes

soundings such as borehole data

In the best case you can take an existing ASCII files of data with one location per line, add a few header lines to it as described below, and it is ready to convert to NetCDF. The use of this format is to simplify using existing research data files in the GEON IDV by converting ASCII data files to the NetCDF format (binary) read by the IDV.

The GIAP format is for one or more parameter variables, at many independent lat-lon-depth positions, with optional time values. GIAP is for "GEON IDV ASCII Point data." It has the advantage of being close to ASCII column files, or one location with values per line, in use by the scientists we are working with now. GIAP format files also may be used (without conversion to NetCDF) as GMT "xyz" format files.

To use GIAP format files, download the UNAVCO GIAP-to-NetCDF binary converter, to convert GIAP files to NetCDF. Use it to make NetCDF files that work in the GEON IDV. See ASCII Data Converters.

NetCDF has many advantages. Read more about NetCDF for the GEON IDV.

File Contents and Header Information

The GIAP format is very simple: one line per point location and associated variable data value(s). The filename can be named anything you like. The file begins with several header lines of metadata information. Below the header lines, each line in the file has space-separated values of latitude, longitude, depth, time(optional), station ID(optional) and parameter data values, as shown below. Column alignment need not be provided; spaces delimit values in each line.

See this sample GIAP file of GPS vectors and error ellipse data. There are five parameters at each location.

Order of parameters in each line is not fixed. The header block labels the columns and provides metadata required by NetCDF.

All header lines begin with the "#" character. Each header line then has a space, a keyword, and then data or information, as described here for each header line. Use the exact keywords shown here, all lower case.

Example of a complete header:

# source Brown Caldera GPS vectors 1997-2002
# depth meters up
# missing_value -9999. 
# time seconds since 1970-01-01 00 UTC 
# var1 ve "eastward component of vector" mm yr-1
# var2 vn "northward component of vector" mm yr-1
# var3 a "uncertainty 1-sigma major axis length" mm yr-1
# var4 b "uncertainty 1-sigma minor axis length" mm yr-1
# var5 corr "error correlation" none
## lon lat depth time stationid var1 var2 var3 var4 var5

Details about the header lines

Source header line (required)
keyword source 
example:
# source Brown Caldera GPS vectors 1997-2002 
Whatever follows " source " to the end of line is used as the description. Quotations are not required.
                                                                                                     
Depth header line  (required)
keyword depth, units of depth, indicator word "down" or "up" for positive values.
(see below for accepted units' names; meter and kilometer are common ones)
for example
# depth kilometer down
Note that the surface of the earth is at 0 depth. "down" means positive-increasing-down depth values 
are below the surface.
If you do not use depth enter 0 for depth values in the columns. If you have station elevations in
meters, use # depth meter up
                             
Time header line (optional)
keyword time
example
# time  "years since 1900-1-1"
Unit name must be enclosed in quotes " " even if one word.
Ma  or Myr or Myear is the unit for million years. Use negative values for "years before
present," so the IDV shows time animations loops in the normal sense.
Use positive time values if you have a sequence starting at some arbitrary
time. There are UD Units for actual times too, precise to any degree of accuracy you want.

About time, the IDV plots data from one file with the same times in one display. If all times in your
file are the same, there is one display. If you have a file of 5000 earthquake locations 
each with its own time the IDV will attempt to make 5000 separate displays and probably will 
freeze up trying to get enough memory to make 5000 displays. 

Use the IDV's time binning features - see the How-to web page on this site.
The IDV can handle 100 time steps.

Missing value header line (optional)
The missing value is a special number used to indicate no data value is known at that point.
keyword missing_value
example:
# missing_value -9999
The data columns cannot have spaces for "no data." Spaces are column separators.
The IDV will not plot data which is the missing value, or use it in
computations. If you do not use a missing value number, omit this line entirely.
If you have gaps in grid or point values, and you plan to do calculations in the IDV with your data, 
use of a missing value is highly recommended.

Parameter variable metadata header lines (at least one needed)
One header line for each variable:
The keywords are  "var1", "var2", etc., followed by the  short name, long name, and units.
The short name is a character string, with no spaces. Fewer than about 10 characters are recommended.
The short name appears in the IDV Displays legends.
The long name is enclosed in quotes and may have spaces in it, such as "air temperature".  
The long name will appear as the parameter variable name in the IDV "Fields" panel;
Unit name is last, and may have spaces; enter "none" if no unit applies as for pure numbers
template:                           
# var1 your_short_name "your long name in quotes" units
example:
# var1 SvrDG "Shear wave velocity relative to 1D model DG" kilometer/second
      
Column label header line (required)
Last line in the header  labels columns order, such as
## lon lat depth time stationID var1 var2 var3
NOTE the column label line begins with TWO "#"; 
this is in case your first column is var1
so that the var1 description line and column label line are not ambiguous.
You can use any column order you like. The converter uses this column label header line.

Station ID uses  the column label "stationid," and  is optional.
Stationid like lat and lon does not have a separate descriptive header line. 
The stationid is a character string, letters and numbers,  with no spaces. 
The stationid can be used in the IDV to label points on plots.
Stationid-s are optional and not used, for example, for earthquakes.

You can skip reading any column by putting an "x" in the column label line for that column position. If you have an ASCII file with data you do NOT want in the NetCDF file, label the column with x.
See this sample GIAP file with xed-out data columns.

Data values

The data values in each line are separated by spaces, for example for lat lon depth time stationID var1 var2 var3:
-105.45 39.8823 33.0 85     wd2 45.552 66.67001 0.098
-104.98 40.22 33.01 85 akk20 45.77 65.89 0.087e-02
Columns need not be aligned; this format does not count characters.

Longitudes and latitudes are in geographic degrees. Use longitude positive east from 0, latitude positive north from 0 degrees. Negative values, such as -105.342 for longitude 105.342 West, are fine. Numerical values can be integer(123), decimal (123.45678), scientific notation (1.2345e+02) or mixed formats.

The file must end on the last data line. Do not have any extra lines or empty lines.

The IDV needs parameter data values for every position. If your file only has latitude, longitude, and depth values, the converter from a GIAP file to netCDF automatically adds a parameter "Altitude" with the same values as the depth. This then is a topography data file.

There is no limit to how many point data values you can store in a GIAP file or enter in the IDV. As a practical matter the IDV treats each point data value as a separate item in the display which can be computationally intensive. Some point data symbols are very easy and you can plot more than 10,000 of them; others are complex graphical objects and plotting more than a few hundred of them will noticibly slow down performance.

Examples of GIAP files converted to NetCDF

GPS Motion Vectors and Error ellipses -- GPS Vel 1.0

Here (http://geon.unavco.org/unavco/GIAP/gpsvel_1.0_itrf2000.giap) is a sample GIAP file of GPS vectors and error ellipses which has been tested with the GIAG to NetCDF converter and the GEON IDV. Here are the equivalent CDL file and the NetCDF binary file.

Note that ve, vn, a, b, and corr are recognized as a group of special point data parameter names for GPS vector data and their error ellipses by the GEON IDV. If you use any other parameter names for such data you can still get the GEON IDV to display it as GPS vectors and ellipses by editing the user alias table to point your parameter names to these parameter names, however it is easier to use the GEON IDV rcognized vocabulary in the data files.

Earthquake locations and magnitudes -- The Centennial Catalogs of Earthquakes for 1900-1999

Engdahl and Villaseño have compiled a catalog of earthquake locations and magnitudes for the world from 1900 through 1999. (see Global Seismicity: 1900-1999, in W.H.K. Lee, H. Kanamori, P.C. Jennings, and C. Kisslinger, editors, International Handbook of Earthquake and Engineering Seismology, Part A, Chapter 41, pp. 665-690, Academic Press, 2002.

UNAVCO has taken the online Centennial catalog, made a GIAP file from it, and converted it to NetCDF for GEON IDV use. Here is the top of the GIAP file, showing the header lines. Here is the NetCDF binary file of the Centennial Catalog with preferred corrected magnitudes, made with the GIAP converter.

Earthquake Focal Mechanisms

To make a GIAP file for focal mechanisms, use a format like that shown below. Strike, dip and rake are controlled by the set parameter names "strike" "dip" and "rake" (no upper case) recognized by the GEON IDV to make focal mechanism symbols. Unit names are not used (they are degrees).

# source global earthquakes > mag 6 1980-1999
# depth kilometer down
# time "seconds since 1970-01-01 00 UTC"
# missing_value -9999.
# var1 mag "magnitude" none
# var2 strike "strike" none
# var3 dip "dip" none
# var4 rake "rake" none
## lon lat depth time var1 var2 var3 var4
-110.9355 44.577 15.6 473385600 6.6 185 70 -90
-111.122 44.74 7.63 473385600 6.2 180 55 -70
...  one line for each focal mechanism

Note that mag, strike, dip, and rake are recognized as special point data parameter names for earthquakes by the GEON IDV (but not by the Unidata IDV): "strike" is degrees CW from North, "dip" is slant of nodal plane in degrees downwards from horizon level, and "rake" is angle of motion on nodal plane in degrees.

Units and unit names

The UNAVCO web page NetCDF Data Format has a list of "Variable names for the GEON IDV" that the GEON IDV recognizes for special plots, such as focal mechanisms. These variable names, such as ve and eps2, must be used in the ASCII files as the "short name" where appropriate, for the data to create the special geophysical plot symbols in GEON IDV displays.

For accepted variable units and names, use the UD Units conventions. UD Units is a very complete software implementation for recognizing SI and related units. The IDV uses UD Units. See the list of recognized unit names in http://my.unidata.ucar.edu/content/software/udunits/udunits.txt . The UD Units home page is http://my.unidata.ucar.edu/content/software/udunits; see also http://my.unidata.ucar.edu/content/software/netcdf/docs/netcdf.html#Units. For SI units, see also http://physics.nist.gov/cuu/Units/index.html, and http://physics.nist.gov/cuu/Units/units.html.

When the IDV is used to make computations involving two or more data sets which have different units, the unit conversions are automatically done for you, if all the data has units with a recognized name.

                                                                                                                          
Examples of unit names recognized by UD Units:
     1300 meter or 1300 m
     250 kilometer or 250 km
     12 sec, 12 s
     -165 Ma, -165 Myr, -165 Myear
     Celsius [not C which means Coulomb]; kelvin
     gram [not g which is accel of gravity],  kilogram, kg does mean kilogram
     degF
     17.7 meter second-1, 17 m/s; 17 m s-1
     17.7 km/s, 17.7 km s-1
     9.80665 meter2 second-2
     10 kilogram.meters/seconds2
     10 kg-m/sec2
     10 kg m/s2
     (PI radian)2
     100 rpm
     geopotential meters
     24598 seconds since 1992-12-31 12:34:0.1 -7:00

For pure numbers or unitless data omit the unit name or enter "none."

For percentages you may omit the unit name, or enter "none," 
or use unit name "percent" and in that case use data value 1.0 for 1 %, and
calculations using the values in IDV will multiply your percent values by 0.01
where appropriate.