Plotting 1D data

ProPlot adds new features to various Axes plotting methods using a set of wrapper functions. When a plotting method like plot is “wrapped” by one of these functions, it accepts the same parameters as the wrapper. These features are a strict superset of the matplotlib API. This section documents the features added by wrapper functions to 1D plotting commands like plot, scatter, bar, and barh.

Property cycles

It is often desirable to use different property cycles for different axes or different plot elements. To enable this, the cycle_changer adds the cycle and cycle_kw to the 1D plotting methods. These arguments are passed to the Cycle constructor function, and the resulting property cycle is used to style the input data. ProPlot iterates through property cycle properties when (1) making multiple calls to a plotting command, or (2) plotting successive columns of 2-dimensional input data. For more information on property cycles, see the color cycles section and this matplotlib tutorial.

  1. [1]:
  1. import proplot as plot
  2. import numpy as np
  3. state = np.random.RandomState(51423)
  4. data1 = state.rand(6, 4)
  5. data2 = state.rand(6, 4) * 1.5
  6. with plot.rc.context({'lines.linewidth': 3}):
  7.     fig, axs = plot.subplots(ncols=2)
  8.     axs.format(xlabel='xlabel', ylabel='ylabel', suptitle='Local property cycles demo')
  10.     # Property cycles specific to datasets
  11.     axs[0].plot(data1, cycle='Reds', cycle_kw={'left': 0.3})
  12.     axs[0].plot(data2, cycle='Blues', cycle_kw={'left': 0.3})
  13.     axs[1].plot(
  14.         data1 * data2,
  15.         cycle='black',
  16.         cycle_kw={'linestyle': ('-', '--', '-.', ':')}
  17.     )
  1. /home/docs/checkouts/readthedocs.org/user_builds/proplot/conda/v0.6.4/lib/python3.8/site-packages/proplot/config.py:1454: ProPlotWarning: Rebuilding font cache.

_images/1dplots_2_1.svg

Standardized arguments

The standardize_1d wrapper is used to standardize positional arguments across all 1D plotting methods. standardize_1d allows you to optionally omit x coordinates, in which case they are inferred from the data. It also permits passing 2D y coordinate arrays to any plotting method, in which case the plotting method is called for each column of the array.

  1. [2]:
  1. import proplot as plot
  2. import numpy as np
  4. # Figure and sample data
  5. N = 5
  6. state = np.random.RandomState(51423)
  7. with plot.rc.context({'axes.prop_cycle': plot.Cycle('Grays', N=N, left=0.3)}):
  8.     fig, axs = plot.subplots(ncols=2, share=False)
  9.     x = np.linspace(-5, 5, N)
  10.     y = state.rand(N, 5)
  11.     axs.format(xlabel='xlabel', ylabel='ylabel')
  12.     axs.format(suptitle='Standardized arguments demonstration')
  14.     # Plot by passing both x and y coordinates
  15.     ax = axs[0]
  16.     ax.area(x, -1 * y / N, stacked=True)
  17.     ax.bar(x, y, linewidth=0, alpha=1, width=0.8)
  18.     ax.plot(x, y + 1, linewidth=2)
  19.     ax.scatter(x, y + 2, marker='s', markersize=5**2)
  20.     ax.format(title='Manual x coordinates')
  22.     # Plot by passing just y coordinates
  23.     # Default x coordinates are inferred from DataFrame,
  24.     # inferred from DataArray, or set to np.arange(0, y.shape[0])
  25.     ax = axs[1]
  26.     ax.area(-1 * y / N, stacked=True)
  27.     ax.bar(y, linewidth=0, alpha=1)
  28.     ax.plot(y + 1, linewidth=2)
  29.     ax.scatter(y + 2, marker='s', markersize=5**2)
  30.     ax.format(title='Auto x coordinates')

_images/1dplots_4_0.svg

Pandas and xarray integration

