NCL Home > Documentation > Functions > Date routines

ut_convert

Converts a time variable from one set of units to another (deprecated; use cd_convert).

Prototype

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl"  ; This library is automatically loaded
                                                             ; from NCL V6.2.0 onward.
                                                             ; No need for user to explicitly load.

	function ut_convert (
		dateFrom  : numeric,  
		unitsTo   : string    
	)

	return_val [dimsizes(dateFrom)] :  double

Arguments

dateFrom

The original date(s) to convert. It must contain a "units" attribute in one of two formats recognized by the Udunits library:

standard
gregorian

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

Return value

An array of type double and the same size as dateFrom.

Description

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.

This function converts dateFrom from its original Julian/Gregorian units to the new specified units, using the built-in functions ut_calendar and ut_inv_calendar.

If the input data does not contain a units attribute, then an error message will be printed and all missing values will be returned.

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 = 0

    year   = 1870
    month  = 1
    day    = 31
    hour   = 10
    second = 3.83122

This function was contributed by Carl J. Schreck, III, a graduate student at the University at Albany in the Department of Earth and Atmospheric Sciences.

Examples

The following require that contributed.ncl be loaded prior to invoking the function.

       load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl"

Example 1

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:   [1]
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:   [1]
Coordinates:
Number Of Attributes: 1
  units :       days since 1800-01-01 00:00
(0)     73048

Example 2

Overlay on a Hovmueller two datasets that use different units for their time coordinates: