|
INTRO
Introducing the GEON IDV
INSTALL Download & Run the GEON IDV
LEARN
Tutorial
YOUR DATA Data Formats for the IDV |
Using the NetCDF Data Format for Seismic Tomography
See also Using the GEON IDV to Explore Seismic Tomography
Introduction
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 untis 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.
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.
In many cases you already have or make data in some format other than NetCDF. 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 softeware 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 3D 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 a lat-long grid. You have to know how your grid maps on the Earth. in this case, transverse mercator.
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 in one netCDF 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
Sample regional seismic tomography NetCDF data files for the IDV:
-
Yellowstone National Park regional seismic tomography
Vp URL: http://geon.unavco.org/unavco/YNP/YellJordanVp.nc
Vp 500 URL: http://geon.unavco.org/unavco/YNP/YellVp500.nc
Vp deep URL: http://geon.unavco.org/unavco/YNP/YSCalderaVPdeep.nc
Vp shallow : http://geon.unavco.org/unavco/YNP/YSCalderaVPshallow.nc
Vp deep and shallow combined: http://geon.unavco.org/unavco/YNP/YSCalderaVPcomb.nc
Vs URL: http://geon.unavco.org/unavco/YNP/YellWaiteVs.nc
Data published in
Jordan, M., R.B. Smith and G.P. Waite, 2004. Tomographic images of the Yellowstone hotspot structure, in 2004. Eos, Transactions Amer. Geoph. Un., 2004 Fall Meeting, Suppl. Abst. V51B-0556.
Husen, S., R.B. Smith, and G.P. Waite, 2004, Evidence for gas and magmatic sources beneath the Yellowstone volcanic field from seismic tomographic imaging, Journal of Volcanology and Geothermal Research, Vol. 131 (3-4), p. 397-410
North American seismic tomography by Suzan van der Lee and A. Frederiksen
URL: http://geon.unavco.org/unavco/SVDL/vdlNA04_90kmtop.nc
Data published as
Van der Lee, S., and A. Frederiksen, 2005, Surface Wave Tomography applied to the North American upper mantle, in AGU Monograph "Seismic Data Analysis and Imaging With Global and Local Arrays", Eds: Nolet and Levander, 67-80.
NetCDF data files of REM seismic tomography models ready to use in the IDV:
Reference Earth Model (REM) Seismic Tomography data files.
