NCL Home > Documentation > Functions > Date routines

time_to_newtime

Change a "udunits" recognized time unit to a new (different) "udunits" recognized time unit.

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 time_to_newtime (
		time              : numeric,  ; float or double
		new_time_unit [1] : string    
	)

	return_val [dimsizes(time)] :  double or float

Arguments

time

A "udunits" recognized time variable. Must be type "float" or "double".

new_time_unit

A "udunits" recognized string indicating the unit of the new time variable.

Return value

An array of the same size as time: double if time is double; float if time is float.

Description

This function converts the time units using cd_calendar. Useful for making the time variables associated with different variables and files consistent.

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

Examples

Example 1

Create a new time variable.

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

  TIME = f->time                                ; hours since 1-1-1 00:00:0.0
  DATE = cd_calendar (TIME, 0)

  new_time_units = "hours since 1800-01-01 00:00"

  time = time_to_newtime(TIME, new_time_units) 

  printVarSummary(TIME)
  printVarSummary(time)

The edited output from the above:


Variable: TIME
Type: double
Total Size: 5968 bytes
            746 values
Number of Dimensions: 1
Dimensions and sizes:   [time | 746]
Coordinates: 
            time: [17067072..17611320]
Number Of Attributes: 6
  units :       hours since 1-1-1 00:00:0.0

-------------------------------------------------
 

Variable: time
Type: double
Total Size: 5968 bytes
            746 values
Number of Dimensions: 1
Dimensions and sizes:   [time | 746]
Coordinates: 
            time: [1297320..1841568]
Number Of Attributes: 2
  units :       hours since 1800-01-01 00:00
  calendar :    gregorian

Example 2

Overwrite the current time variable.