matplotlib 3.5.1

---

---

BackRef

To remove in the future –– matplotlib.dates

Matplotlib provides sophisticated date plotting capabilities, standing on the shoulders of python datetime and the add-on module dateutil .

By default, Matplotlib uses the units machinery described in ~matplotlib.units to convert datetime.datetime , and numpy.datetime64 objects when plotted on an x- or y-axis. The user does not need to do anything for dates to be formatted, but dates often have strict formatting needs, so this module provides many axis locators and formatters. A basic example using numpy.datetime64 is:

import numpy as np

times = np.arange(np.datetime64('2001-01-02'),
                  np.datetime64('2002-02-03'), np.timedelta64(75, 'm'))
y = np.random.randn(len(times))

fig, ax = plt.subplots()
ax.plot(times, y)

.. seealso:: 
    - :doc:`/gallery/text_labels_and_annotations/date`
    - :doc:`/gallery/ticks/date_concise_formatter`
    - :doc:`/gallery/ticks/date_demo_convert`

            <Unimplemented 'target' '.. _date-format:'>
           

Matplotlib date format

Matplotlib represents dates using floating point numbers specifying the number of days since a default epoch of 1970-01-01 UTC; for example, 1970-01-01, 06:00 is the floating point number 0.25. The formatters and locators require the use of datetime.datetime objects, so only dates between year 0001 and 9999 can be represented. Microsecond precision is achievable for (approximately) 70 years on either side of the epoch, and 20 microseconds for the rest of the allowable range of dates (year 0001 to 9999). The epoch can be changed at import time via .dates.set_epoch or dates.epoch to other dates if necessary; see /gallery/ticks/date_precision_and_epochs for a discussion.

new_ordinal = old_ordinal + mdates.date2num(np.datetime64('0000-12-31'))

There are a number of helper functions to convert between datetime objects and Matplotlib dates:

.. currentmodule:: matplotlib.dates
    

.. autosummary:: 
    :nosignatures:
    datestr2num
    date2num
    num2date
    num2timedelta
    drange
    set_epoch
    get_epoch

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, timezone is assumed. If you want to use a custom time zone, pass a datetime.tzinfo instance with the tz keyword argument to num2date , .Axis.axis_date , and any custom date tickers or locators you create.

A wide range of specific and general purpose date tick locators and formatters are provided in this module. See matplotlib.ticker for general information on tick locators and formatters. These are described below.

The :None:None:`dateutil_` module provides additional code to handle date ticking, making it easy to place ticks on any kinds of dates. See examples below.

            <Unimplemented 'target' '.. _dateutil: https://dateutil.readthedocs.io'>
           

Date tickers

Most of the date tickers can locate single or multiple values. For example:

# import constants for the days of the week
from matplotlib.dates import MO, TU, WE, TH, FR, SA, SU

# tick on mondays every week
loc = WeekdayLocator(byweekday=MO, tz=tz)

# tick on mondays and saturdays
loc = WeekdayLocator(byweekday=(MO, SA))

In addition, most of the constructors take an interval argument:

# tick on mondays every second week
loc = WeekdayLocator(byweekday=MO, interval=2)

The rrule locator allows completely general date ticking:

# tick every 5th easter
rule = rrulewrapper(YEARLY, byeaster=1, interval=5)
loc = RRuleLocator(rule)

The available date tickers are:

• MicrosecondLocator : Locate microseconds.

• SecondLocator : Locate seconds.

• MinuteLocator : Locate minutes.

• HourLocator : Locate hours.

• DayLocator : Locate specified days of the month.

• WeekdayLocator : Locate days of the week, e.g., MO, TU.

• MonthLocator : Locate months, e.g., 7 for July.

• YearLocator : Locate years that are multiples of base.

• RRuleLocator : Locate using a matplotlib.dates.rrulewrapper . .rrulewrapper is a simple wrapper around :None:None:`dateutil_`'s dateutil.rrule which allow almost arbitrary date tick specifications. See rrule example </gallery/ticks/date_demo_rrule> .

• AutoDateLocator : On autoscale, this class picks the best DateLocator (e.g., RRuleLocator ) to set the view limits and the tick locations. If called with interval_multiples=True it will make ticks line up with sensible multiples of the tick intervals. E.g. if the interval is 4 hours, it will pick hours 0, 4, 8, etc as ticks. This behaviour is not guaranteed by default.

Date formatters

The available date formatters are:

• AutoDateFormatter : attempts to figure out the best format to use. This is most useful when used with the AutoDateLocator .

• ConciseDateFormatter : also attempts to figure out the best format to use, and to make the format as compact as possible while still having complete date information. This is most useful when used with the AutoDateLocator .

• DateFormatter : use :None:None:`~datetime.datetime.strftime` format strings.

Examples

Back References

The following pages refer to to this document either explicitly or contain code examples using this.

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them