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.
------------------------------------------------------------------------------
ThinkGeek and WIRED's GeekDad team up for the Ultimate
GeekDad Father's Day Giveaway. ONE MASSIVE PRIZE to the
lucky parental unit. See the prize list and enter to win:
http://p.sf.net/sfu/thinkgeek-promo
_______________________________________________
Matplotlib-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/matplotlib-checkins