The standardize_1d wrapper integrates 1D plotting methods with pandas DataFrames and xarray DataArrays. When you pass a DataFrame or DataArray to any plotting command, the x-axis label, y-axis label, legend label, colorbar label, and/or title are configured from the metadata. This restores some of the convenience you get with the builtin pandas and xarray plotting functions. This feature is optional; installation of pandas and xarray are not required.

  1. [3]:
  1. import xarray as xr
  2. import numpy as np
  3. import pandas as pd
  5. # DataArray
  6. state = np.random.RandomState(51423)
  7. data = (
  8.     np.sin(np.linspace(0, 2 * np.pi, 20))[:, None]
  9.     + state.rand(20, 8).cumsum(axis=1)
  10. )
  11. da = xr.DataArray(data, dims=('x', 'cat'), coords={
  12.     'x': xr.DataArray(
  13.         np.linspace(0, 1, 20),
  14.         dims=('x',),
  15.         attrs={'long_name': 'distance', 'units': 'km'}
  16.     ),
  17.     'cat': xr.DataArray(
  18.         np.arange(0, 80, 10),
  19.         dims=('cat',),
  20.         attrs={'long_name': 'parameter', 'units': 'K'}
  21.     )
  22. }, name='position series')
  24. # DataFrame
  25. data = (
  26.     (np.cos(np.linspace(0, 2 * np.pi, 20))**4)[:, None] + state.rand(20, 5)**2
  27. )
  28. ts = pd.date_range('1/1/2000', periods=20)
  29. df = pd.DataFrame(data, index=ts, columns=['foo', 'bar', 'baz', 'zap', 'baf'])
  30. df.name = 'time series'
  31. df.index.name = 'time (s)'
  32. df.columns.name = 'columns'
  1. [4]:
  1. import proplot as plot
  2. fig, axs = plot.subplots(ncols=2, axwidth=2.2, share=0)
  3. axs.format(suptitle='Automatic subplot formatting')
  5. # Plot DataArray
  6. cycle = plot.Cycle('dark blue', fade=90, space='hpl', N=da.shape[1])
  7. axs[0].scatter(da, cycle=cycle, lw=3, colorbar='ul', colorbar_kw={'locator': 20})
  9. # Plot Dataframe
  10. cycle = plot.Cycle('dark green', fade=90, space='hpl', N=df.shape[1])
  11. axs[1].plot(df, cycle=cycle, lw=3, legend='uc')
  1. [4]:
  1. (<matplotlib.lines.Line2D at 0x7f5a3318e100>,
  2.  <matplotlib.lines.Line2D at 0x7f5a3318e4f0>,
  3.  <matplotlib.lines.Line2D at 0x7f5a3318e880>,
  4.  <matplotlib.lines.Line2D at 0x7f5a3318ec10>,
  5.  <matplotlib.lines.Line2D at 0x7f5a331d7790>)

_images/1dplots_7_1.svg

Shading and error bars

The indicate_error wrapper lets you draw error bars and error shading on-the-fly by passing certain keyword arguments to plot, scatter, bar, or barh.

If you pass 2D arrays to these methods with means=True or medians=True, the means or medians of each column are drawn as points, lines, or bars, and error bars or shading is drawn to represent the spread of the distribution for each column. You can also specify the error bounds manually with the bardata, boxdata, shadedata, and fadedata keywords. indicate_error can draw thin error bars with optional whiskers, thick “boxes” overlayed on top of these bars (think of this as a miniature boxplot), and up to 2 regions of shading. See indicate_error for details.

  1. [5]:
  1. import proplot as plot
  2. import numpy as np
  3. import pandas as pd
  4. plot.rc['title.loc'] = 'uc'
  6. # Generate sample data
  7. state = np.random.RandomState(51423)
  8. data = state.rand(20, 8).cumsum(axis=0).cumsum(axis=1)[:, ::-1]
  9. data = data + 20 * state.normal(size=(20, 8)) + 30
  10. data = pd.DataFrame(data, columns=np.arange(0, 16, 2))
  11. data.name = 'variable'
  13. # Generate figure
  14. fig, axs = plot.subplots(
  15.     nrows=3, aspect=1.5, axwidth=4,
  16.     share=0, hratios=(2, 1, 1)
  17. )
  18. axs.format(suptitle='Indicating error bounds with various plotting commands')
  19. axs[1:].format(xlabel='column number', xticks=1, xgrid=False)
  21. # Automatically calculate medians and display default percentile range
  22. ax = axs[0]
  23. obj = ax.barh(
  24.     data,
  25.     color='light red', legend=True,
  26.     medians=True, boxpctiles=True, barpctiles=(5, 95),
  27. )
  28. ax.format(title='Column statistics')
  29. ax.format(ylabel='column number', title='Bar plot', ygrid=False)
  31. # Automatically calculate means and display requested standard deviation range
  32. ax = axs[1]
  33. ax.scatter(
  34.     data,
  35.     color='denim', marker='x', markersize=8**2, linewidth=0.8,
  36.     means=True, shadestds=(-1, 1), shadelabel=True, legend='ll',
  37. )
  38. ax.format(title='Scatter plot')
  40. # Manually supply error bar data and legend labels
  41. ax = axs[2]
  42. means = data.mean(axis=0)
  43. means.name = data.name
  44. shadedata = np.percentile(data, (25, 75), axis=0)  # dark shading
  45. fadedata = np.percentile(data, (5, 95), axis=0)  # light shading
  46. ax.plot(
  47.     means,
  48.     shadedata=shadedata, fadedata=fadedata,
  49.     shadelabel='50% CI', fadelabel='90% CI',
  50.     color='ocean blue', barzorder=0, boxmarker=False, legend='ll',
  51. )
  52. ax.format(title='Line plot')
  53. plot.rc.reset()

