Converts a time variable from one set of units to another (deprecated; use cd_convert).
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl" function ut_convert ( dateFrom : numeric, unitsTo : string ) return_val [dimsizes(dateFrom)] : double
standard gregorianThe following common calendaring systems are NOT recognized by the Udunits library.
no_leap 360 365_day command_year n kyr B.P.unitsTo
The new date unit to convert to, which must adhere to the same restrictions on the input units.
An array of type double and the same size as dateFrom.
Unidata no longers supports the internal code that ut_convert is based on. We therefore strongly recommend that you use the cd_convert function instead.
Known bug in NCL V6.4.0 and earlier: Many users have reported a "60 second" bug in several of NCL's date conversion routines, in which you get a value of "n minutes, 60 seconds" instead of "n+1 minutes, 0 seconds". See the 6.4.0 release notes for details. If you encounter this bug, please email the ncl-talk group with the details. Meanwhile, you can try the temporary ut_convert_fix, which was added in NCL V6.4.0 for test purposes and potentially as a replacement function. A decision will be made about this function in a future release of NCL.
To quote the Udunits man page:
The udunits(3) package uses a mixed Gregorian/Julian calendar system. Dates prior to 1582-10-15 are assumed to use the Julian calendar, which was introduced by Julius Caesar in 46 BCE and is based on a year that is exactly 365.25 days long. Dates on and after 1582-10-15 are assumed to use the Gregorian calendar, which was introduced on that date and is based on a year that is exactly 365.2425 days long. (A year is actually approximately 365.242198781 days long.) Seemingly strange behavior of the udunits(3) package can result if a user-given time interval includes the changeover date. For example, ut_calendar and ut_inv_calendar can be used to show that 1582-10-15 *preceded* 1582-10-14 by 9 days.
Caveats of Udunits:
- Year 0 is treated as year 1, because year 0 does not exist in the real world calendar.
- The length of a month is fixed at 1/12 of a tropical year or 2629743.831225 seconds. This means if you have a units of something like "months since 1870-1-1", then at time = 0 you will get:
year = 1870 month = 1 day = 1 hour = 0 second = 0However, at time = 1, you will get:
year = 1870 month = 1 day = 31 hour = 10 second = 3.83122This function was contributed by Carl J. Schreck, III, a graduate student at the University at Albany in the Department of Earth and Atmospheric Sciences.
The following require that contributed.ncl be loaded prior to invoking the function.
Convert a time variable from hours to days:
time_hours = ut_inv_calendar( 2000, 01, 01, 00, 00, 00, "hours since 1800-01-01 00:00", 0 ) print( time_hours ) time_days = ut_convert( time_hours, "days since 1800-01-01 00:00" ) print( time_days )The above will output:
Variable: time_hours Type: double Total Size: 8 bytes 1 values Number of Dimensions: 1 Dimensions and sizes:  Coordinates: Number Of Attributes: 1 units : hours since 1800-01-01 00:00 (0) 1753152 Variable: time_days Type: double Total Size: 8 bytes 1 values Number of Dimensions: 1 Dimensions and sizes:  Coordinates: Number Of Attributes: 1 units : days since 1800-01-01 00:00 (0) 73048Example 2
Overlay on a Hovmueller two datasets that use different units for their time coordinates:
data2&time = ut_convert( data2&time, data1&time@units ) contour1 = gsn_csm_hov( wks, data1, res1 ) contour2 = gsn_csm_hov( wks, data2, res2 ) overlay( contour1, contour2 )