Package netcdftime :: Module netcdftime

Module netcdftime

source code

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


Version: 0.9.2

Classes
  datetime
Phony datetime object which mimics the python datetime object, but allows for dates that don't exist in the proleptic gregorian calendar.
  utime
Performs conversions of netCDF time coordinate data to/from datetime objects.
Functions
 
DateFromJulianDay(JD, calendar='standard')
returns a 'datetime-like' object given Julian Day.
source code
 
JulianDayFromDate(date, calendar='standard')
creates a Julian Day from a 'datetime-like' object.
source code
 
date2index(dates, nctime, calendar=None, select='exact')
Return indices of a netCDF time variable corresponding to the given dates.
source code
 
date2num(dates, units, calendar='standard')
Return numeric time values given datetime objects.
source code
 
num2date(times, units, calendar='standard')
Return datetime objects given numeric time values.
source code
Variables
  ISO8601_REGEX = re.compile(r'(?P<year>[0-9]{4})(-(?P<month>[0-...
  TIMEZONE_REGEX = re.compile(r'(?P<prefix>[\+-])(?P<hours>[0-9]...
  __package__ = 'netcdftime'
Function Details

DateFromJulianDay(JD, calendar='standard')

source code 

returns a 'datetime-like' object given Julian Day. Julian Day is a fractional day with a resolution of 1 second.

if calendar='standard' or 'gregorian' (default), Julian day follows Julian Calendar on and before 1582-10-5, Gregorian calendar after 1582-10-15.

if calendar='proleptic_gregorian', Julian Day follows gregorian calendar.

if calendar='julian', Julian Day follows julian calendar.

The datetime object is a 'real' datetime object 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, it's a 'phony' datetime object which is actually an instance of netcdftime.datetime.

Algorithm:

Meeus, Jean (1998) Astronomical Algorithms (2nd Edition). Willmann-Bell, Virginia. p. 63

JulianDayFromDate(date, calendar='standard')

source code 

creates a Julian Day from a 'datetime-like' object. Returns the fractional Julian Day (resolution 1 second).

if calendar='standard' or 'gregorian' (default), Julian day follows Julian Calendar on and before 1582-10-5, Gregorian calendar after 1582-10-15.

if calendar='proleptic_gregorian', Julian Day follows gregorian calendar.

if calendar='julian', Julian Day follows julian calendar.

Algorithm:

Meeus, Jean (1998) Astronomical Algorithms (2nd Edition). Willmann-Bell, Virginia. p. 63

date2index(dates, nctime, calendar=None, select='exact')

source code 

Return indices of a netCDF time variable corresponding to the given dates.

Parameters:
  • dates - A datetime object or a sequence of datetime objects. The datetime objects should not include a time-zone offset.
  • nctime - A netCDF time variable object. The nctime object must have a units attribute. The entries are assumed to be stored in increasing order.
  • calendar - Describes the calendar used in the time calculation. Valid calendars 'standard', 'gregorian', 'proleptic_gregorian' 'noleap', '365_day', '360_day', 'julian', 'all_leap', '366_day'. Default is 'standard', which is a mixed Julian/Gregorian calendar If calendar is None, its value is given by nctime.calendar or standard if no such attribute exists.
  • select - 'exact', 'before', 'after', 'nearest' The index selection method. exact will return the indices perfectly matching the dates given. before and after will return the indices corresponding to the dates just before or just after the given dates if an exact match cannot be found. nearest will return the indices that correpond to the closest dates.

date2num(dates, units, calendar='standard')

source code 

Return numeric time values given datetime objects. The units of the numeric time values are described by the units argument and the calendar keyword. The datetime objects must be in UTC with no time-zone offset. If there is a time-zone offset in units, it will be applied to the returned numeric values.

Like the matplotlib date2num function, except that it allows for different units and calendars. Behaves the same if units = 'days since 0001-01-01 00:00:00' and calendar = 'proleptic_gregorian'.

Parameters:
  • dates - A datetime object or a sequence of datetime objects. The datetime objects should not include a time-zone offset.
  • units - a string of the form 'time units since reference time' describing the time units. time units can be days, hours, minutes or seconds. reference time is the time origin. A valid choice would be units='hours since 1800-01-01 00:00:00 -6:00'.
  • calendar - describes the calendar used in the time calculations. All the values currently defined in the CF metadata convention are supported. Valid calendars 'standard', 'gregorian', 'proleptic_gregorian' 'noleap', '365_day', '360_day', 'julian', 'all_leap', '366_day'. Default is 'standard', which is a mixed Julian/Gregorian calendar.
Returns:
a numeric time value, or an array of numeric time values.

The maximum resolution of the numeric time values is 1 second.

num2date(times, units, calendar='standard')

source code 

Return datetime objects given numeric time values. The units of the numeric time values are described by the units argument and the calendar keyword. The returned datetime objects represent UTC with no time-zone offset, even if the specified units contain a time-zone offset.

Like the matplotlib num2date function, except that it allows for different units and calendars. Behaves the same if units = 'days since 001-01-01 00:00:00' and calendar = 'proleptic_gregorian'.

Parameters:
  • times - numeric time values. Maximum resolution is 1 second.
  • units - a string of the form 'time units since reference time' describing the time units. time units can be days, hours, minutes or seconds. reference time is the time origin. A valid choice would be units='hours since 1800-01-01 00:00:00 -6:00'.
  • calendar - describes the calendar used in the time calculations. All the values currently defined in the CF metadata convention are supported. Valid calendars 'standard', 'gregorian', 'proleptic_gregorian' 'noleap', '365_day', '360_day', 'julian', 'all_leap', '366_day'. Default is 'standard', which is a mixed Julian/Gregorian calendar.
Returns:
a datetime instance, or an array of datetime instances.

The datetime instances returned are 'real' python datetime objects if the date falls in the Gregorian calendar (i.e. calendar='proleptic_gregorian', or calendar = 'standard' or 'gregorian' and the date is after 1582-10-15). Otherwise, they are 'phony' datetime objects which support some but not all the methods of 'real' python datetime objects. This is because the python datetime module cannot the uses the 'proleptic_gregorian' calendar, even before the switch occured from the Julian calendar in 1582. The datetime instances do not contain a time-zone offset, even if the specified units contains one.


Variables Details

ISO8601_REGEX

Value:
re.compile(r'(?P<year>[0-9]{4})(-(?P<month>[0-9]{1,2})(-(?P<day>[0-9]{\
1,2})((?P<separator>.)(?P<hour>[0-9]{2}):(?P<minute>[0-9]{2})(:(?P<sec\
ond>[0-9]{2})(\.(?P<fraction>[0-9]+))?)?(?P<timezone>Z|(([-\+])([0-9]{\
2}):([0-9]{2})))?)?)?)?')

TIMEZONE_REGEX

Value:
re.compile(r'(?P<prefix>[\+-])(?P<hours>[0-9]{2}).(?P<minutes>[0-9]{2}\
)')