Deprecate plotfile.

anntzer · anntzer · commit b1141fd7bc11 · 2019-03-31T22:28:06.000+02:00
Various replacements are showcased in plotfile_demo_sgskip.
diff --git a/doc/api/next_api_changes/2019-03-23-AL.rst b/doc/api/next_api_changes/2019-03-23-AL.rst
@@ -0,0 +1,7 @@
+Deprecations
+````````````
+
+`.pyplot.plotfile` is deprecated in favor of separately loading and plotting
+the data.  See :doc:`/gallery/misc/plotfile_demo_sgskip` for various ways to
+use pandas or numpy to load data, and pandas or matplotlib to plot the
+resulting data.
diff --git a/examples/misc/plotfile_demo.py b/examples/misc/plotfile_demo.py
diff --git a/examples/misc/plotfile_demo_sgskip.py b/examples/misc/plotfile_demo_sgskip.py
@@ -0,0 +1,89 @@
+"""
+=============
+plotfile demo
+=============
+
+Replacing the deprecated `plotfile` by pandas or other matplotlib plotting
+methods.
+"""
+
+import matplotlib.pyplot as plt
+import matplotlib.cbook as cbook
+
+import numpy as np
+import pandas as pd
+pd.plotting.register_matplotlib_converters()
+
+# Time series.
+fname = cbook.get_sample_data('msft.csv', asfileobj=False)
+with cbook.get_sample_data('msft.csv') as file:
+    msft = pd.read_csv(file, parse_dates=['Date'])
+
+# Use indices.
+plt.plotfile(fname, (0, 5, 6))
+
+msft.plot(0, [5, 6], subplots=True)
+
+# Use names.
+plt.plotfile(fname, ('date', 'volume', 'adj_close'))
+
+msft.plot("Date", ["Volume", "Adj. Close*"], subplots=True)
+
+# Use semilogy for volume.
+plt.plotfile(fname, ('date', 'volume', 'adj_close'),
+             plotfuncs={'volume': 'semilogy'})
+
+fig, axs = plt.subplots(2, sharex=True)
+msft.plot("Date", "Volume", ax=axs[0], logy=True)
+msft.plot("Date", "Adj. Close*", ax=axs[1])
+
+# Use semilogy for volume (by index).
+plt.plotfile(fname, (0, 5, 6), plotfuncs={5: 'semilogy'})
+
+fig, axs = plt.subplots(2, sharex=True)
+msft.plot(0, 5, ax=axs[0], logy=True)
+msft.plot(0, 6, ax=axs[1])
+
+# Single subplot
+plt.plotfile(fname, ('date', 'open', 'high', 'low', 'close'), subplots=False)
+
+msft.plot("Date", ["Open", "High", "Low", "Close"])
+
+# Use bar for volume
+plt.plotfile(fname, (0, 5, 6), plotfuncs={5: "bar"})
+
+fig, axs = plt.subplots(2, sharex=True)
+axs[0].bar(msft.iloc[:, 0], msft.iloc[:, 5])
+axs[1].plot(msft.iloc[:, 0], msft.iloc[:, 6])
+fig.autofmt_xdate()
+
+###############################################################################
+
+# Unlabeled data.
+fname2 = cbook.get_sample_data('data_x_x2_x3.csv', asfileobj=False)
+with cbook.get_sample_data('data_x_x2_x3.csv') as file:
+    array = np.loadtxt(file)
+
+# Labeling, if no names in csv-file.
+plt.plotfile(fname2, cols=(0, 1, 2), delimiter=' ',
+             names=['$x$', '$f(x)=x^2$', '$f(x)=x^3$'])
+
+fig, axs = plt.subplots(2, sharex=True)
+axs[0].plot(array[:, 0], array[:, 1])
+axs[0].set(ylabel='$f(x)=x^2$')
+axs[1].plot(array[:, 0], array[:, 2])
+axs[1].set(xlabel='$x$', ylabel='$f(x)=x^3$')
+
+# More than one file per figure--illustrated here with a single file.
+plt.plotfile(fname2, cols=(0, 1), delimiter=' ')
+plt.plotfile(fname2, cols=(0, 2), newfig=False,
+             delimiter=' ')  # use current figure
+plt.xlabel(r'$x$')
+plt.ylabel(r'$f(x) = x^2, x^3$')
+
+fig, ax = plt.subplots()
+ax.plot(array[:, 0], array[:, 1])
+ax.plot(array[:, 0], array[:, 2])
+ax.set(xlabel='$x$', ylabel='$f(x)=x^3$')
+
+plt.show()
diff --git a/examples/tests/backend_driver_sgskip.py b/examples/tests/backend_driver_sgskip.py
@@ -212,7 +212,6 @@
     'pcolor_log.py',
     'pcolor_small.py',
     'pie_demo2.py',
-    'plotfile_demo.py',
     'polar_demo.py',
     'polar_legend.py',
     'psd_demo.py',
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2176,6 +2176,7 @@ def polar(*args, **kwargs):
     return ret
 
 
+@cbook.deprecated("3.1")
 def plotfile(fname, cols=(0,), plotfuncs=None,
              comments='#', skiprows=0, checkrows=5, delimiter=',',
              names=None, subplots=True, newfig=True, **kwargs):
