mpl.dates

Matplotlib provides sophisticated date plotting capabilities, standing on the shoulders of python datetime, the add-on modules pytz and dateutil. 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 date2num(), num2date() and drange() are used to facilitate easy conversion to and from 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 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 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 matplotlibrc file. If you leave out a tz timezone instance, the default from your rc file will be assumed. If you want to use a custom time zone, pass a pytz.timezone instance with the tz keyword argument to num2date(), plot_date(), and any custom date tickers or locators you create. See pytz for information on pytz and timezone handling.

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

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)

Here are all the date tickers:

Date formatters

Here all all the date formatters:

Functions

date2num(d) d is either a datetime instance or a sequence of datetimes.
date_ticker_factory(span[, tz, numticks]) Create a date locator with numticks (approx) and a date formatter for span in days.
datestr2num(d[, default]) Convert a date string to a datenum using dateutil.parser.parse().
drange(dstart, dend, delta) Return a date range as float Gregorian ordinals.
epoch2num(e) Convert an epoch or sequence of epochs to the new date format, that is days since 0001.
hours(h) Return hours as days.
julian2num(j) Convert a Julian date (or sequence) to a matplotlib date (or sequence).
minutes(m) Return minutes as days.
mx2num(mxdates) Convert mx datetime instance (or sequence of mx instances) to the new date format.
num2date(x[, tz]) x is a float value which gives the number of days
num2epoch(d) Convert days since 0001 to epoch.
num2julian(n) Convert a matplotlib date (or sequence) to a Julian date (or sequence).
seconds(s) Return seconds as days.
weeks(w) Return weeks as days.

Classes

AutoDateFormatter(locator[, tz, defaultfmt]) This class attempts to figure out the best format to use.
AutoDateLocator([tz, minticks, maxticks, ...]) On autoscale, this class picks the best DateLocator to set the view limits and the tick locations.
DateConverter Converter for datetime.date and datetime.datetime data, or for date/time data represented as it would be converted by date2num().
DateFormatter(fmt[, tz]) Tick location is seconds since the epoch.
DateLocator([tz]) Determines the tick locations when plotting dates.
DayLocator([bymonthday, interval, tz]) Make ticks on occurances of each day of the month.
HourLocator([byhour, interval, tz]) Make ticks on occurances of each hour.
IndexDateFormatter(t, fmt[, tz]) Use with IndexLocator to cycle format strings by index.
MicrosecondLocator([interval, tz]) Make ticks on occurances of each microsecond.
MinuteLocator([byminute, interval, tz]) Make ticks on occurances of each minute.
MonthLocator([bymonth, bymonthday, interval, tz]) Make ticks on occurances of each month month, e.g., 1, 3, 12.
RRuleLocator(o[, tz])
SecondLocator([bysecond, interval, tz]) Make ticks on occurances of each second.
WeekdayLocator([byweekday, interval, tz]) Make ticks on occurances of each weekday.
YearLocator([base, month, day, tz]) Make ticks on a given day of each year that is a multiple of base.
bytespdate2num(fmt[, encoding]) Use this class to parse date strings to matplotlib datenums when you know the date format string of the date you are parsing.
relativedelta([dt1, dt2, years, months, ...]) The relativedelta type is based on the specification of the excellent work done by M.-A.
rrule(freq[, dtstart, interval, wkst, ...]) That’s the base of the rrule operation.
rrulewrapper(freq, **kwargs)
strpdate2num(fmt) Use this class to parse date strings to matplotlib datenums when you know the date format string of the date you are parsing.
xrange xrange(start, stop[, step]) -> xrange object
zip alias of izip