_images/1dplots_9_0.svg

Bar plots and area plots

The bar and barh methods are wrapped by bar_wrapper, cycle_changer, and standardize_1d. You can now group or stack columns of data by passing 2D arrays to bar or barh, just like in pandas, or use different colors for negative and positive bars by passing negpos=True. Also, bar and barh now employ “default” x coordinates if you failed to provide them explicitly.

To make filled “area” plots, use the new area and areax methods. These are alises for fill_between and fill_betweenx, which are wrapped by fill_between_wrapper and fill_betweenx_wrapper. You can now stack or overlay columns of data by passing 2D arrays to area and areax, just like in pandas. You can also now draw area plots that change color when the fill boundaries cross each other by passing negpos=True to fill_between. The most common use case for this is highlighting negative and positive areas with different colors, as shown below.

  1. [6]:
  1. import proplot as plot
  2. import numpy as np
  3. import pandas as pd
  4. state = np.random.RandomState(51423)
  5. data = state.rand(5, 5).cumsum(axis=0).cumsum(axis=1)[:, ::-1]
  6. data = pd.DataFrame(
  7.     data, columns=pd.Index(np.arange(1, 6), name='column'),
  8.     index=pd.Index(['a', 'b', 'c', 'd', 'e'], name='row idx')
  9. )
  11. # Generate figure
  12. plot.rc.titleloc = 'uc'
  13. fig, axs = plot.subplots(nrows=2, aspect=2, axwidth=4.8, share=0, hratios=(3, 2))
  15. # Side-by-side bars
  16. ax = axs[0]
  17. obj = ax.bar(
  18.     data, cycle='Reds', colorbar='ul',
  19.     edgecolor='red9', colorbar_kw={'frameon': False}
  20. )
  21. ax.format(
  22.     xlocator=1, xminorlocator=0.5, ytickminor=False,
  23.     title='Side-by-side', suptitle='Bar plot demo'
  24. )
  26. # Stacked bars
  27. ax = axs[1]
  28. obj = ax.barh(
  29.     data.iloc[::-1, :], cycle='Blues',
  30.     legend='ur', edgecolor='blue9', stacked=True
  31. )
  32. ax.format(title='Stacked')
  33. axs.format(grid=False)
  34. plot.rc.reset()

_images/1dplots_11_0.svg

  1. [7]:
  1. import proplot as plot
  2. import numpy as np
  3. state = np.random.RandomState(51423)
  4. data = state.rand(5, 3).cumsum(axis=0)
  5. cycle = ('gray3', 'gray5', 'gray7')
  7. # Generate figure
  8. fig, axs = plot.subplots(ncols=2, axwidth=2.3, share=0)
  9. axs.format(grid=False, xlabel='xlabel', ylabel='ylabel', suptitle='Area plot demo')
  11. # Overlaid area patches
  12. ax = axs[0]
  13. ax.area(
  14.     np.arange(5), data, data + state.rand(5)[:, None], cycle=cycle, alpha=0.7,
  15.     legend='uc', legend_kw={'center': True, 'ncols': 2, 'labels': ['z', 'y', 'qqqq']},
  16. )
  17. ax.format(title='Fill between columns')
  19. # Stacked area patches
  20. ax = axs[1]
  21. ax.area(
  22.     np.arange(5), data, stacked=True, cycle=cycle, alpha=0.8,
  23.     legend='ul', legend_kw={'center': True, 'ncols': 2, 'labels': ['z', 'y', 'qqqq']},
  24. )
  25. ax.format(title='Stack between columns')

