# 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" 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 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.

## 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_calendarandut_inv_calendarcan 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.

## See Also

**cd_convert**,
**cd_string**,
**cd_calendar**,
**cd_inv_calendar**

## 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 =The above will output:ut_inv_calendar( 2000, 01, 01, 00, 00, 00, "hours since 1800-01-01 00:00", 0 )ut_convert( time_hours, "days since 1800-01-01 00:00" )

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:

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 )