ENH: Adds custom plot formatting for TimedeltaIndex.

Author: James Goppert <[email protected]>
Author: James Goppert <[email protected]>

Closes #8711
Closes #15067 from jgoppert/tdi_plot_fix and squashes the following commits:

945ec14 [James Goppert] Merge branch 'master' into tdi_plot_fix
7db61ec [James Goppert] Create TimeSeries_TimedeltaFormatter.
232efe6 [James Goppert] Fix comment format and exception type for tdi plotting.
4eff697 [James Goppert] Add more time delta series plotting tests.
f5f32bc [James Goppert] Link time delta index docs to better matplotlib docs.
d588c2c [James Goppert] Fixes test for tdi w/o autofmt_xdate.
b6e6a81 [James Goppert] Disables autofmt_xdate testing.
c7851e3 [James Goppert] Adjusts tdi test draw calls to try to fix CI issue.
7d28842 [James Goppert] Switch to draw_idle to try to fix bug on xticks update.
3abc310 [James Goppert] Try plt.draw() instead of canvas.draw() to fix issue on osx 3.5.
91954bd [James Goppert] Finished unit test for timedelta plotting.
41ebc85 [James Goppert] Fixes for review comments from #15067.
f021cbd [James Goppert] Support nano-second level precision x-axis labels.
5ec65fa [James Goppert] Plot fix for tdi and added more comments.
b967d24 [James Goppert] flake8 fixes for tdi plotting.
efe5636 [James Goppert] Adds custom plot formatting for TimedeltaIndex.

Author: jgoppert

doc/source/visualization.rst

@@ -1245,6 +1245,18 @@ in ``pandas.plot_params`` can be used in a `with statement`:
 
    plt.close('all')
 
+Automatic Date Tick Adjustment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 0.20.0
+
+``TimedeltaIndex`` now uses the native matplotlib
+tick locator methods, it is useful to call the automatic
+date tick adjustment from matplotlib for figures whose ticklabels overlap.
+
+See the :meth:`autofmt_xdate <matplotlib.figure.autofmt_xdate>` method and the
+`matplotlib documentation <http://matplotlib.org/users/recipes.html#fixing-common-date-annoyances>`__ for more.
+
 Subplots
 ~~~~~~~~
 

doc/source/whatsnew/v0.20.0.txt

@@ -155,7 +155,7 @@ Other enhancements
 - ``Series/DataFrame.squeeze()`` have gained the ``axis`` parameter. (:issue:`15339`)
 - ``DataFrame.to_excel()`` has a new ``freeze_panes`` parameter to turn on Freeze Panes when exporting to Excel (:issue:`15160`)
 - HTML table output skips ``colspan`` or ``rowspan`` attribute if equal to 1. (:issue:`15403`)
-
+- ``pd.TimedeltaIndex`` now has a custom datetick formatter specifically designed for nanosecond level precision (:issue:`8711`)
 .. _ISO 8601 duration: https://en.wikipedia.org/wiki/ISO_8601#Durations
 
 .. _whatsnew_0200.api_breaking:

pandas/tests/plotting/test_datetimelike.py

@@ -9,6 +9,7 @@
 from pandas import Index, Series, DataFrame
 
 from pandas.tseries.index import date_range, bdate_range
+from pandas.tseries.tdi import timedelta_range
 from pandas.tseries.offsets import DateOffset
 from pandas.tseries.period import period_range, Period, PeriodIndex
 from pandas.tseries.resample import DatetimeIndex
@@ -1270,6 +1271,63 @@ def test_plot_outofbounds_datetime(self):
         values = [datetime(1677, 1, 1, 12), datetime(1677, 1, 2, 12)]
         self.plt.plot(values)
 