_images/1dplots_12_0.svg

  1. [8]:
  1. import proplot as plot
  2. import numpy as np
  3. state = np.random.RandomState(51423)
  4. data = 4 * (state.rand(50) - 0.5)
  6. # Generate figure
  7. fig, axs = plot.subplots(nrows=2, width=5, aspect=2)
  8. axs.format(
  9.     xmargin=0, xlabel='xlabel', ylabel='ylabel', grid=True,
  10.     suptitle='Positive and negative colors demo',
  11. )
  12. axs.axhline(0, color='k', linewidth=1)  # zero line
  14. # Bar plot
  15. axs[0].bar(data, width=1, edgecolor='none', negpos=True)
  16. axs[0].format(title='Bar plot')
  18. # Area plot
  19. axs[1].area(data, negpos=True)
  20. axs[1].format(title='Area plot')

_images/1dplots_13_0.svg

Box plots and violin plots

The boxplot and violinplot methods are now wrapped with boxplot_wrapper, violinplot_wrapper, cycle_changer, and standardize_1d. These wrappers add some useful options and apply aesthetically pleasing default settings. They also automatically apply axis labels based on the DataFrame column labels or the input x coordinate labels.

  1. [9]:
  1. import proplot as plot
  2. import numpy as np
  3. import pandas as pd
  5. # Generate sample data
  6. N = 500
  7. state = np.random.RandomState(51423)
  8. data = state.normal(size=(N, 5)) + 2 * (state.rand(N, 5) - 0.5) * np.arange(5)
  9. data = pd.DataFrame(
  10.     data,
  11.     columns=pd.Index(['a', 'b', 'c', 'd', 'e'], name='xlabel')
  12. )
  14. # Generate figure
  15. fig, axs = plot.subplots(ncols=2, axwidth=2.5)
  16. axs.format(grid=False, suptitle='Boxes and violins demo')
  18. # Box plots
  19. ax = axs[0]
  20. obj1 = ax.boxplot(
  21.     data, lw=0.7, marker='x', fillcolor='gray5',
  22.     medianlw=1, mediancolor='k'
  23. )
  24. ax.format(title='Box plots', titleloc='uc')
  26. # Violin plots
  27. ax = axs[1]
  28. obj2 = ax.violinplot(
  29.     data, lw=0.7, fillcolor='gray7',
  30.     points=500, bw_method=0.3, means=True
  31. )
  32. ax.format(title='Violin plots', titleloc='uc')

_images/1dplots_15_0.svg

Parametric plots

To make “parametric” plots, use the new parametric method. Parametric plots are LineCollections that map individual line segments to individual colors, where each segment represents a “parametric” coordinate (e.g. time). The parametric coordinates are specified with the values keyword argument. See parametric for details. As shown below, it is also easy to build colorbars from the LineCollection returned by parametric.

  1. [10]:
  1. import proplot as plot
  2. import numpy as np
  3. fig, axs = plot.subplots(
  4.     share=0, ncols=2, wratios=(2, 1),
  5.     width='16cm', aspect=(2, 1)
  6. )
  7. axs.format(suptitle='Parametric plots demo')
  8. cmap = 'IceFire'
  10. # Parametric line with smooth gradations
  11. ax = axs[0]
  12. state = np.random.RandomState(51423)
  13. N = 50
  14. x = (state.rand(N) - 0.52).cumsum()
  15. y = state.rand(N)
  16. c = np.linspace(-N / 2, N / 2, N)  # color values
  17. m = ax.parametric(
  18.     x, y, c, cmap=cmap, lw=7, interp=5, capstyle='round', joinstyle='round'
  19. )
  20. ax.format(xlabel='xlabel', ylabel='ylabel', title='Line with smooth gradations')
  21. ax.colorbar(m, loc='b', label='parametric coordinate', locator=5)
  23. # Parametric line with stepped gradations
  24. N = 12
  25. ax = axs[1]
  26. radii = np.linspace(1, 0.2, N + 1)
  27. angles = np.linspace(0, 4 * np.pi, N + 1)
  28. x = radii * np.cos(1.4 * angles)
  29. y = radii * np.sin(1.4 * angles)
  30. c = np.linspace(-N / 2, N / 2, N + 1)
  31. m = ax.parametric(x, y, c, cmap=cmap, lw=15)
  32. ax.format(
  33.     xlim=(-1, 1), ylim=(-1, 1), title='Step gradations',
  34.     xlabel='cosine angle', ylabel='sine angle'
  35. )
  36. ax.colorbar(m, loc='b', maxn=10, label='parametric coordinate')
  1. [10]:
  1. <matplotlib.colorbar.Colorbar at 0x7f5a32e3d760>

