EarthScope

Data Services (DS)
Data Products Unit
EarthScope Earth Model Collaboration (EMC) - Release 2.1

COMMENTS/QUESTIONS:

Please contact [email protected]

2024-09-16

Release 2.1: Introduces the new emc_inspector.py v2024.260 script to help identify any potential issues with the netCDF metadata.

Release 2.0: The R2 release includes changes to the GeoCSV fields. R1 GeoCSV files are not compatible with the R2 tools. However, you can use the netCDF files generated by the R1 package to generate R2-style GeoCSV files using the EMC Tools Release 2.0 script from the R2 release.

1. DESCRIPTION:

EMC Tools contain the following Python scripts for converting the EMC netCDF Earth model files to and from GeoCSV format and for checking the netCDF metadata:

• netCDF_2_GeoCSV.py - Converts a 2D or 3D netCDF Earth model file in geographic or projected coordinate systems to GeoCSV format or displays its header information.
• GeoCSV_2_netCDF.py - Converts a 2D or 3D GeoCSV Earth model file to netCDF format or displays its header information.
• emc_inspector.py - Checks a netCDF file against the EMC requirements and flags any missing or incorrectly defined attributes. This check is not exhaustive, and visual validation is required.

Additional Information:

• For EMC (EarthScope Earth Model Collaboration) information, visit: http://ds.iris.edu/ds/products/emc/
• For netCDF information, visit: https://www.unidata.ucar.edu/software/netcdf/
• For GeoCSV format information, visit: http://geows.ds.iris.edu/documents/GeoCSV.pdf

2. USAGE:

Each conversion script can be used independently. For help, run the script with the -h option:

• netCDF_2_GeoCSV.py -h
• GeoCSV_2_netCDF.py -h
• emc_inspector.py (Run without arguments for a metadata validation prompt)

2.1 How to run netCDF_2_GeoCSV.py:

• Use the sample 3D netCDF file from the "samples" directory or download a 3D netCDF Earth model file from the EMC repository: http://ds.iris.edu/ds/products/emc-earthmodels/

• Run the script to convert the netCDF file. The converted file will have the same name as the netCDF file but with a .csv extension and will be saved in the same directory.

  netCDF_2_GeoCSV.py -i FILE -x longitude -y latitude -z depth -m mode -d -H
  

  • -i [required]: Input GeoCSV Earth model file
  • -x [required]: x-axis variable in netCDF
  • -y [required]: y-axis variable in netCDF
  • -z [required]: z-axis variable in netCDF (none for 2D models)
  • -m [default: single]: Output mode (single for one GeoCSV file or depth for one file per depth)
  • -d [default: False]: Debug mode
  • -H [default: False]: Display headers only

  Note: Only a .csv file converted with the -m single option can be converted back to netCDF.

2.2 How to run GeoCSV_2_netCDF.py:

• Use the sample GeoCSV file as a template to create your own GeoCSV file or convert a netCDF model file to GeoCSV using netCDF_2_GeoCSV.py.

• Run the script to convert the GeoCSV file back to netCDF. The converted file will have the same name as the GeoCSV file but with a .nc extension and will be saved in the same directory.

  GeoCSV_2_netCDF.py -i FILE -d -H
  

  • -i [required]: Input GeoCSV Earth model file
  • -d [default: False]: Debug mode
  • -H [default: False]: Display headers only

  Note: Only a single .csv file can be converted back to netCDF.

2.3 How to run emc_inspector.py:

• Run emc_inspector.py directly. It will prompt you for the input netCDF file. Enter the path to an EMC-compatible netCDF file.

  Please enter the netCDF file name:
  

• Check the output for metadata validation results.

2.4 How to create EMC GeoCSV Earth Model Files:

The following highlights the steps for creating an EMC Earth model file in GeoCSV format:

• Follow EMC's guidelines at: http://ds.iris.edu/ds/products/emc-contributionguide/
• Familiarize yourself with the GeoCSV format: http://geows.ds.iris.edu/documents/GeoCSV.pdf

Steps for converting 3D models:

• Download and inspect the "SAW642ANB_kmps.csv" file.
• Download the "header.csv" template and edit it with information about your model.
• Create the data section using the appropriate delimiter, ensuring data is sorted in the order: depth, latitude, longitude.
• Test and convert the GeoCSV file using GeoCSV_2_netCDF_3D.py.