|
INTRO
Introducing the GEON IDV
INSTALL Download & Run the GEON IDV
LEARN
Tutorial
YOUR DATA Data Formats for the IDV |
print version - black and white
Using the NetCDF Data Format for Seismic Tomography
See also Using the GEON IDV to Explore Seismic Tomography
Introduction
This page tells how to create NetCDF format data files for 2D (latitude-longitude) and 3D (latitude-longitude-depth) grids of geophysical data. Seismic tomography results are the example, but the same NetCDF format applies to all grids for use in the IDV.
Seismic tomography data grids (2D or 3D) used in the IDV are in a NetCDF format. NetCDF data formats are used by hundreds of scientific institutions. NetCDF files are an excellent format for 2D and 3D grids mapped on the Earth. NetCDF files should include detailed metadata, such as names for units of the data values. The IDV can use approved unit names in NetCDF files to do computations with grids of differing units and differing latitude-longitude mappings; the conversions of units and grid point locations are automatically done for you.
GMT users already have NetCDF on their system. GNT "grd" files can be made into NetCDF files for the IDV. Actually they are NetCDF files but they do not match the netCDF format conventions used by IDV; they were designed before there were NetCDF conventions. I believe that IDV netCDF files may be used for GMT grid files with no change.
NetCDF is a binary format which allows you to use the same data files on different operating systems, such as Windows, Mac, and Linux. NetCDF can be written directly (as binary files) when the data is created, using code libraries for C, Fortran, C++ and Java from Unidata's NetCDF web site. Unidata maintains the NetCDF code and detailed NetCDF documentation online.
You may already have data in some format other than NetCDF to put into the IDV. A good way to convert it to NetCDF is to use an intermediate step, NetCDF's CDL ascii format. A CDL file is plain ascii text with the same information as a NetCDF file, in human-readable format. First, make or recast your data into CDL form. Then you use the NetCDF utility program ncgen to convert CDL to NetCDF. UNAVCO provides some reformatting software that can do this for you, in some cases.
Put your data in NetCDF
This discussion will use CDL examples. Then you will see how to covert CDL into NetCDF in one easy quick step.
NetCDF and CDL files have "dimensions," "variables," "attributes," and a "data:" section. "Dimensions" are name-integer pairs such as latitude=120, giving the length or size of variable arrays. "Attributes" are metadata.
"Variables" are one-dimensional arrays of data, both the model results, and also coordinate values -
grid point locations and times(if needed).
For the IDV, every data value (or grid point) must have a latitude, longitude, and depth value, and if wanted a time value.
The "data:" section has the 1D arrays of values for the variables.
Here is an sample CDL file of a lat-long-depth grid of Vp, Vs, and density (and no time values). It happens to be a global grid but regional grids use the same format. (Some data values in this sample have been replaced with "..." to save space on this page.)
netcdf AK135_3D_global_grid {
dimensions:
depth = 136;
latitude = 7 ;
longitude = 13 ;
variables:
float depth(depth) ;
depth:units = "kilometer" ;
depth:positive = "up" ;
float latitude(latitude) ;
latitude:long_name = "Latitude, positive north" ;
latitude:units = "degrees_north" ;
latitude:standard_name = "latitude" ;
float longitude(longitude) ;
longitude:long_name = "Longitude, positive East" ;
longitude:units = "degrees_east" ;
longitude:standard_name = "longitude" ;
float Vp(depth, latitude, longitude) ;
Vp:long_name = "AK135 P wave velocity" ;
Vp:valid_range = 5.9f, 13.7f ;
Vp:units = "kilometer sec^-1" ;
float Vs(depth, latitude, longitude) ;
Vs:long_name = "AK135 S wave velocity" ;
Vs:valid_range = 0.f, 7.3f ;
Vs:units = "kilometer sec^-1" ;
float density(depth, latitude, longitude) ;
density:long_name = "AK135 density" ;
density:valid_range = 2.40f, 13.1f ;
density:units = "gram centimeter^-3" ;
data:
depth = -0.000, -20.000, -20.000, -35.000, -35.000, -77.500, -120.000, -165.000, -210.000, -210.000, ... -6320.290, -6371.000;
latitude = -90.0, -60.0, -30.0, 0.0, 30.0, 60.0, 90.0;
longitude = 0.0, 30.0, 60.0, 90.0, 120.0, 150.0, 180.0, 210.0, 240.0, 270.0, 300.0, 330.0, 360.0;
Vp = 5.8000, 5.8000, 5.8000, 5.8000, 5.8000, 5.8000, 5.8000, 5.8000, ... 11.2622;
Vs = 3.4600, 3.4600, 3.4600, 3.4600, 3.4600, 3.4600, 3.4600, 3.4600, ... 3.6678, 3.6678;
density = 2.4490, 2.4490, 2.4490, 2.4490, 2.4490, 2.4490, 2.4490, 2.4490, 2.4490, ... 13.0122;
}
If you use this exact format for your tomography grids and change only the data values
(and change the names of variable and units where or if needed) you will have a good data file in CDL format.
Note:
- the first line "netcdf AK135_3D_global_grid {" has a name you make up.
- all the material after that name is inside a { } pair.
- every data line ends with ";"
- each variable shows the names of its position corrdinate values, such as "(depth)."
- The "variables" "depth," "latitude," and "longitude" are 1D arrays of the position coordinates.
- Position coordinate arrays are
recognized in NetCDF by having the same name as their dimension size value name.
- the parameter values such as Vp have their data in a 1D array with values ordered
as indicated by (depth, latitude, longitude).
- In this example the Vp array will have 137 * 7 * 13 = 12376 values.
- In this example, the values in the 1D parameter arrays have longitude changing most rapidly.
- each variable has "attributes." In this example we see attributes of units,
depth:positive, long_name, standard_name, and valid_range.
- the IDV likes depth to increase upwards; generally depth=0 is at mean sea level.
- NetCDF unit abbreviated names come from
"UD units",
and see Supported Units.
- "long_name" is only for informational and display labeling purposes.
- "standard_name" is a NetCDF attribute to help
insure that position corordinates are recognized correctly.
- "valid_range" means data values outdside the range are not displayed.
CDL documents
For the netCDF documentation about CDL, see Section 2.1.2 Network Common Data Form Language (CDL), CDL Syntax, and CDL data types (for float, int, etc.). Other parts of the complete NetCDF documentation may be useful to you. CDL files end with extension ".cdl". NetCDF files (binary) end with extension ".nc".
NetCDF: the CF Convention
There are several different "conventions" for NetCDF files. Conventions are best practices for a netCDF file to represent certain kinds of data. Conventions are created by users' working groups, with Unidata advice in some cases. The IDV works best with gridded data in the CF convention, designed for 2D, 3D and 4D grids with Earth locations.
Converting CDL files to NetCDF files: The ncgen and ncdump Utilities
Ncgen makes a NetCDF (.nc) binary file from an ASCII CDL (.cdl) file; ncdump does the reverse.
You use ncgen to make a binary NetCDF file from your ASCII CDL file. You can get ncgen by downloading and installing NetCDf on your system from NetCDF downloads. After installation you will find ncgen and ncdump in for example a Linux directory like /home/user22/netcdf/netcdf-3.6.0/bin/ or on Windows in My Documents\netcdf\netcdf-3.6.0\bin\.
You make a NetCDF file from a CDL file with the command
ncgen -o outputNetCDFfile.nc inputCDLfile.cdl
Note that the cdl file has extension .cdl and the output NetCDF file has extension .nc.
You can even use ncgen to create a C or FORTRAN code fragment to write the cdl file.
Ncgen is described in the online NetCDF ncgen documentation and in the ncgen "Man" page.
Ncdump
What if you have a NetCDF binary file you want to examine?
Ncdump is a utility program to examine the contents of a NetCDF binary file by creating the CDL equivalent.
The ncdump tool generates the CDL version of a netCDF file on standard output,
optionally excluding some or all of the variable data in the output. (The output from ncdump is also intended to be acceptable as input to ncgen. Thus ncdump and ncgen can be used as inverses to transform data representation between binary and text representations.)
To get a new CDL file from a NetCDF file, do
ncdump datafile.nc > datafile.cdl
Often ncdump is used to reveal only the header in CDL, ithe part above the "data:" section, so you can see how
it works, or why it does not work. i
Add "-h" after "ncdump "
ncdump -h datafile.nc > datafile.cdl
to see only the the header.
See the NetCDF header in the IDV
You can see the header of a NetCDF file in the IDV. In the Dasboard open the "Field Selector" tab. Do a right click over the data source name in the "Data Sources" column (left side). Click on "Properties." Click on "Metadata" in the new window that pops up.
Mapping X-Y-Z Grids to Latitude-Longitude-Depth grids with NetCDF
Here is an example of a CDL file header, showing how to store a rectangular x-y-depth grid in NetCDF so that it can be used by programs that require latitude-longitude-depth grids. NetCDF readers automatically convert the x-y-z locations in the file to latitude-longitude-depth for the program. You have to know exactly how your grid maps on the Earth, in this case, as transverse mercator. The official NetCDF documentation for this feature is Standard Coordinate Transforms.
netcdf tomography_m2.nc {
dimensions:
y = 86; // (has coord.var)
x = 70; // (has coord.var)
Depth = 101; // (has coord.var)
variables:
float Vp(Depth=101, y=86, x=70);
:units = "km/s";
:long_name = "P wave velocity";
:missing_value = -9999.0; // double
:coordinates = "lat lon";
:grid_mapping = "TM";
int TM;
:_CoordinateTransformType = "Projection";
:grid_mapping_name = "transverse_mercator";
:scale_factor_at_central_meridian = 1.0; // double
:longitude_of_central_meridian = 138.97; // double
:latitude_of_projection_origin = 36.05; // double
:_CoordinateAxisTypes = "GeoX GeoY";
float y(y=86);
:units = "km";
:_CoordinateAxisType = "GeoY";
:long_name = "y coordinate of projection";
float x(x=70);
:_CoordinateAxisType = "GeoX";
:units = "km";
:long_name = "x coordinate of projection";
float Depth(Depth=101);
:units = "km";
:_CoordinateAxisType = "Height";
:_CoordinateZisPositive = "up";
float lat(y=86, x=70);
:units = "degrees_north";
:long_name = "latitude coordinate";
:standard_name = "Latitude";
:_CoordinateAxisType = "Lat";
float lon(y=86, x=70);
:units = "degrees_east";
:long_name = "longitude coordinate";
:standard_name = "Longitude";
:_CoordinateAxisType = "Lon";
Note that this has only one parameter, Vp; more may be used in one file. Also note the new attribute "missing_value = -9999.0." Grid values of -9999 will not be displayed or used fror calculations in the IDV.
For more about NetCDf and the GEON IDV, NetCDF Data for the GEON IDV
Reference Seismic Tomography Data in NetCDF Grids for the GEON IDV
NetCDF data files of REM seismic tomography models ready to use in the IDV:
Reference Earth Model (REM) Seismic Tomography data files.
