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).