TAX_DATESTRING

TAX_DATESTRING(A,B,C)
Returns date string for time axis coordinate values.

Argument 3 is given as a string and must be enclosed in double quotes. Its values can be "year", "month", "day", "hour", "minute", "second". Only the first 3 letters of this string is matched, so for instance, you can specify month with "mon".

Note that the variables you specify for the first two arguments will be loaded into memory. So, rather than giving a simple variable name, it's best to specify just a variable based on its time axis, say t[gt=b]. See example 1 below.

Caution: Previous to Ferret v6.8 only: Although Ferret stores and computes with coordinate values in double-precision, argument 1 of this function is a single-precision expression. There is plenty of precision in double-precision data to handle 1-second time axes since year 0000 with accuracy, but if an axis has units of seconds and its time origin is too long before the coordinates you are looking at, the truncation to single precision in an expression such as t[gt=var] may result in duplicate values in the expression in argument 1. The function converts the single-precision time steps to their double precision coordinate counterparts, and if duplicate values are encountered, it will return an error message. (Previous to Ferret v6.73 the function did not get the coordinate values and returned inaccurate results.) See example 2 below for more details.

Example 1:

yes? define axis/t=1-jan-1980:1-jan-1990:4/unit=days tax

yes? let date_list = t[t=29000:29900:100]

yes? list tax_datestring(date_list,t[gt=tax], "day")
             VARIABLE : TAX_DATESTRING(DATE_LIST,T[GT=TAX], "day")
             SUBSET   : 10 points (T)
 29000   /  1:"09-JUN-1980"
 29100   /  2:"17-SEP-1980"
 29200   /  3:"26-DEC-1980"
 29300   /  4:"05-APR-1981"
 29400   /  5:"14-JUL-1981"
 29500   /  6:"22-OCT-1981"
 29600   /  7:"30-JAN-1982"
 29700   /  8:"10-MAY-1982"
 29800   /  9:"18-AUG-1982"
 29900   / 10:"26-NOV-1982"

In this example, one COULD specify just "sst" for the second argument, but in fact the whole variable for all time steps would then be loaded into memory as the variable is passed to the function. So, just give a variable representing the time axis.

yes? use "http://ferret.pmel.noaa.gov/thredds/dodsC/data/PMEL/COADS/coads_sst.cdf"
yes? let tsteps = t[gt=sst,L=1200:1220:12]
yes? list tax_datestring(tsteps, t[gt=sst], "year") VARIABLE : TAX_DATESTRING(TSTEPS, T[GT=SST], "year") DATA SET : COADS Surface Marine Observations (1854-1993) FILENAME : coads_sst.cdf FILEPATH : http://ferret.pmel.noaa.gov/thredds/dodsC/data/PMEL/COADS/ SUBSET : 9 points (TIME)
 DEC-1953 / 1:"1953" DEC-1954 / 2:"1954" DEC-1955 / 3:"1955" DEC-1956 / 4:"1956"
 DEC-1957 / 5:"1957" DEC-1958 / 6:"1958"
 DEC-1959 / 7:"1959" DEC-1960 / 8:"1960"
 DEC-1961 / 9:"1961"

Example 2:

The precision issue described here is only a problem prior to Ferret v6.8:

This time axis, defined with timesteps of days, but underlying units of seconds, can be converted to strings with the TAX_DATESTRING function. The function gets the coordinate values corresponding to t[gt=ssh].

yes? define axis/t=1-jan-2010:31-dec-2010:86400/unit=seconds taxis
yes? let var = sin(t[gt=taxis])yes?  list/l=1:7 TAX_DATESTRING(t[gt=var], var, "seconds")
             VARIABLE : TAX_DATESTRING(T[GT=VAR], VAR, "seconds")
             SUBSET   : 7 points (TIME)
 01-JAN-2010 00 / 1:"31-DEC-2010 00:00:00"
 02-JAN-2010 00 / 2:"31-DEC-2010 00:00:00"
 03-JAN-2010 00 / 3:"31-DEC-2010 00:00:00"
 04-JAN-2010 00 / 4:"31-DEC-2010 00:00:00"
 05-JAN-2010 00 / 5:"31-DEC-2010 00:00:00"
 06-JAN-2010 00 / 6:"31-DEC-2010 00:00:00"
 07-JAN-2010 00 / 7:"31-DEC-2010 00:00:00"

The coordinates on the following time axis, with timesteps of 5 seconds and the default time origin in 1901 cannot be converted accurately to single precision values. Ferret uses it correctly but the tax_datestring function can't be used. (Previous to Ferret v6.73 the function did not check for this case and returned inaccurate results.)

yes? define axis/t="1-jan-2010:00:00":"1-jan-2010:00:10":5/unit=seconds taxis
yes? let var = sin(t[gt=taxis])
yes? list/l=1:7 TAX_DATESTRING(t[gt=var], var, "seconds")

Bailing out of external function "tax_datestring":
 Duplicate times in ARG 1, may arise from double- to single- precision conversion 0.3438547E+10 0.3438547E+10
 **ERROR: error in external function

The axis could be redefined with a time origin closer to the first timestep, and then we can use the function to convert to strings.

yes? define axis/t="1-jan-2010:00:00":"1-jan-2010:00:10":5/t0=1-jan-2010/unit=seconds taxis
...