Go to the previous, next section, or Table of Contents.
An axis in an EPS file is referred to by the variable code of the variable it associated with and by the axis number (1 for x, 2 for y, and 3 for z; and 4 for 4th axis it is not a time axis). The axis code (like varible code defined in epic.key file) is also used for reading and writing a classic EPIC data file.
Axes of a variable in an EPS file must be defined with the variable they are associated with. As discussed in Section 2.3 Axes within EPS internal database the variable shape is described by the lower corner index lci[4] and the upper corner index uci[4]. Lci(i) and uci(i) are for x-axis when i = 1; for y-axis when i = 2; for z-axis when i = 3; and for t-axis when i = 4. If one or more axes are found missing when read in or when define a variable in a netCDF file, the missing axes will be inserted in the corresponding places automatically by EPS routines. Refer to EPS Implementation of Unidata NetCDF File Format for detailed information of axis definition in a netCDF file.
The time axis and spatial axes are processed differently. Separate EPS routines to set or get axis information and axis coordinates value for a time axis and for a spatial axis are provided.
Operations supported on axes are:
Spatial Axis
The function ep_set_axis (or epsetaxis for Fortran) creates a new spatial axis (x-, y-, z-, or the 4th axis if it is not a time axis; use ep_set_t_axis if it is a time axis) in the database and sets the axis information for a variable. If the variable does not exist in the database, the function will also create it. In this case, if a user-defined variable code (negative numbers) is used for the variable, the ep_set_var or (epsetvar for Fortran) must be called later to set the variable information; if a predefined variable code (defined in epic.key file) is used, then the function need not be called to set the variable information, since the information will be obtained directly from the epic.key file. When this axis is used by other variables, separate calls must be made to set axis information for each variable. See the Appendix C, Epic.key File for more information about the use of variable and axis codes in the epic.key file. Ep_set_axis must be called before ep_put_axis.
The valid input axis identifier, axis, is from 1 to 4. It represents the first to fourth axis of the variable. Normally, the first to third axes are x-, y- and z-axis. Axis equals 4 only when the 4th axis is not a time axis. Use ep_set_t_axis (or epsettaxis for Fortran) to set time axis information. Note: for longitude axes use variable code 502 for the East longitude convention (i.e. 170E is +170). Please refer to Section 2.3.1,Longitude Axes for detail about longitude representations.
The axid is the axis code (like the variable code). When writing a classic EPIC file, user must input axis code which has been defined in epic.key file (e.g. 500 for latitude), since the axis information (name, format, and units) are obtained by EPS routines from the epic.key file, based on the axis code for a classic EPIC file. When writing a netCDF file, however, this axis code will not be used by EPS routine to get the axis information. The axis information are expected to be specified by user regardless of what axis code is used. We recommend following the PMEL-EPIC convention when setting the axis name, format and units. For a netCDF file, refer to Spatial Axis Name, Units, and Epic_code Lookup Table in Appendix D,EPS Implementation of Unidata NetCDF File Format for details. The valid axis types, axtype, are EPEVEN, EPUNEVEN, EPEVEN_INT, EPUNEVEN_INT, EPEVEN_REAL and EPUNEVEN_REAL. Refer to Section 2.3 Axes for details about axis types.
Possible causes of error to this routine call include:
ep_set_axis: C Interface
void ep_set_axis(Dbase* epf, int varcde, int axis,
int axid, char* name, char* frmt,
char* units, char* axtype)
epf I EPIC system data structure
varcde I variable code
axis I axis identifier, 1-4 is valid range
axid I variable code for the axis data (e.g. lat=500)
name I axis name
frmt I format to use to print out axis values
units I units of the axis
axtype I type of axis
epsetaxis: Fortran Interface
subroutine epsetaxis(integer epf, integer varcde,
integer axis, integer axid,
character*(*) name,
character*(*) frmt,
character*(*) units,
character*(*) axtype)
epf I pointer file identifier
varcde I variable code
axis I axis identifier, 1-4 is valid range
axid I variable code for the axis data (e.g. lat=500)
name I axis name
frmt I format to use to print out axis values
units I units of the axis
axtype I type of axis
Time Axis
The function ep_set_t_axis (or epsettaxis for Fortran) creates a new time axis in the database and sets the time axis information for a variable. If the variable does not exist in the database, the function will also create it. In this case, if a user-defined variable code (negative number) is used for the variable ep_set_var (or epsetvar for Fortran) must be called later to set the variable information; if a predefined variable code (defined in epic.key file) is used, then the function need not be called to set the variable information, since the information will be obtained directly from the epic.key file. When this axis is used by other variables, separate calls must be made to set axis information for each variable. Ep_set_t_axis must be called before ep_put_t_axis.
The valid axis types, axtype} are EPEVEN, EPUNEVEN, EPEVEN_INT, EPUNEVEN _INT, EPEVEN_REAL and EPUNEVEN_REAL. Refer to Section 2.3, Axes for details about axis types.
When writing a netCDF file, the time axis unit, units, which is input to this function will be used to determine the output time format. The EPS library only supports the following three forms:
This time representation uses the variable attribute ``units'' to specify the time unit in the form of ``time-units since YYYY-MM-DD hh:mm:ss''. Here is an example of the output netCDF file time axis variable in this form:
......
variables:
long time(time) ;
time:units = "seconds since 1993-1-16 10:09:55" ;
......
In order to create the time axis in above format, for example, user must specify the units value, for function ep_set_t_axis (or epsettaxis for Fortran), to be ``seconds since 1993-1-16 10:09:55''.
Note: if the base time is not provided, e.g. units = ``seconds'', then the base time is assumed to be True Julian Day 0.
This time representation is supported to provide read compatability with PMEL's Ferret System. It uses the variable attribute ``units'' and ``time_origin'' to specify the time units. Here is an example of the output netCDF file time axis variable in this form:
......
variables:
float time(time) ;
time:units = "hour" ;
time:time_origin = "14-JAN-1990 14:00:00" ;
......
In order to create the time axis in above format, for example, user must
specify the units value, for function ep_set_t_axis
or epsettaxis for Fortran, to be ``hour time_origin 14-JAN-1990 14:00:00''.
The EPS time representation in a netCDF file uses one integer variable to represent the ``True Julian Day'', and another integer variable to represent the ``msec since 0:00 GMT''. The name of the second integer variable is the first integer variable name appended by ``2''. Here is an example of the output netCDF file time axis variable in this form:
......
variables:
long time(time) ;
time:units = "True Julian Day" ;
...
long time2(time)
time2:units = "msec since 0:00 GMT" ;
...
......
If units is none of above two specifications (netCDF supported and Ferret netCDF form), then the time axis will be written in EPS two-integer time representation. For example, setting units = ``'' will generate EPS two-integer time format.
Note: if you intend to write two-integer time format, the units should not be set to any netCDF standard time units. Since the EPS library version 2.0 or earlier output only two-integer time format and accepted any time units, one must be careful about time units input to this function call when linking old programs to EPS library version 2.1 or later.
Refer to Appendix D, EPS Implementation of Unidata NetCDF File Format for details about time units and formats.
Possible causes of error to this routine call include:
ep_set_t_axis: C Interface
void ep_set_t_axis(Dbase* epf, int varcde, char* name, char* frmt,
char* units, char* axtype)
epf I EPIC system data structure
varcde I variable code
name I axis name
frmt I format to use to print out axis values
units I units of the axis
axtype I type of axis
epsettaxis: Fortran Interface
subroutine epsettaxis(integer epf, integer varcde, character*(*) name,
character*(*) frmt, character*(*) units,
character*(*) axtype)
epf I pointer file identifier
varcde I variable code
name I axis name
frmt I format to use to print out axis values
units I units of the axis
axtype I type of axis
Spatial Axis
The function ep_put_axis (or epputaxis for Fortran) set the grid coordinates value for an existing axis. Lci and uci describes the length of the axis; once the axis length is set, it cannot be changed. The valid input axis identifier, axis, is from 1 to 4. It represents the first to fourth axis of the variable. Normally, the first to third axes are x-, y- and z-axis. Axis equals 4 only when the 4th axis is not a time axis. Use ep_put_t_axis to set time axis coordinates value. Ep_set_axis must be called before this routine can be called.
Note: for longitude axes use variable code 502 for the East longitude convention (i.e. 170E is +170). Please refer to Section 2.3.1, Longitude Axes for detail about longitude representations.
Possible causes of error to this routine call include:
ep_put_axis: C Interface
void ep_put_axis(Dbase* epf, int varcde, int axis, int* origin,
int* lci, int* uci, float* array)
epf I EPIC system data structure
varcde I variable code
axis I axis identifier, valid range is 1-4.
origin[4] I index of array origin
lci[4] I lower corner index
uci[4] I upper corner index
array[] I array containing coordinates
epputaxis: Fortran Interface
subroutine epputaxis(integer epf, integer varcde, integer axis,
integer origin(4), integer lci(4),
integer uci(4), real array(*))
epf I pointer file identifier
varcde I variable code
axis I axis identifier, valid range is 1-4.
origin I index of array origin
lci I lower corner index
uci I upper corner index
array I array containing coordinates
Time Axis
The function ep_put_t_axis (or epputtaxis for Fortran) sets the time coordinates for an existing time axis. Lci and uci describes the length of the axis; once the axis length is set, it cannot be changed. The input array contains the True Julian Day number as well as the number of milliseconds in the day. For element i, the True Julian Day number is in array[i*2-1] and the milliseconds since midnight is in array[i*2]. Use ep_set_axis to set spatial axis coordinates. Ep_set_t_axis must be called before this routine can be called.
Possible causes of error to this routine call include:
ep_put_t_axis: C Interface
void ep_put_t_axis(Dbase* epf, int varcde, int* origin, int* lci,
int* uci, long* array)
epf I EPIC system data structure
varcde I variable code
origin[4] I index of array origin
lci[4] I lower corner index
uci[4] I upper corner index
array[] I EPS two-integer time array
epputtaxis: Fortran Interface
subroutine epputtaxis(integer epf, integer varcde, integer origin(4),
integer lci(4), integer uci(4), integer array(2,*))
epf I pointer file identifier
varcde I variable code
origin I index of array origin
lci I lower corner index
uci I upper corner index
array I array containing time word
Spatial Axis
The function ep_inq_axis (or epinqaxis for Fortran) returns information about a spatial axis of a variable. The variable code varcde can be obtained using ep_var_name_to_id. The valid input axis identifier, axis, is from 1 to 4. It represents the first to fourth axis of the variable. Normally, the first to third axes are x-, y- and z-axis. Axis equals 4 only when the 4th axis is not a time axis. The axid (axis code) is only used for classis EPIC data file. For netCDF file, the axid is ignored. The output space interval , spcing, equals 0 if the axtype is UNEVEN. Use ep_inq_t_axis or epinqtaxis for Fortran to get time axis information.
Possible causes of error to this routine call include:
ep_inq_axis: C Interface
void ep_inq_axis(Dbase* epf, int varcde, int axis, int* axid,
char** name, char** frmt, char** units, char** axtype,
float* spcing)
epf I EPIC system data structure
varcde I variable code
axis I axis identifier, 1-4 is valid range
axid O variable code for the axis data
name O axis name
frmt O format to use to print out axis values
units O units of the axis
axtype O type of axis (e.g. EVEN, UNEVEN)
spcing O spacing of axis.
epinqaxis: Fortran Interface
subroutine epinqaxis(integer epf, integer varcde, integer axis,
integer axid, character*(*) name,
character*(*) frmt, character*(*) units,
character*(*) axtype, real spcing)
epf I pointer file identifier
varcde I variable code
axis I axis identifier, 1-4 is valid range
axid O variable code for the axis data
name O axis name
frmt O format to use to print out axis values
units O units of the axis
axtype O type of axis (e.g. EVEN, UNEVEN)
spcing O spacing of axis.
Time Axis
The function ep_inq_t_axis (or epinqtaxis for Fortran returns information about the time axis of a variable. The time interval, spcing, is in EPS two-integer time format and equals 0 if the axtype is UNEVEN. Possible causes of error to this routine call include:
ep_inq_t_axis: C Interface
void ep_inq_t_axis(Dbase* epf, int varcde, char** name, char** frmt,
char** units, char** axtype, long* spcing)
epf I EPIC system data structure
varcde I variable code
name O axis name
frmt O format to use to print out axis values
units O units of the axis
axtype O type of axis (e.g. EVEN, UNEVEN)
spcing[2] O spacing of time axis.
epinqtaxis: Fortran Interface
subroutine epinqtaxis(integer epf, integer varcde, character*(*) name,
character*(*) frmt, character*(*) units,
character*(*) axtype, integer spcing(2))
epf I pointer file identifier
varcde I variable code
name O axis name
frmt O format to use to print out axis values
units O units of the axis
axtype O type of axis (e.g. EVEN, UNEVEN)
spcing O spacing of time axis.
Spatial Axis
The function ep_get_axis (or epgetaxis for Fortran) returns the grid coordinates along an axis of a variable. The values of lci and uci are obtained from ep_get_var_shape. The dim is the dimensioned size of the array. The valid input axis identifier, axis, is from 1 to 4. It represents the first to fourth axis of the variable. Normally, the first to third axes are x-, y- and z-axis. Axis equals 4 only when the 4th axis is not a time axis. Use ep_get_t_axis to get time coordinate.
Possible causes of error to this routine call include:
ep_get_axis: C Interface
void ep_get_axis(Dbase* epf, int varcde, int axis, int* lci, int* uci,
float *array, int dim)
epf I EPIC system data structure
varcde I variable code
axis I axis identifier, 1-4 is valid range
lci[4] I lower corner index
uci[4] I upper corner index
array O array containing coordinates
dim I dimensioned size of array
epgetaxis: Fortran Interface
subroutine epgetaxis(integer epf, integer varcde integer axis,
integer lci(4), integer uci(4), real array(*),
integer dim)
epf I pointer file identifier
varcde I variable code
axis I axis identifier, 1-4 is valid range
lci I lower corner index
uci I upper corner index
array O array containing coordinates
dim I dimensioned size of array
Time Axis
The function ep_get_t_axis (or epgettaxis for Fortran) returns the time coordinates along the time axis. The output array contains the True Julian Day number as well as the number of milliseconds in the day. For element i, the True Julian Day number is in array[i*2-1] and the milliseconds since midnight is in array[i*2]. The values of lci and uci are obtained from ep_get_var_shape. The dim is the dimensioned size of first index of array. Possible causes of error to this routine call include:
ep_get_t_axis: C Interface
void ep_get_t_axis(Dbase* epf, int varcde, int* lci, int* uci,
long* array, int dim)
epf I EPIC system data structure
varcde I variable code
lci[4] I lower corner index
uci[4] I upper corner index
array[] O array containing EPS time
dim I dimensioned size of first index of array
epgettaxis: Fortran Interface
subroutine epgettaxis(integer epf, integer varcde, integer lci(4),
integer uci(4), integer array(2,*), integer dim)
epf I pointer file identifier
varcde I variable code
lci I lower corner index
uci I upper corner index
array O array containing time word
dim I dimensioned size of second index of array
The function ep_copy_grid (or epcopygrid for Fortran) copies the grid information (including coordinates value) of one variable (input variable) to that of another variable (output variable) in the same or different EPS file. If the output variable does not exist, this function will create it.
Possible causes of error to this routine call include:
ep_copy_grid: C Interface
void ep_copy_grid(Dbase* epin, int varin, Dbase* epout, int varout)
epin I input EPIC system data structure
varin I input variable code
epout I output EPIC system data structure
varout I output variable code
epcopygrid: Fortran Interface
subroutine epcopygrid(integer epin, integer varin, integer epout,
integer varout)
epin I input pointer file identifier
varin I input variable code
epout I output pointer file identifier
varout I output variable code
Logical function ep_check_grid (or epcheckgrid for Fortran) tests if the grids for the two variables are identical. It only checks the numerical values of the grids, but not the axis names. The match is comparison criteria for each coordinate, in the order of (x, y, z, t), 0 means don't compare and 1 means check for identical axis. For example, match = {1, 1, 0, 0} means it only checks the identical axis for x- and y-coordinates.
Possible causes of error to this routine call include:
ep_check_grid: C Interface
int ep_check_grid(Dbase* epf, int varcde1, int varcde2, int* match)
epf I EPIC system data structure
varcde1 I first variable code
varcde2 I second variable code
match[4] I comparison criteria for each coordinate, 0= don't
compare, 1= check for identical axis
epcheckgrid: Fortran Interface
logical function epcheckgrid(integer epf, integer var1, integer var2,
integer match(4))
epf I pointer file identifier
var1 I first variable code
var2 I second variable code
match I comparison criteria for each coordinate, 0= don't
compare, 1= check for identical axis
The function ep_set_index (or epsetindx for Fortran) loads the 4 integers into the point array. That is, the output pt = {i, j, k, l}.
ep_set_index: C Interface
void ep_set_index(int i, int j, int k, int l, int* pt)
i I first index
j I second index
k I third index
l I fourth index
pt[4] O index point array
epsetindx: Fortran Interface
subroutine epsetindx(integer i, integer j, integer k, integer l,
integer pt(4))
i I first index
j I second index
k I third index
l I fourth index
pt O index point array
The function ep_set_user (or epsetusr for Fortran) loads the 3 real values into the coordinate array. That is, the output coord = {x, y, z}.
ep_set_user: C Interface
void ep_set_user(double x, double y, double z, float* coord)
x I first user value
y I second user value
z I third user value
coord[3] O user array
epsetus: Fortran Interface
subroutine epsetusr(real x, real y, real z, real coord(3))
x I first user value
y I second user value
z I third user value
coord O user array
The function ep_index_to_user (or epindxtousr for Fortran) transforms grid index coordinates to user coordinates for the variable indicated by the variable code. That is, the output coord = {x[pt(1)], y[pt(2)], z[pt(3)]} and time = {t[(pt4),1), t(pt4),2)]}, where (x, y, z, t) are the grid index coordinates for the variable indicated by the variable code.
ep_index_to_user: C Interface
void ep_index_to_user(Dbase* epf, int varcde, int* pt, float* coord,
long* time)
epf I EPIC system data structure
varcde I variable code
pt[4] I point in index units
coord[3] O spatial coordinate in user units
time[2] O EPIC time of point
epindxtousr: Fortran Interface
subroutine epindxtousr(integer epf, integer varcde, integer pt(4),
real coord(3), integer time(2))
epf I pointer file identifier
varcde I variable code
pt I point in index units
coord O spatial coordinate in user units
time O EPIC time of point
The function ep_user_to_index (or epusrtoindx for Fortran) transforms from user coordinate to grid index for the variable indicated by the variable code.
ep_user_to_index: C Interface
void ep_user_to_index(Dbase* epf, int varcde, float* coord, long* time,
int* pt)
epf I EPIC system data structure
varcde I variable code
coord[3] I spatial coordinate of point in user units
time[2] I EPIC time of point
pt[4] O point in index units
epusrtoindx: Fortran Interface
subroutine epusrtoindx(integer epf, integer varcde, real coord(3),
integer time(2), integer pt(4))
epf I pointer file identifier
varcde I variable code
coord I spatial coordinate of point in user units
time I EPIC time of point
pt O point in index units
The function ep_axis_direction (or epaxisdirection for Fortran) returns an integer number which indicates the direction of an axis. The returned value has been defined in the EPSLIB include file (``epsystem.h'' for C routines and ``epsystem.fh for Fortran routines). The value equals EPTAXIS for time axis, EPXAXIS for x-axis, EPYAXIS for y-axis, EPZAXIS for z-axis and EPNONEAXIS for the axis whose direction can not be determined from its name or units by EPS routines. This function can be used to test whether an axis name or units is accepted by EPS routines to be a valid axis.
ep_axis_direction: C Interface
int ep_axis_direction(char* name, char* units)
name I axis name
units I axis units
epaxisdirection: Fortran Interface
integer epaxisdirection(character*(*) name, character*(*) units)
name I axis name
units I axis units
The function ep_get_timebase (or epgettimebase for Fortran) returns time base (in a character string) and time unit for a variable. This function is only implemented for netCDF files. The variable ``units'' attribute must be one of following 2 EPS supported formats: (1) units = ``time-unit since YYYY-MM-DD hh:mm:ss''; or (2) units = ``time-unit time_origin MMM-DD-YYYY hh:mm:ss''. Otherwise, null string will be returned to tbase and value of ``units'' attribute will be returned to units.
ep_get_timebase: C Interface
subroutine ep_get_timebase(Dbase* epf, int varcde, char* tbase,
char* units)
epf I EPIC system data structure
varcde I variable code
tbase O time base string
units O time unit
axtype O time axis type
epgettimebase: Fortran Interface
subroutine epgettimebase(integer epf, integer varcde,
character*(*) tbase, character*(*) units)
epf I pointer file identifier
varcde I variable code
tbase O time base string
units O time unit
axtype O time axis type
The function ep_set_unlimited (or epsetunlimited for Fortran) sets the UNLIMITED axis name in the current netCDF file when Creating netCDF files.
ep_put_unlimited: C Interface
void ep_put_unlimited(Dbase* epf, char* name)
epf I EPIC system data structure
name I unlimited axis name
epputunlimited: Fortran Interface
subroutine epputunlimited(integer epf, character*(*) name)
epf I pointer file identifier
name I unlimited axis name
The function ep_get_unlimited (or epgetunlimited for Fortran) returns the name of the UNLIMITED axis in the current netCDF file.
ep_get_unlimited: C Interface
void ep_get_unlimited(Dbase* epf, char* name)
epf I EPIC system data structure
name O the unlimited axis name
epgetunlimited: Fortran Interface
subroutine epgetunlimited(integer epf, character*(*) name)
epf I pointer file identifier
name O the unlimited axis name
The function ep_append_axis (or epappendaxis for Fortran) appends coordinate values to the unlimited axis coordinates in an existing netCDF file. The input netCDF file must be opened for editing, i.e. set EPEDIT mode when call ep_open. The length is the length of the input array. The data type of the array must agree with the data type of the UNLIMITED axis in the existing netCDF file. For example, if the UNLIMITED axis is a time axis and it is in EPS two-integer time format in the current netCDF file, then the input array must be defined as ``integer array(2,length)''.
Possible causes of error to this routine call include:
ep_append_axis: C Interface
void ep_append_axis(Dbase* epf, int length, void* array)
epf I EPIC system data structure
length I length of the array
array[] I array that appends to unlimited axis
epappendaxis: Fortran Interface
subroutine epappendaxis(integer epf, integer length, dtype array(*))
epf I pointer file identifier
length I length of the array
array[] I array that appends to unlimited axis
The function ep_overwrite_axis (or epoverwriteaxis for Fortran) overwrites coordinate values of the unlimited axis coordinates in an existing netCDF file. The input netCDF file must be opened for editing, i.e. set EPEDIT mode when calling ep_open. The length is the length of the input array. The data type of the array must agree with the data type of the UNLIMITED axis in the existing netCDF file. For example, if the UNLIMITED axis is a time axis and it is in EPS two-integer time format in the current netCDF file, then the input array must be defined as ``integer array(2,length)''.
Possible causes of error to this routine call include:
ep_overwrite_axis: C Interface
void ep_overwrite_axis(Dbase* epf, int start, int length, void* array)
epf I EPIC system data structure
start I start point of the unlimited axis that will be overwritten
length I length of the array
array I array that overwrites the the unlimited axis
epoverwriteaxis: Fortran Interface
subroutine epoverwriteaxis(integer epf, integer start,
integer length, dtype array(*))
epf I pointer file identifier
start I start point of the unlimited axis that will be overwritten
length I length of the array
array I array that overwrites the the unlimited axis
Go to the previous, next section, or Table of Contents.