8000 add more documentation and rework matplotlib.dates doc structure · matplotlib/matplotlib@5b1274e · GitHub
[go: up one dir, main page]
Skip to content

Commit 5b1274e

Browse files
theOehrlytheOehrly
committed
add more documentation and rework matplotlib.dates doc structure
1 parent c373657 commit 5b1274e

File tree

2 files changed

+396
-216
lines changed

2 files changed

+396
-216
lines changed

‎doc/api/dates_api.rst

Lines changed: 309 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,314 @@
22
``matplotlib.dates``
33
********************
44

5-
.. inheritance-diagram:: matplotlib.dates
6-
:parts: 1
7-
:top-classes: matplotlib.ticker.Formatter, matplotlib.ticker.Locator
5+
Matplotlib provides sophisticated date plotting capabilities, standing on the
6+
shoulders of python :mod:`datetime` and the add-on module dateutil_.
7+
8+
.. currentmodule:: matplotlib.dates
9+
10+
.. contents:: Table of Contents
11+
:depth: 2
12+
:local:
13+
:backlinks: entry
14+
:class: multicol-toc
815

916
.. automodule:: matplotlib.dates
10-
:members:
11-
:undoc-members:
12-
:exclude-members: rrule
13-
:show-inheritance:
17+
:no-members:
18+
:no-undoc-members:
19+
20+
Overview
21+
========
22+
23+
By default, Matplotlib uses the units machinery described in
24+
`~matplotlib.units` to convert `datetime.datetime`, `datetime.timedelta`,
25+
`numpy.datetime64` or `numpy.timedelta64` objects when plotted on an
26+
x- or y-axis. The user does not need to do anything for dates to be formatted,
27+
but dates often have strict formatting needs, so this module provides many
28+
tick locators and formatters. A basic example using `numpy.datetime64` is
29+
30+
.. plot::
31+
:include-source:
32+
33+
import numpy as np
34+
times = np.arange(np.datetime64('2001-01-02'),
35+
np.datetime64('2002-02-03'), np.timedelta64(1, 'D'))
36+
y = np.random.randn(len(times))
37+
fig, ax = plt.subplots()
38+
ax.plot(times, y)
39+
fig.autofmt_xdate()
40+
41+
42+
If you want to customize the tick labels that are shown on the x-axis, you
43+
need to manually configure the tick locator and formatter for this axis.
44+
The tick locator determines how many ticks are shown and in which interval they
45+
are shown.
46+
The formatter defines how a date or timedelta value is represented as a string.
47+
This means that tick formatting is independent of the number, interval and
48+
location of ticks.
49+
50+
By default, Matplotlib uses automatic tick locators and formatters for
51+
date and timedelta values. This means that a reasonable number of ticks is
52+
shown and the tick label is formatted in such a way that includes only the
53+
relevant information to keep it as short as possible.
54+
55+
56+
.. seealso::
57+
58+
- :doc:`/gallery/text_labels_and_annotations/date`
59+
- :doc:`/gallery/ticks/date_concise_formatter`
60+
- :doc:`/gallery/ticks/date_demo_convert`
61+
62+
63+
.. _date-format:
64+
65+
Matplotlib date format
66+
======================
67+
68+
Matplotlib represents dates using floating point numbers specifying the number
69+
of days since a default epoch of 1970-01-01 UTC; for example,
70+
1970-01-01, 06:00 is the floating point number 0.25. The formatters and
71+
locators require the use of `datetime.datetime` objects, so only dates between
72+
year 0001 and 9999 can be represented. Microsecond precision
73+
is achievable for (approximately) 70 years on either side of the epoch, and
74+
20 microseconds for the rest of the allowable range of dates (year 0001 to
75+
9999). The epoch can be changed at import time via `set_epoch` or
76+
:rc:`dates.epoch` to other dates if necessary; see
77+
:doc:`/gallery/ticks/date_precision_and_epochs` for a discussion.
78+
79+
.. note::
80+
81+
Before Matplotlib 3.3, the epoch was 0000-12-31 which lost modern
82+
microsecond precision and also made the default axis limit of 0 an invalid
83+
datetime. In 3.3 the epoch was changed as above. To convert old
84+
ordinal floats to the new epoch, users can do::
85+
86+
new_ordinal = old_ordinal + mdates.date2num(np.datetime64('0000-12-31'))
87+
88+
89+
There are a number of helper functions to convert between :mod:`datetime`
90+
objects and Matplotlib dates:
91+
92+
.. currentmodule:: matplotlib.dates
93+
94+
.. autosummary::
95+
:toctree: _as_gen
96+
:template: autosummary.rst
97+
:nosignatures:
98+
99+
datestr2num
100+
date2num
101+
num2date
102+
drange
103+
set_epoch
104+
get_epoch
105+
106+
107+
.. note::
108+
109+
Like Python's `datetime.datetime`, Matplotlib uses the Gregorian calendar
110+
for all conversions between dates and floating point numbers. This practice
111+
is not universal, and calendar differences can cause confusing
112+
differences between what Python and Matplotlib give as the number of days
113+
since 0001-01-01 and what other software and databases yield. For
114+
example, the US Naval Observatory uses a calendar that switches
115+
from Julian to Gregorian in October, 1582. Hence, using their
116+
calculator, the number of days between 0001-01-01 and 2006-04-01 is
117+
732403, whereas using the Gregorian calendar via the datetime
118+
module we find::
119+
120+
In [1]: date(2006, 4, 1).toordinal() - date(1, 1, 1).toordinal()
121+
Out[1]: 732401
122+
123+
All the Matplotlib date converters, locators and formatters are timezone aware.
124+
If no explicit timezone is provided, :rc:`timezone` is assumed, provided as a
125+
string. If you want to use a different timezone, pass the *tz* keyword
126+
argument of `num2date` to any date tick locators or formatters you create. This
127+
can be either a `datetime.tzinfo` instance or a string with the timezone name
128+
that can be parsed by `~dateutil.tz.gettz`.
129+
130+
A wide range of specific and general purpose date tick locators and
131+
formatters are provided in this module. See
132+
:mod:`matplotlib.ticker` for general information on tick locators
133+
and formatters. These are described below.
134+
135+
The dateutil_ module provides additional code to handle date ticking, making it
136+
easy to place ticks on any kinds of dates. See examples below.
137+
138+
.. _dateutil: https://dateutil.readthedocs.io
139+
140+
141+
Matplotlib timedelta format
142+
===========================
143+
144+
Matplotlib represents timedeltas using floating point numbers specifying the
145+
number of days, similar to how dates are represented. For example, a timedelta
146+
of 1 day, 06:00 is the floating point number 1.25. The formatters and tick
147+
locators require the use of `datetime.timedelta` objects, therefore, only
148+
timedeltas up to +-999999999 days are supported.
149+
Microsecond precision is achievable for (approximately) +-70 years.
150+
151+
There are two of helper functions to convert between `~datetime.timedelta`
152+
objects and Matplotlib timedeltas. Additionally, Matplotlib defines a
153+
`strftimedelta` function. This is the timedelta equivalent to
154+
`datetime.date.strftime`, but the `datetime` module does not define such a
155+
function for timedeltas.
156+
The format codes for `strftimedelta` are similar to those used for
157+
`~datetime.date.strftime`. The complete reference is given in the documentation
158+
for `strftimedelta`.
159+
160+
.. autosummary::
161+
:toctree: _as_gen
162+
:template: autosummary.rst
163+
:nosignatures:
164+
165+
num2timedelta
166+
timedelta2num
167+
strftimedelta
168+
strftdnum
169+
170+
171+
Tick Locators
172+
=============
173+
174+
Tick locators determine how many ticks are shown on an `~matplotlib.axis.Axis`
175+
and where they are located. Most tick locators create ticks in regular
176+
intervals.
177+
178+
.. inheritance-diagram::
179+
rrulewrapper
180+
DateLocator
181+
AutoDateLocator
182+
RRuleLocator
183+
YearLocator
184+
WeekdayLocator
185+
DayLocator
186+
HourLocator
187+
MinuteLocator
188+
SecondLocator
189+
MicrosecondLocator
190+
TimedeltaLocator
191+
AutoTimedeltaLocator
192+
:parts: 1
193+
:top-classes: matplotlib.ticker.Locator
194+
195+
196+
.. _date-locators:
197+
198+
Date tick locators
199+
------------------
200+
201+
Most of the date tick locators can locate single or multiple ticks. For example::
202+
203+
# import constants for the days of the week
204+
from matplotlib.dates import MO, TU, WE, TH, FR, SA, SU
205+
206+
# tick on Mondays every week
207+
loc = WeekdayLocator(byweekday=MO, tz=tz)
208+
209+
# tick on Mondays and Saturdays
210+
loc = WeekdayLocator(byweekday=(MO, SA))
211+
212+
In addition, most of the constructors take an interval argument::
213+
214+
# tick on Mondays every second week
215+
loc = WeekdayLocator(byweekday=MO, interval=2)
216+
217+
The rrule locator allows completely general date ticking::
218+
219+
# tick every 5th easter
220+
rule = rrulewrapper(YEARLY, byeaster=1, interval=5)
221+
loc = RRuleLocator(rule)
222+
223+
224+
.. autosummary::
225+
:toctree: _as_gen
226+
:template: autosummary_class_only.rst
227+
:nosignatures:
228+
229+
AutoDateLocator
230+
YearLocator
231+
MonthLocator
232+
WeekdayLocator
233+
DayLocator
234+
HourLocator
235+
MinuteLocator
236+
SecondLocator
237+
MicrosecondLocator
238+
DateLocator
239+
RRuleLocator
240+
rrulewrapper
241+
242+
243+
Timedelta tick locators
244+
-----------------------
245+
246+
.. autosummary::
247+
:toctree: _as_gen
248+
:template: autosummary_class_only.rst
249+
:nosignatures:
250+
251+
TimedeltaLocator
252+
AutoTimedeltaLocator
253+
254+
255+
Formatters
256+
==========
257+
258+
Formatters define the format of the tick label.
259+
260+
.. _date-formatters:
261+
262+
Date formatters
263+
---------------
264+
265+
.. autosummary::
266+
:toctree: _as_gen
267+
:template: autosummary_class_only.rst
268+
:nosignatures:
269+
270+
AutoDateFormatter
271+
ConciseDateFormatter
272+
DateFormatter
273+
274+
The automatic date formatters `AutoDateFormatter` and `ConciseDateFormatter`
275+
are most useful when used with the `AutoDateLocator`.
276+
277+
278+
Timedelta formatters
279+
--------------------
280+
281+
.. autosummary::
282+
:toctree: _as_gen
283+
:template: autosummary_class_only.rst
284+
:nosignatures:
285+
286+
AutoTimedeltaFormatter
287+
ConciseTimedeltaFormatter
288+
TimedeltaFormatter
289+
290+
The automatic date formatters `AutoTimedeltaFormatter` and
291+
`ConciseTimedeltaFormatter` are most useful when used with the
292+
`AutoTimedeltaLocator`.
293+
294+
295+
Conversion Interface
296+
====================
297+
298+
.. inheritance-diagram::
299+
DateConverter
300+
ConciseDateConverter
301+
TimedeltaConverter
302+
ConciseTimedeltaConverter
303+
:parts: 1
304+
:top-classes: matplotlib.ticker.Formatter
305+
306+
307+
.. autosummary::
308+
:toctree: _as_gen
309+
:template: autosummary_class_only.rst
310+
:nosignatures:
311+
312+
DateConverter
313+
ConciseDateConverter
314+
TimedeltaConverter
315+
ConciseTimedeltaConverter

0 commit comments

Comments
 (0)
0