SF.net SVN: matplotlib:[8396] trunk/matplotlib/lib/matplotlib/dates.py

[<ef...@us...>]

Revision: 8396
          http://matplotlib.svn.sourceforge.net/matplotlib/?rev=8396&view=rev
Author:   efiring
Date:     2010-06-07 23:39:24 +0000 (Mon, 07 Jun 2010)

Log Message:
-----------
dates: improve documentation related to use of Gregorian calendar

Modified Paths:
--------------
    trunk/matplotlib/lib/matplotlib/dates.py

Modified: trunk/matplotlib/lib/matplotlib/dates.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/dates.py	2010-06-07 20:15:11 UTC (rev 8395)
+++ trunk/matplotlib/lib/matplotlib/dates.py	2010-06-07 23:39:24 UTC (rev 8396)
@@ -9,6 +9,23 @@
 :func:`num2date` and :func:`drange` are used to facilitate easy
 conversion to and from :mod:`datetime` and numeric ranges.
 
+.. note::
+   Like Python's datetime, mpl uses the Gregorian calendar for
+   all conversions between dates and floating point numbers.
+   This practice is not universal, and calendar differences can
+   cause confusing differences between what Python and mpl
+   give as the number of days since 0001-01-01 and what other
+   software and databases yield.  For example, the
+   `US Naval Observatory <http://www.usno.navy.mil/USNO/astronomical-applications/data-services/jul-date>`_
+   uses a calendar that switches from Julian to Gregorian in
+   October, 1582.  Hence, using their calculator, the number of
+   days between 0001-01-01 and 2006-04-01 is 732403, whereas using
+   the Gregorian calendar via the datetime module we find::
+
+     In [31]:date(2006,4,1).toordinal() - date(1,1,1).toordinal()
+     Out[31]:732401
+
+
 A wide range of specific and general purpose date tick locators and
 formatters are provided in this module.  See
 :mod:`matplotlib.ticker` for general information on tick locators
@@ -233,8 +250,11 @@
     *d* is either a :class:`datetime` instance or a sequence of datetimes.
 
     Return value is a floating point number (or sequence of floats)
-    which gives one plus the number of days (fraction part represents hours,
-    minutes, seconds) since 0001-01-01 00:00:00 UTC.
+    which gives the number of days (fraction part represents hours,
+    minutes, seconds) since 0001-01-01 00:00:00 UTC, *plus* *one*.
+    The addition of one here is a historical artifact.  Also, note
+    that the Gregorian calendar is assumed; this is not universal
+    practice.  For details, see the module docstring.
     """
     if not cbook.iterable(d): return _to_ordinalf(d)
     else: return np.asarray([_to_ordinalf(val) for val in d])
@@ -252,9 +272,12 @@
 
 def num2date(x, tz=None):
     """
-    *x* is a float value which gives one plus the number of days
+    *x* is a float value which gives the number of days
     (fraction part represents hours, minutes, seconds) since
-    0001-01-01 00:00:00 UTC.
+    0001-01-01 00:00:00 UTC *plus* *one*.
+    The addition of one here is a historical artifact.  Also, note
+    that the Gregorian calendar is assumed; this is not universal
+    practice.  For details, see the module docstring.
 
     Return value is a :class:`datetime` instance in timezone *tz* (default to
     rcparams TZ value).


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.