From f5fb78ab6ca5ff455d5ed6d65eab53bd8da4f472 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Sun, 14 Jan 2018 03:03:24 +0100 Subject: [PATCH 1/2] some cleanup of matplotlib.dates docs --- lib/matplotlib/dates.py | 85 ++++++++++++++++++++++++++--------------- 1 file changed, 54 insertions(+), 31 deletions(-) diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py index 762743259c1b..518f713e4221 100644 --- a/lib/matplotlib/dates.py +++ b/lib/matplotlib/dates.py @@ -1,11 +1,19 @@ """ Matplotlib provides sophisticated date plotting capabilities, standing on the shoulders of python :mod:`datetime`, the add-on modules :mod:`pytz` and -:mod:`dateutil`. :class:`datetime` objects are converted to floating point -numbers which represent time in days since 0001-01-01 UTC, plus 1. For -example, 0001-01-01, 06:00 is 1.25, not 0.25. The helper functions -:func:`date2num`, :func:`num2date` and :func:`drange` are used to facilitate -easy conversion to and from :mod:`datetime` and numeric ranges. +:mod:`dateutil`. + + +.. date-format: + +Matplotlib date format +---------------------- +Matplotlib represents dates using floating point numbers specifying the number +of days since 0001-01-01 UTC, plus 1. For example, 0001-01-01, 06:00 is 1.25, +not 0.25. Values < 1, i.e. dates before 0001-01-01 UTC are not supported. + +The helper functions :func:`date2num`, :func:`num2date` and :func:`drange` are +used for easy conversion between :mod:`datetime` objects and Matplotlib dates. .. note:: @@ -20,24 +28,22 @@ 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 + In [1]: date(2006,4,1).toordinal() - date(1,1,1).toordinal() + Out[1]: 732401 +All the Matplotlib date converters, tickers and formatters are timezone aware. +If no explicit timezone is provided, the rcParam ``timezone`` is assumend. If +you want to use a custom time zone, pass a :class:`pytz.timezone` instance +with the tz keyword argument to :func:`num2date`, :func:`.plot_date`, and any +custom date tickers or locators you create. +See `pytz `_ for information on :mod:`pytz` and +timezone handling. 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 and formatters. These are described below. -All the matplotlib date converters, tickers and formatters are -timezone aware, and the default timezone is given by the timezone -parameter in your :file:`matplotlibrc` file. If you leave out a -:class:`tz` timezone instance, the default from your rc file will be -assumed. If you want to use a custom time zone, pass a -:class:`pytz.timezone` instance with the tz keyword argument to -:func:`num2date`, :func:`plot_date`, and any custom date tickers or -locators you create. See `pytz `_ for -information on :mod:`pytz` and timezone handling. The `dateutil module `_ provides additional code to handle date ticking, making it easy to place ticks @@ -350,11 +356,11 @@ def datestr2num(d, default=None): def date2num(d): """ - Converts datetime objects to Matplotlib dates. + Convert datetime objects to Matplotlib dates. Parameters ---------- - d : :class:`datetime` or sequence of :class:`datetime` + d : `datetime.datetime` or `numpy.datetime64` or sequences of these Returns ------- @@ -379,11 +385,11 @@ def date2num(d): def julian2num(j): """ - Convert a Julian date (or sequence) to a matplotlib date (or sequence). + Convert a Julian date (or sequence) to a Matplotlib date (or sequence). Parameters ---------- - k : float or sequence of floats + j : float or sequence of floats Julian date(s) Returns @@ -417,21 +423,23 @@ def num2julian(n): def num2date(x, tz=None): """ + Convert Matplotlib dates to `~datetime.datetime` objects. + Parameters ---------- x : float or sequence of floats Number of days (fraction part represents hours, minutes, seconds) since 0001-01-01 00:00:00 UTC, plus one. tz : string, optional - Timezone of *x* (defaults to rcparams TZ value). + Timezone of *x* (defaults to rcparams ``timezone``). Returns ------- - :class:`datetime` or sequence of :class:`datetime` - Dates are returned in timezone *tz* + `~datetime.datetime` or sequence of `~datetime.datetime` + Dates are returned in timezone *tz*. - If *x* is a sequence, a sequence of :class:`datetime` objects will - be returned. + If *x* is a sequence, a sequence of :class:`datetime` objects will + be returned. Notes ----- @@ -459,18 +467,19 @@ def _ordinalf_to_timedelta(x): def num2timedelta(x): """ - Converts number of days to a :class:`timdelta` object. + Convert number of days to a :class:`timdelta` object. + If *x* is a sequence, a sequence of :class:`timedelta` objects will be returned. Parameters ---------- x : float, sequence of floats - Number of days (fraction part represents hours, minutes, seconds) + Number of days. The fraction part represents hours, minutes, seconds. Returns ------- - :class:`timedelta` or list[:class:`timedelta`] + `.timedelta` or list[:class:`.timedelta`] """ if not cbook.iterable(x): @@ -484,9 +493,23 @@ def num2timedelta(x): def drange(dstart, dend, delta): """ - Return a date range as float Gregorian ordinals. *dstart* and - *dend* are :class:`datetime` instances. *delta* is a - :class:`datetime.timedelta` instance. + Return a sequence of equally spaced Matplotlib dates. + + The dates start at *dstart* and reach up to, but not including *dend*. + They are spaced by *delta*. + + Parameters + ---------- + dstart, dend : `~datetime.datetime` + The date limits. + delta : `datetime.timedelta` + Spacing of the dates. + + Returns + ------- + drange : `numpy.array` + A list floats representing Matplotlib dates. + """ f1 = _to_ordinalf(dstart) f2 = _to_ordinalf(dend) From 1db6604cc8fbac589697d5f409ac20395d04a430 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Sun, 14 Jan 2018 03:54:02 +0100 Subject: [PATCH 2/2] improve docstring of Axes.plot_date and parts of matplotlib.dates --- lib/matplotlib/axes/_axes.py | 74 ++++++++++++++++++------------------ lib/matplotlib/dates.py | 27 +++++++++---- 2 files changed, 58 insertions(+), 43 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 9cd4f5921cf0..e917fab7565c 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -1381,64 +1381,66 @@ def plot(self, *args, **kwargs): def plot_date(self, x, y, fmt='o', tz=None, xdate=True, ydate=False, **kwargs): """ - A plot with data that contains dates. - - Similar to the :func:`~matplotlib.pyplot.plot` command, except - the *x* or *y* (or both) data is considered to be dates, and the - axis is labeled accordingly. - - *x* and/or *y* can be a sequence of dates represented as float - days since 0001-01-01 UTC. - - Note if you are using custom date tickers and formatters, it - may be necessary to set the formatters/locators after the call - to :meth:`plot_date` since :meth:`plot_date` will set the - default tick locator to - :class:`matplotlib.dates.AutoDateLocator` (if the tick - locator is not already set to a - :class:`matplotlib.dates.DateLocator` instance) and the - default tick formatter to - :class:`matplotlib.dates.AutoDateFormatter` (if the tick - formatter is not already set to a - :class:`matplotlib.dates.DateFormatter` instance). + Plot data that contains dates. + Similar to `.plot`, this plots *y* vs. *x* as lines or markers. + However, the axis labels are formatted as dates depending on *xdate* + and *ydate*. Parameters ---------- - fmt : string - The plot format string. + x, y : array-like + The coordinates of the data points. If *xdate* or *ydate* is + *True*, the respective values *x* or *y* are interpreted as + :ref:`Matplotlib dates `. + + fmt : str, optional + The plot format string. For details, see the corresponding + parameter in `.plot`. tz : [ *None* | timezone string | :class:`tzinfo` instance] - The time zone to use in labeling dates. If *None*, defaults to rc - value. + The time zone to use in labeling dates. If *None*, defaults to + rcParam ``timezone``. - xdate : boolean - If *True*, the *x*-axis will be labeled with dates. + xdate : bool, optional, default: True + If *True*, the *x*-axis will be interpreted as Matplotlib dates. - ydate : boolean - If *True*, the *y*-axis will be labeled with dates. + ydate : bool, optional, default: False + If *True*, the *y*-axis will be interpreted as Matplotlib dates. Returns ------- lines + A list of `.Line2D` objects that were added to the axes. - See Also - -------- - matplotlib.dates : helper functions on dates - matplotlib.dates.date2num : how to convert dates to num - matplotlib.dates.num2date : how to convert num to dates - matplotlib.dates.drange : how floating point dates - Other Parameters ---------------- - **kwargs : + **kwargs Keyword arguments control the :class:`~matplotlib.lines.Line2D` properties: %(Line2D)s + + See Also + -------- + matplotlib.dates : Helper functions on dates. + matplotlib.dates.date2num : Convert dates to num. + matplotlib.dates.num2date : Convert num to dates. + matplotlib.dates.drange : Create an equally spaced sequence of dates. + + + Notes + ----- + If you are using custom date tickers and formatters, it may be + necessary to set the formatters/locators after the call to + `.plot_date`. `.plot_date` will set the default tick locator to + `.AutoDateLocator` (if the tick locator is not already set to a + `.DateLocator` instance) and the default tick formatter to + `.AutoDateFormatter` (if the tick formatter is not already set to a + `.DateFormatter` instance). """ if not self._hold: diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py index 518f713e4221..91196b342b9b 100644 --- a/lib/matplotlib/dates.py +++ b/lib/matplotlib/dates.py @@ -4,7 +4,7 @@ :mod:`dateutil`. -.. date-format: +.. _date-format: Matplotlib date format ---------------------- @@ -12,8 +12,21 @@ of days since 0001-01-01 UTC, plus 1. For example, 0001-01-01, 06:00 is 1.25, not 0.25. Values < 1, i.e. dates before 0001-01-01 UTC are not supported. -The helper functions :func:`date2num`, :func:`num2date` and :func:`drange` are -used for easy conversion between :mod:`datetime` objects and Matplotlib dates. +There are a number of helper functions to convert between :mod:`datetime` +objects and Matplotlib dates: + +.. currentmodule:: matplotlib.dates + +.. autosummary:: + :nosignatures: + + date2num + num2date + num2timedelta + epoch2num + num2epoch + mx2num + drange .. note:: @@ -28,7 +41,7 @@ 732403, whereas using the Gregorian calendar via the datetime module we find:: - In [1]: date(2006,4,1).toordinal() - date(1,1,1).toordinal() + In [1]: date(2006, 4, 1).toordinal() - date(1, 1, 1).toordinal() Out[1]: 732401 All the Matplotlib date converters, tickers and formatters are timezone aware. @@ -467,9 +480,9 @@ def _ordinalf_to_timedelta(x): def num2timedelta(x): """ - Convert number of days to a :class:`timdelta` object. + Convert number of days to a `~datetime.timedelta` object. - If *x* is a sequence, a sequence of :class:`timedelta` objects will + If *x* is a sequence, a sequence of `~datetime.timedelta` objects will be returned. Parameters @@ -479,7 +492,7 @@ def num2timedelta(x): Returns ------- - `.timedelta` or list[:class:`.timedelta`] + `datetime.timedelta` or list[`datetime.timedelta`] """ if not cbook.iterable(x):