+    def test_format_timedelta_ticks_narrow(self):
+
+        expected_labels = [
+            '00:00:00.00000000{:d}'.format(i)
+            for i in range(10)]
+
+        rng = timedelta_range('0', periods=10, freq='ns')
+        df = DataFrame(np.random.randn(len(rng), 3), rng)
+        ax = df.plot(fontsize=2)
+        fig = ax.get_figure()
+        fig.canvas.draw()
+        labels = ax.get_xticklabels()
+        self.assertEqual(len(labels), len(expected_labels))
+        for l, l_expected in zip(labels, expected_labels):
+            self.assertEqual(l.get_text(), l_expected)
+
+    def test_format_timedelta_ticks_wide(self):
+
+        expected_labels = [
+            '00:00:00',
+            '1 days 03:46:40',
+            '2 days 07:33:20',
+            '3 days 11:20:00',
+            '4 days 15:06:40',
+            '5 days 18:53:20',
+            '6 days 22:40:00',
+            '8 days 02:26:40',
+            ''
+        ]
+
+        rng = timedelta_range('0', periods=10, freq='1 d')
+        df = DataFrame(np.random.randn(len(rng), 3), rng)
+        ax = df.plot(fontsize=2)
+        fig = ax.get_figure()
+        fig.canvas.draw()
+        labels = ax.get_xticklabels()
+        self.assertEqual(len(labels), len(expected_labels))
+        for l, l_expected in zip(labels, expected_labels):
+            self.assertEqual(l.get_text(), l_expected)
+
+    def test_timedelta_plot(self):
+        # test issue #8711
+        s = Series(range(5), timedelta_range('1day', periods=5))
+        _check_plot_works(s.plot)
+
+        # test long period
+        index = timedelta_range('1 day 2 hr 30 min 10 s',
+                                periods=10, freq='1 d')
+        s = Series(np.random.randn(len(index)), index)
+        _check_plot_works(s.plot)
+
+        # test short period
+        index = timedelta_range('1 day 2 hr 30 min 10 s',
+                                periods=10, freq='1 ns')
+        s = Series(np.random.randn(len(index)), index)
+        _check_plot_works(s.plot)
+
 
 def _check_plot_works(f, freq=None, series=None, *args, **kwargs):
     import matplotlib.pyplot as plt

pandas/tools/plotting.py

@@ -1781,7 +1781,7 @@ def _ts_plot(cls, ax, x, data, style=None, **kwds):
 
         lines = cls._plot(ax, data.index, data.values, style=style, **kwds)
         # set date formatter, locators and rescale limits
-        format_dateaxis(ax, ax.freq)
+        format_dateaxis(ax, ax.freq, data.index)
         return lines
 
     def _get_stacking_id(self):

pandas/tseries/converter.py

@@ -1000,3 +1000,33 @@ def __call__(self, x, pos=0):
         else:
             fmt = self.formatdict.pop(x, '')
             return Period(ordinal=int(x), freq=self.freq).strftime(fmt)
+
+
+class TimeSeries_TimedeltaFormatter(Formatter):
+    """
+    Formats the ticks along an axis controlled by a :class:`TimedeltaIndex`.
+    """
+
+    @staticmethod
+    def format_timedelta_ticks(x, pos, n_decimals):
+        """
+        Convert seconds to 'D days HH:MM:SS.F'
+        """
+        s, ns = divmod(x, 1e9)
+        m, s = divmod(s, 60)
+        h, m = divmod(m, 60)
+        d, h = divmod(h, 24)
+        decimals = int(ns * 10**(n_decimals - 9))
+        s = r'{:02d}:{:02d}:{:02d}'.format(int(h), int(m), int(s))
+        if n_decimals > 0:
+            s += '.{{:0{:0d}d}}'.format(n_decimals).format(decimals)
+        if d != 0:
+            s = '{:d} days '.format(int(d)) + s
+        return s
+
+    def __call__(self, x, pos=0):
+        (vmin, vmax) = tuple(self.axis.get_view_interval())
+        n_decimals = int(np.ceil(np.log10(100 * 1e9 / (vmax - vmin))))
+        if n_decimals > 9:
+            n_decimals = 9
+        return self.format_timedelta_ticks(x, pos, n_decimals)

pandas/tseries/plotting.py

@@ -12,11 +12,14 @@
 from pandas.tseries.offsets import DateOffset
 import pandas.tseries.frequencies as frequencies
 from pandas.tseries.index import DatetimeIndex
+from pandas.tseries.period import PeriodIndex
+from pandas.tseries.tdi import TimedeltaIndex
 from pandas.formats.printing import pprint_thing
 import pandas.compat as compat
 
 from pandas.tseries.converter import (TimeSeries_DateLocator,
-                                      TimeSeries_DateFormatter)
+                                      TimeSeries_DateFormatter,
+                                      TimeSeries_TimedeltaFormatter)
 
 # ---------------------------------------------------------------------
 # Plotting functions and monkey patches
