Package netcdftime :: Module netcdftime :: Class utime
[hide private]
[frames] | no frames]

Class utime

source code

Performs conversions of netCDF time coordinate data to/from datetime objects.

To initialize: t = utime(unit_string,format='%Y-%m-%d %H:%M:%S',calendar='standard')

where

unit_string is a string of the form 'time-units since <format>' defining the time units.

format is a string describing a reference time. This string is converted to a year,month,day,hour,minute,second tuple by strptime. The default format is '%Y-%m-%d %H:%M:%S'. See the time.strptime docstring for other valid formats.

Valid time-units are days, hours, minutes and seconds (the singular forms are also accepted). An example unit_string would be 'hours since 0001-01-01 00:00:00'.

The calendar keyword describes the calendar used in the time calculations. All the values currently defined in the CF metadata convention are accepted. The default is 'standard', which corresponds to the mixed Gregorian/Julian calendar used by the udunits library. Valid calendars are:

'gregorian' or 'standard' (default):

Mixed Gregorian/Julian calendar as defined by udunits.

'proleptic_gregorian':

A Gregorian calendar extended to dates before 1582-10-15. That is, a year is a leap year if either (i) it is divisible by 4 but not by 100 or (ii) it is divisible by 400.

'noleap' or '365_day':

Gregorian calendar without leap years, i.e., all years are 365 days long. all_leap or 366_day Gregorian calendar with every year being a leap year, i.e., all years are 366 days long.

'360_day':

All years are 360 days divided into 30 day months.

'julian':

Proleptic Julian calendar, extended to dates after 1582-10-5. A year is a leap year if it is divisible by 4.

The num2date and date2num class methods can used to convert datetime instances to/from the specified time units using the specified calendar.

The datetime instances returned by num2date are 'real' python datetime objects if the date falls in the Gregorian calendar (i.e. calendar='proleptic_gregorian', 'standard' or 'gregorian' and the date is after 1582-10-15). Otherwise, they are 'phony' datetime objects which are actually instances of netcdftime.datetime. This is because the python datetime module cannot handle the weird dates in some calendars (such as '360_day' and 'all_leap') which don't exist in any real world calendar.

Example usage:
>>> from netcdftime import utime
>>> from datetime import  datetime
>>> cdftime = utime('hours since 0001-01-01 00:00:00')
>>> date = datetime.now()
>>> print date
2006-03-17 16:04:02.561678
>>>
>>> t = cdftime.date2num(date)
>>> print t
17577328.0672
>>>
>>> date = cdftime.num2date(t)
>>> print date
2006-03-17 16:04:02
>>>

The resolution of the transformation operation is 1 second.

Warning: Dates between 1582-10-5 and 1582-10-15 do not exist in the 'standard' or 'gregorian' calendars. An exception will be raised if you pass a 'datetime-like' object in that range to the date2num class method.

Words of Wisdom from the British MetOffice concerning reference dates http://www.metoffice.com/research/hadleycentre/models/GDT/ch26.html:

"udunits implements the mixed Gregorian/Julian calendar system, as followed in England, in which dates prior to 1582-10-15 are assumed to use the Julian calendar. Other software cannot be relied upon to handle the change of calendar in the same way, so for robustness it is recommended that the reference date be later than 1582. If earlier dates must be used, it should be noted that udunits treats 0 AD as identical to 1 AD."

Instance Methods [hide private]
  __init__(self, unit_string, format='%Y-%m-%d %H:%M:%S', calendar='standard')
  date2num(self, date)
Returns time_value in units described by unit_string, using the specified calendar, given a 'datetime-like' object.
  num2date(self, time_value)
Return a 'datetime-like' object given a time_value in units described by unit_string, using calendar.

Instance Variables [hide private]
  calendar
the calendar used (as specified by the calendar keyword).
  origin
datetime instance defining the origin of the netCDF time variable.
  unit_string
a string defining the the netCDF time variable.
  units
the units part of unit_string (i.e.

Method Details [hide private]

__init__(self, unit_string, format='%Y-%m-%d %H:%M:%S', calendar='standard')
(Constructor)

source code 
Parameters:
  • unit_string - a string of the form 'time-units since <format>' defining the time units.
  • format - a string describing a reference time. This string is converted to a year,month,day,hour,minute,second tuple by strptime. The default format is '%Y-%m-%d %H:%M:%S'. See the time.strptime docstring for other valid formats. Valid time-units are days, hours, minutes and seconds (the singular forms are also accepted). An example unit_string would be 'hours since 0001-01-01 00:00:00'.
  • calendar - describes the calendar used in the time calculations. All the values currently defined in the CF metadata convention are accepted. The default is 'standard', which corresponds to the mixed Gregorian/Julian calendar used by the udunits library. Valid calendars are:
    • 'gregorian' or 'standard' (default): Mixed Gregorian/Julian calendar as defined by udunits.
    • 'proleptic_gregorian': A Gregorian calendar extended to dates before 1582-10-15. That is, a year is a leap year if either (i) it is divisible by 4 but not by 100 or (ii) it is divisible by 400.
    • 'noleap' or '365_day': Gregorian calendar without leap years, i.e., all years are 365 days long. all_leap or 366_day Gregorian calendar with every year being a leap year, i.e., all years are 366 days long. -'360_day': All years are 360 days divided into 30 day months. -'julian': Proleptic Julian calendar, extended to dates after 1582-10-5. A year is a leap year if it is divisible by 4.
Returns:
A class instance which may be used for converting times from netCDF units to datetime objects.

date2num(self, date)

source code 

Returns time_value in units described by unit_string, using the specified calendar, given a 'datetime-like' object.

Resolution is 1 second.

If calendar = 'standard' or 'gregorian' (indicating that the mixed Julian/Gregorian calendar is to be used), an exception will be raised if the 'datetime-like' object describes a date between 1582-10-5 and 1582-10-15.

Works for scalars, sequences and numpy arrays. Returns a scalar if input is a scalar, else returns a numpy array.

num2date(self, time_value)

source code 

Return a 'datetime-like' object given a time_value in units described by unit_string, using calendar.

Resolution is 1 second.

Works for scalars, sequences and numpy arrays. Returns a scalar if input is a scalar, else returns a numpy array.

The datetime instances returned by num2date are 'real' python datetime objects if the date falls in the Gregorian calendar (i.e. calendar='proleptic_gregorian', or calendar = 'standard'/'gregorian' and the date is after 1582-10-15). Otherwise, they are 'phony' datetime objects which are actually instances of netcdftime.datetime. This is because the python datetime module cannot handle the weird dates in some calendars (such as '360_day' and 'all_leap') which don't exist in any real world calendar.

Instance Variable Details [hide private]

calendar

the calendar used (as specified by the calendar keyword).

origin

datetime instance defining the origin of the netCDF time variable.

unit_string

a string defining the the netCDF time variable.

units

the units part of unit_string (i.e. 'days', 'hours', 'seconds').