matplotlib.dates#

Inheritance diagram of 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 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 tick 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)

See also

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 rcParams["date.epoch"] (default: '1970-01-01T00:00:00') to other dates if necessary; see Date precision and epochs for a discussion.

Note

Before Matplotlib 3.3, the epoch was 0000-12-31 which lost modern microsecond precision and also made the default axis limit of 0 an invalid datetime. In 3.3 the epoch was changed as above. To convert old ordinal floats to the new epoch, users can do:

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:

datestr2num

Convert a date string to a datenum using dateutil.parser.parse.

date2num

Convert datetime objects to Matplotlib dates.

num2date

Convert Matplotlib dates to datetime objects.

num2timedelta

Convert number of days to a timedelta object.

drange

Return a sequence of equally spaced Matplotlib dates.

set_epoch

Set the epoch (origin for dates) for datetime calculations.

get_epoch

Get the epoch used by dates.

Note

Like Python's datetime.datetime, Matplotlib 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 Matplotlib 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 [1]: date(2006, 4, 1).toordinal() - date(1, 1, 1).toordinal()
Out[1]: 732401

All the Matplotlib date converters, locators and formatters are timezone aware. If no explicit timezone is provided, rcParams["timezone"] (default: 'UTC') is assumed, provided as a string. If you want to use a different timezone, pass the tz keyword argument of num2date to any date tick locators or formatters you create. This can be either a datetime.tzinfo instance or a string with the timezone name that can be parsed by gettz.

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 dateutil module provides additional code to handle date ticking, making it easy to place ticks on any kinds of dates. See examples below.

Date tick locators#

Most of the date tick locators can locate single or multiple ticks. 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 tick locators are:

Date formatters#

The available date formatters are:

class matplotlib.dates.AutoDateFormatter(locator, tz=None, defaultfmt='%Y-%m-%d', *, usetex=None)[source]#

Bases: Formatter

A Formatter which attempts to figure out the best format to use. This is most useful when used with the AutoDateLocator.

AutoDateFormatter has a .scale dictionary that maps tick scales (the interval in days between one major tick) to format strings; this dictionary defaults to

self.scaled = {
    DAYS_PER_YEAR: rcParams['date.autoformatter.year'],
    DAYS_PER_MONTH: rcParams['date.autoformatter.month'],
    1: rcParams['date.autoformatter.day'],
    1 / HOURS_PER_DAY: rcParams['date.autoformatter.hour'],
    1 / MINUTES_PER_DAY: rcParams['date.autoformatter.minute'],
    1 / SEC_PER_DAY: rcParams['date.autoformatter.second'],
    1 / MUSECONDS_PER_DAY: rcParams['date.autoformatter.microsecond'],
}

The formatter uses the format string corresponding to the lowest key in the dictionary that is greater or equal to the current scale. Dictionary entries can be customized:

locator = AutoDateLocator()
formatter = AutoDateFormatter(locator)
formatter.scaled[1/(24*60)] = '%M:%S' # only show min and sec

Custom callables can also be used instead of format strings. The following example shows how to use a custom format function to strip trailing zeros from decimal seconds and adds the date to the first ticklabel:

def my_format_function(x, pos=None):
    x = matplotlib.dates.num2date(x)
    if pos == 0:
        fmt = '%D %H:%M:%S.%f'
    else:
        fmt = '%H:%M:%S.%f'
    label = x.strftime(fmt)
    label = label.rstrip("0")
    label = label.rstrip(".")
    return label

formatter.scaled[1/(24*60)] = my_format_function

Autoformat the date labels.

Parameters:
locatorticker.Locator

Locator that this axis is using.

tzstr or tzinfo, default: rcParams["timezone"] (default: 'UTC')

Ticks timezone. If a string, tz is passed to dateutil.tz.

defaultfmtstr

The default format to use if none of the values in self.scaled are greater than the unit returned by locator._get_unit().

usetexbool, default: rcParams["text.usetex"] (default: False)

To enable/disable the use of TeX's math mode for rendering the results of the formatter. If any entries in self.scaled are set as functions, then it is up to the customized function to enable or disable TeX's math mode itself.

class matplotlib.dates.AutoDateLocator(tz=None, minticks=5, maxticks=None, interval_multiples=True)[source]#

Bases: DateLocator

On autoscale, this class picks the best DateLocator to set the view limits and the tick locations.

Attributes:
intervalddict

Mapping of tick frequencies to multiples allowed for that ticking. The default is