@@ -49,7 +52,7 @@ def tsplot(series, plotf, ax=None, **kwargs):
     lines = plotf(ax, series.index._mpl_repr(), series.values, **kwargs)
 
     # set date formatter, locators and rescale limits
-    format_dateaxis(ax, ax.freq)
+    format_dateaxis(ax, ax.freq, series.index)
     return lines
 
 
@@ -278,8 +281,24 @@ def _maybe_convert_index(ax, data):
 # Patch methods for subplot. Only format_dateaxis is currently used.
 # Do we need the rest for convenience?
 
-
-def format_dateaxis(subplot, freq):
+def format_timedelta_ticks(x, pos, n_decimals):
+    """
+    Convert seconds to 'D days HH:MM:SS.F'
+    """
+    s, ns = divmod(x, 1e9)
+    m, s = divmod(s, 60)
+    h, m = divmod(m, 60)
+    d, h = divmod(h, 24)
+    decimals = int(ns * 10**(n_decimals - 9))
+    s = r'{:02d}:{:02d}:{:02d}'.format(int(h), int(m), int(s))
+    if n_decimals > 0:
+        s += '.{{:0{:0d}d}}'.format(n_decimals).format(decimals)
+    if d != 0:
+        s = '{:d} days '.format(int(d)) + s
+    return s
+
+
+def format_dateaxis(subplot, freq, index):
     """
     Pretty-formats the date axis (x-axis).
 
@@ -288,26 +307,38 @@ def format_dateaxis(subplot, freq):
     default, changing the limits of the x axis will intelligently change
     the positions of the ticks.
     """
-    majlocator = TimeSeries_DateLocator(freq, dynamic_mode=True,
-                                        minor_locator=False,
-                                        plot_obj=subplot)
-    minlocator = TimeSeries_DateLocator(freq, dynamic_mode=True,
-                                        minor_locator=True,
-                                        plot_obj=subplot)
-    subplot.xaxis.set_major_locator(majlocator)
-    subplot.xaxis.set_minor_locator(minlocator)
-
-    majformatter = TimeSeries_DateFormatter(freq, dynamic_mode=True,
+
+    # handle index specific formatting
+    # Note: DatetimeIndex does not use this
+    # interface. DatetimeIndex uses matplotlib.date directly
+    if isinstance(index, PeriodIndex):
+
+        majlocator = TimeSeries_DateLocator(freq, dynamic_mode=True,
                                             minor_locator=False,
                                             plot_obj=subplot)
-    minformatter = TimeSeries_DateFormatter(freq, dynamic_mode=True,
+        minlocator = TimeSeries_DateLocator(freq, dynamic_mode=True,
                                             minor_locator=True,
                                             plot_obj=subplot)
-    subplot.xaxis.set_major_formatter(majformatter)
-    subplot.xaxis.set_minor_formatter(minformatter)
-
-    # x and y coord info
-    subplot.format_coord = lambda t, y: (
-        "t = {0}  y = {1:8f}".format(Period(ordinal=int(t), freq=freq), y))
+        subplot.xaxis.set_major_locator(majlocator)
+        subplot.xaxis.set_minor_locator(minlocator)
+
+        majformatter = TimeSeries_DateFormatter(freq, dynamic_mode=True,
+                                                minor_locator=False,
+                                                plot_obj=subplot)
+        minformatter = TimeSeries_DateFormatter(freq, dynamic_mode=True,
+                                                minor_locator=True,
+                                                plot_obj=subplot)
+        subplot.xaxis.set_major_formatter(majformatter)
+        subplot.xaxis.set_minor_formatter(minformatter)
+
+        # x and y coord info
+        subplot.format_coord = lambda t, y: (
+            "t = {0}  y = {1:8f}".format(Period(ordinal=int(t), freq=freq), y))
+
+    elif isinstance(index, TimedeltaIndex):
+        subplot.xaxis.set_major_formatter(
+            TimeSeries_TimedeltaFormatter())
+    else:
+        raise TypeError('index type not supported')
 
     pylab.draw_if_interactive()