EPIC - Documentation - EPIC Key File

Documentation Links	About EPIC	EPIC netCDF Conventions	EPIC Gallery
EPIC Database	About EPIC Key File	Write EPIC Data Files	References

EPIC Key File

What is the EPIC key file?

Each variable in an EPIC data file is described by a numeric code. The numeric code is a unique identifier for the variable. The EPIC key file is a disk file (epic.key) containing the numeric code and associated information. The associated information includes a short label, a long label, the generic name, the units of the variable, the format for printing the data values (in Fortran format notation), and a comment field. The short name is suitable for use as a title for a column on a data listing. The long name is intended to be used in a label, such as an axis label on a graph. The generic name is a generic identifier (e.g., temperature) which can be used to generically identify data for plotting or other purposes. The comment field in the key file is optional, and includes information about the variable. Here is the current version of the epic key file (epic.key), from the EPIC FTP directory.

How does the EPIC system use the EPIC key file?

The file epic.key is used by EPIC system routines to identify or locate the variables in a data file. It is also used by PPLUS and by EPIC programs to label plots and listings automatically. Since data files in Classic EPIC format contain only numeric codes to identify the variables contained in the data file, the key file is needed to provide complete identification of the variables. For data files in netCDF format, complete identification of each variable can be included in the data file, and in this case, the key file is not required for variable identification when the data file is read.

What does the EPIC key file contain?

Each variable in an EPIC data file is described by a numeric code The EPIC key file is a disk file named "epic.key", which contains the variable code, a short label, a long label, the generic name, the units of the variable, the format for printing the data values (in Fortran format notation), and a comment field. The short, long and generic names are character strings. The short name is four characters or less, and is suitable for use as a title for a column on a data listing. The long name is intended to be used in a label, such as an axis label on a graph. The generic name is used to access data from within the nccalc netCDF calculater, which is linked with the PPLUS graphics package. The EPIC variable key code is an integer with 4 or fewer digits, and is a unique identifier for the variable. The comment field is optional, and includes information about the variable, such as "Temperature in degrees Centigrade on the 1968 temperature scale".

For example, Air Temperature in a data file has numeric variable code of 21, short name of "AT", long name of "Air Temperature, C", generic name of "atemp", units of "C", format of "f10.2", and a comment field of "1968 standard". Here is the current version of the epic key file (epic.key), from the EPIC FTP directory.

What is the relationship between the EPIC key file and EPIC data files?

If the data file is in Classic EPIC format, then the data file contains only numeric variable codes to identify each variable in the file, and all other information about the variable is found in the epic.key file by the EPIC programs and by the PPLUS graphics package. Therefore, for Classic EPIC data formatted files, the epic.key file is required for both read and write. For netCDF formatted data files, the information in the epic.key file is replicated in the data file attributes. At the time when the data file is written, this information can be included in the netCDF file by simply specifying the appropriate numeric variable key code. The EPIC system library will extract the other information from the epic.key file for inclusion in the data file as attributes. Alternatively, an application program writing the netCDF file can set some or all of these attributes in the data file directly, without specifying a numeric variable key code. It is possible to write a netCDF file which omits the numeric code and these attributes entirely, but this omission will result in a lack of information available to EPIC programs and also to PPLUS.

How is the EPIC key file used by EPIC plotting programs?

The following example illustrates the use of the epic.key file by EPIC programs. Plotting programs prompt the user to enter the variable to be plotted. If the user chooses Temperature and Oxygen, then the program will search through the variable codes for each of the variables to locate one which it can identify as a temperature and another which it can identify as an oxygen, and can then make a plot of those variables. Alternatively, the user can select the variables to be plotted by specifying the numeric variable codes, for explicit, exact identification of the data in the file. If the numeric variable codes are absent from the data file, then the program will be unable to locate a temperature or oxygen variable for plotting.

The epic.key file is also used by PPLUS to obtain variable information for Classic EPIC formatted data files. For netCDF files, PPLUS obtains this information from the netCDF attributes. PPLUS can then label plots automatically. The following table summarizes the relationship between the variable information in the epic.key file, the netCDF data file attributes, and the use of this information by PPLUS. EPIC variable information in epic.key file, in netCDF data files, and associated use by PPLUS, is as follows:

Relationship of EPIC key file elements to netCDF attributes and PPLUS

epic.key key file element	netCDF Variable Attribute name	PPLUS Variable Attribute name	PPLUS Global Symbol name	PPLUS use for data plot labels
variable code	epic_code	varid	in EPS$VARLIST
short label	name	name		title
long label	long_name	lname	EPS$FLD_NAME	axis
generic name	generic_name	gname	in EPS$NAMELIST
units	units	units
format	FORTRAN_format	frmt
comment field	(unused)	(unused)	(unused)

How are additions made to the EPIC key file?

Remote users of EPIC are encouraged to maintain their local key files current and compatible with the PMEL EPIC key file. Additions will be coordinated by the EPIC team. This is the process:

A user (local or remote) suggests additons to the key file by contacting EPIC key file coordinator (see bottom of this page)
The coordinator passes these suggestions, along with any comments she has, to the epic group and any EPIC users she is aware of who will be interested in these key file additions.
The coordinator coordinates the responses and makes a proposed final addition or change to the key file, and when all the votes are in, the change becomes final.
The keyfile updates include updating to PMEL installations (VAX/VMS, AXP/VMS, Sun OS, Solaris, Ultrix), the EPIC anonymous FTP, and this Web page. This Web page will always link to the most recent version of the key file.
This Keyfile Web page will be the source for our keyfile conventions (below).

What are the EPIC key file conventions?

Use an existing EPIC key code if possible.
You can propose a new entry to the EPIC key file by sending email to the Key File Coordinator (below). You must include a short label, a long label, the generic name, the units of the variable, the format for printing the data values (in Fortran format notation), and a comment field. You can suggest a numeric code too, but the EPIC project may select a different code. The numeric codes in the official EPIC key file will range from 0-9000. You can use a numeric code from 9001-9999 locally for testing, without conflicting with the official key file.
Eliminate instrument dependence (as much as possible) from the keyfile e.g. ADCP velocity is simply 'velocity' and the INSTRUMENT ID attribute tells the user of the data file that the instrument is ADCP.
A convention is needed for statistical values (such as Standard deviation or standard error of some variable). We propose that these NOT be included as variables in the data file, but rather be computed on-the-fly as needed. If they are included in the data file, they should be written only into netCDF files, and the numeric variable code should be omitted. The other attributes associated with the key file should be included (these include short name, long name, generic name, units, data format and comments).
An alternate suggestion (rejected) was that these be linked to the keycode for the base value. For examle: If the base value is temperature with key code 28, then std dev of temperature should be keycode 28 + {some fixed amount - maybe 400} and std err of temperature shoudld be keycode 28 + {some other fixed amount - maybe 5000}.

(Note: current epic.key file does include standard deviation and standard error for some variables. E.g. pressure, dynamic height, salinity, temporature.)
We can't do all this perfectly, since many entries are tied to older files created in the past, with imperfectly selected keycodes, but we can try to be sure there is some logic to what we do now. Comments are welcome.

EPIC key file coordinator

mick.spillane@noaa.gov