_images/1dplots_17_1.svg

Other plotting methods

The scatter method is now wrapped by scatter_wrapper, cycle_changer, and standardize_1d. This means that scatter now accepts 2D arrays, just like plot. Also, successive calls to scatter now use the property cycler properties (e.g. color, marker, and markersize), and scatter now optionally accepts keywords that look like plot keywords (e.g. color instead of c and markersize instead of s).

ProPlot also supports property cycling for step plots and wraps the vlines and hlines methods with vlines_wrapper and hlines_wrapper, which adds the ability to use different colors for “negative” and “positive” lines.

  1. [11]:
  1. import proplot as plot
  2. import numpy as np
  3. import pandas as pd
  4. fig, axs = plot.subplots(ncols=2, share=1)
  5. state = np.random.RandomState(51423)
  6. x = (state.rand(20) - 0).cumsum()
  7. data = (state.rand(20, 4) - 0.5).cumsum(axis=0)
  8. data = pd.DataFrame(data, columns=pd.Index(['a', 'b', 'c', 'd'], name='label'))
  10. # Scatter plot with property cycler
  11. ax = axs[0]
  12. ax.format(suptitle='Scatter plot demo', title='Extra prop cycle properties')
  13. obj = ax.scatter(
  14.     x, data, legend='ul', cycle='Set2', legend_kw={'ncols': 2},
  15.     cycle_kw={'marker': ['x', 'o', 'x', 'o'], 'markersize': [5, 10, 20, 30]}
  16. )
  18. # Scatter plot with colormap
  19. ax = axs[1]
  20. ax.format(title='Scatter plot with cmap')
  21. data = state.rand(2, 100)
  22. obj = ax.scatter(
  23.     *data, color=data.sum(axis=0), size=state.rand(100), smin=3, smax=30,
  24.     marker='o', cmap='dark red', colorbar='lr', vmin=0, vmax=2,
  25.     colorbar_kw={'label': 'label', 'locator': 0.5}
  26. )
  27. axs.format(xlabel='xlabel', ylabel='ylabel')

_images/1dplots_19_0.svg

  1. [12]:
  1. import proplot as plot
  2. import numpy as np
  3. state = np.random.RandomState(51423)
  4. fig, axs = plot.subplots(ncols=2, nrows=2, share=0)
  5. axs.format(suptitle='Line plots demo', xlabel='xlabel', ylabel='ylabel')
  7. # Step
  8. ax = axs[0]
  9. data = state.rand(20, 4).cumsum(axis=1).cumsum(axis=0)
  10. cycle = ('blue7', 'gray5', 'red7', 'gray5')
  11. ax.step(data, cycle=cycle, labels=list('ABCD'), legend='ul', legend_kw={'ncol': 2})
  12. ax.format(title='Step plot')
  14. # Stems
  15. ax = axs[1]
  16. data = state.rand(20)
  17. ax.stem(data, linefmt='k-')
  18. ax.format(title='Stem plot')
  20. # Vertical lines
  21. gray = 'gray7'
  22. data = state.rand(20) - 0.5
  23. ax = axs[2]
  24. ax.area(data, color=gray, alpha=0.2)
  25. ax.vlines(data, negpos=True, linewidth=2)
  26. ax.format(title='Vertical lines')
  28. # Horizontal lines
  29. ax = axs[3]
  30. ax.areax(data, color=gray, alpha=0.2)
  31. ax.hlines(data, negpos=True, linewidth=2)
  32. ax.format(title='Horizontal lines')

_images/1dplots_20_0.svg