self.intervald = {
    YEARLY  : [1, 2, 4, 5, 10, 20, 40, 50, 100, 200, 400, 500,
               1000, 2000, 4000, 5000, 10000],
    MONTHLY : [1, 2, 3, 4, 6],
    DAILY   : [1, 2, 3, 7, 14, 21],
    HOURLY  : [1, 2, 3, 4, 6, 12],
    MINUTELY: [1, 5, 10, 15, 30],
    SECONDLY: [1, 5, 10, 15, 30],
    MICROSECONDLY: [1, 2, 5, 10, 20, 50, 100, 200, 500,
                    1000, 2000, 5000, 10000, 20000, 50000,
                    100000, 200000, 500000, 1000000],
}

where the keys are defined in dateutil.rrule.

The interval is used to specify multiples that are appropriate for the frequency of ticking. For instance, every 7 days is sensible for daily ticks, but for minutes/seconds, 15 or 30 make sense.

When customizing, you should only modify the values for the existing keys. You should not add or delete entries.

Example for forcing ticks every 3 hours:

locator = AutoDateLocator()
locator.intervald[HOURLY] = [3]  # only show every 3 hours
Parameters:
tzstr or tzinfo, default: rcParams["timezone"] (default: 'UTC')

Ticks timezone. If a string, tz is passed to dateutil.tz.

minticksint

The minimum number of ticks desired; controls whether ticks occur yearly, monthly, etc.

maxticksint

The maximum number of ticks desired; controls the interval between ticks (ticking every other, every 3, etc.). For fine-grained control, this can be a dictionary mapping individual rrule frequency constants (YEARLY, MONTHLY, etc.) to their own maximum number of ticks. This can be used to keep the number of ticks appropriate to the format chosen in AutoDateFormatter. Any frequency not specified in this dictionary is given a default value.

interval_multiplesbool, default: True

Whether ticks should be chosen to be multiple of the interval, locking them to 'nicer' locations. For example, this will force the ticks to be at hours 0, 6, 12, 18 when hourly ticking is done at 6 hour intervals.

get_locator(dmin, dmax)[source]#

Pick the best locator based on a distance.

nonsingular(vmin, vmax)[source]#

Given the proposed upper and lower extent, adjust the range if it is too close to being singular (i.e. a range of ~0).

tick_values(vmin, vmax)[source]#

Return the values of the located ticks given vmin and vmax.

Note

To get tick locations with the vmin and vmax values defined automatically for the associated axis simply call the Locator instance:

>>> print(type(loc))
<type 'Locator'>
>>> print(loc())
[1, 2, 3, 4]
class matplotlib.dates.ConciseDateConverter(formats=None, zero_formats=None, offset_formats=None, show_offset=True, *, interval_multiples=True)[source]#

Bases: DateConverter

axisinfo(unit, axis)[source]#

Return the AxisInfo for unit.

unit is a tzinfo instance or None. The axis argument is required but not used.

class matplotlib.dates.ConciseDateFormatter(locator, tz=None, formats=None, offset_formats=None, zero_formats=None, show_offset=True, *, usetex=None)[source]#

Bases: Formatter

A Formatter which attempts to figure out the best format to use for the date, and to make it as compact as possible, but still be complete. This is most useful when used with the AutoDateLocator:

>>> locator = AutoDateLocator()
>>> formatter = ConciseDateFormatter(locator)
Parameters:
locatorticker.Locator

Locator that this axis is using.

tzstr or tzinfo, default: rcParams["timezone"] (default: 'UTC')

Ticks timezone, passed to dates.num2date.

formatslist of 6 strings, optional

Format strings for 6 levels of tick labelling: mostly years, months, days, hours, minutes, and seconds. Strings use the same format codes as strftime. Default is ['%Y', '%b', '%d', '%H:%M', '%H:%M', '%S.%f']

zero_formatslist of 6 strings, optional

Format strings for tick labels that are "zeros" for a given tick level. For instance, if most ticks are months, ticks around 1 Jan 2005 will be labeled "Dec", "2005", "Feb". The default is ['', '%Y', '%b', '%b-%d', '%H:%M', '%H:%M']

offset_formatslist of 6 strings, optional

Format strings for the 6 levels that is applied to the "offset" string found on the right side of an x-axis, or top of a y-axis. Combined with the tick labels this should completely specify the date. The default is:

['', '%Y', '%Y-%b', '%Y-%b-%d', '%Y-%b-%d', '%Y-%b-%d %H:%M']
show_offsetbool, default: True

Whether to show the offset or not.

usetexbool, default: rcParams["text.usetex"] (default: False)

To enable/disable the use of TeX's math mode for rendering the results of the formatter.

Examples

See Format date ticks using ConciseDateFormatter

(Source code, 2x.png, png)