earthpy.plot

Functionality around spatial plotting.

earthpy.plot.colorbar(mapobj, size='3%', pad=0.09)[source]

Adjust colorbar height to match the matplotlib axis height.

NOTE: This function requires matplotlib v 3.0.1 or greater or v 2.9 or lower to run properly.

Parameters
  • mapobj (matplotlib axis object) – The image that the colorbar will be representing as a matplotlib axis object.

  • size (char (default = "3%")) – The percent width of the colorbar relative to the plot.

  • pad (int (default = 0.09)) – The space between the plot and the color bar.

Returns

Matplotlib color bar object with the correct width that matches the y-axis height.

Return type

matplotlib.pyplot.colorbar

Examples

>>> import matplotlib.pyplot as plt
>>> import rasterio as rio
>>> import earthpy.plot as ep
>>> from earthpy.io import path_to_example
>>> with rio.open(path_to_example('rmnp-dem.tif')) as src:
...     dem = src.read()
...     fig, ax = plt.subplots(figsize = (10, 5))
>>> im = ax.imshow(dem.squeeze())
>>> ep.colorbar(im)
<matplotlib.colorbar.Colorbar object at 0x...>
>>> ax.set(title="Rocky Mountain National Park DEM")
[Text(...'Rocky Mountain National Park DEM')]
>>> ax.set_axis_off()
>>> plt.show()

(Source code, png, hires.png, pdf)

../_images/earthpy-plot-1.png
earthpy.plot.draw_legend(im_ax, bbox=(1.05, 1), titles=None, cmap=None, classes=None)[source]

Create a custom legend with a box for each class in a raster.

Parameters
  • im_ax (matplotlib image object) – This is the image returned from a call to imshow().

  • bbox (tuple (default = (1.05, 1))) – This is the bbox_to_anchor argument that will place the legend anywhere on or around your plot.

  • titles (list (optional)) – A list of a title or category for each unique value in your raster. This is the label that will go next to each box in your legend. If nothing is provided, a generic “Category x” will be populated.

  • cmap (str (optional)) – Colormap name to be used for legend items.

  • classes (list (optional)) – A list of unique values found in the numpy array that you wish to plot.

Returns

A matplotlib legend object to be placed on the plot.

Return type

matplotlib.pyplot.legend

Example

>>> import numpy as np
>>> import earthpy.plot as ep
>>> import matplotlib.pyplot as plt
>>> im_arr = np.random.uniform(-2, 1, (15, 15))
>>> bins = [-np.Inf, -0.8, 0.8, np.Inf]
>>> im_arr_bin = np.digitize(im_arr, bins)
>>> cat_names = ["Class 1", "Class 2", "Class 3"]
>>> f, ax = plt.subplots()
>>> im = ax.imshow(im_arr_bin, cmap="gnuplot")
>>> im_ax = ax.imshow(im_arr_bin)
>>> leg_neg = ep.draw_legend(im_ax = im_ax, titles = cat_names)
>>> plt.show()

(Source code, png, hires.png, pdf)

../_images/earthpy-plot-2.png
earthpy.plot.hist(arr, colors=['purple'], figsize=(12, 12), cols=2, bins=20, title=None)[source]

Plot histogram for each layer in a numpy array.

Parameters
  • arr (numpy array) – An n-dimensional numpy array from which n histograms will be plotted.

  • colors (list (default = ["purple"])) – A list of color values that should either equal the number of bands or be a single color.

  • figsize (tuple (default = (12, 12))) – The x and y integer dimensions of the output plot.

  • cols (int (default = 2)) – The number of columns for plot grid.

  • bins (int (default = 20)) – The number of bins to generate for the histogram.

  • title (list (optional)) – A list of title values that should either equal the number of bands or be empty.

Returns

figfigure object

The figure object associated with the histogram.

ax or axsax or axes object

The axes object(s) associated with the histogram.

Return type

tuple

Example

>>> import matplotlib.pyplot as plt
>>> import rasterio as rio
>>> import earthpy.plot as ep
>>> from earthpy.io import path_to_example
>>> with rio.open(path_to_example('rmnp-rgb.tif')) as src:
...     img_array = src.read()
>>> ep.hist(img_array,
...     colors=['r', 'g', 'b'],
...     title=['Red', 'Green', 'Blue'],
...     cols=3,
...     figsize=(8, 3))
(<Figure size 800x300 with 3 Axes>, ...)

(Source code, png, hires.png, pdf)

../_images/earthpy-plot-3.png
earthpy.plot.make_col_list(unique_vals, nclasses=None, cmap=None)[source]

Convert a matplotlib named colormap into a discrete list of n-colors in RGB format.

Parameters
  • unique_vals (list) – A list of values to make a color list from.

  • nclasses (int (optional)) – The number of classes.

  • cmap (str (optional)) – Colormap name used to create output list.

Returns

A list of colors based on the given set of values in matplotlib format.

Return type

list

Example

>>> import numpy as np
>>> import earthpy.plot as ep
>>> import matplotlib.pyplot as plt
>>> arr = np.array([[1, 2], [3, 4], [5, 4], [5, 5]])
>>> f, ax = plt.subplots()
>>> im = ax.imshow(arr, cmap="Blues")
>>> the_legend = ep.draw_legend(im_ax=im)
>>> # Get the array and cmap from axis object
>>> cmap_name = im.axes.get_images()[0].get_cmap().name
>>> unique_vals = list(np.unique(im.get_array().data))
>>> cmap_colors = ep.make_col_list(unique_vals, cmap=cmap_name)
earthpy.plot.plot_bands(arr, cmap='Greys_r', figsize=(12, 12), cols=3, title=None, extent=None, cbar=True, scale=True, vmin=None, vmax=None, ax=None)[source]

Plot each band in a numpy array in its own axis.

Assumes band order (band, row, col).

Parameters
  • arr (numpy array) – An n-dimensional numpy array to plot.

  • cmap (str (default = "Greys_r")) – Colormap name for plots.

  • figsize (tuple (default = (12, 12))) – Figure size in inches.

  • cols (int (default = 3)) – Number of columns for plot grid.

  • title (str or list (optional)) – Title of one band or list of titles with one title per band.

  • extent (tuple (optional)) – Bounding box that the data will fill: (minx, miny, maxx, maxy).

  • cbar (Boolean (default = True)) – Turn off colorbar if needed.

  • scale (Boolean (Default = True)) – Turn off bytescale scaling if needed.

  • vmin (Int (Optional)) – Specify the vmin to scale imshow() plots.

  • vmax (Int (Optional)) – Specify the vmax to scale imshow() plots.

Returns

ax or axs – The axes object(s) associated with the plot.

Return type

matplotlib.axes._subplots.AxesSubplot object(s)

Example

>>> import matplotlib.pyplot as plt
>>> import earthpy.plot as ep
>>> from earthpy.io import path_to_example
>>> import rasterio as rio
>>> titles = ['Red', 'Green', 'Blue']
>>> with rio.open(path_to_example('rmnp-rgb.tif')) as src:
...     ep.plot_bands(src.read(),
...                   title=titles,
...                   figsize=(8, 3))
array([<matplotlib.axes._subplots.AxesSubplot object at 0x...

(Source code, png, hires.png, pdf)

../_images/earthpy-plot-4.png
earthpy.plot.plot_rgb(arr, rgb=(0, 1, 2), figsize=(10, 10), str_clip=2, ax=None, extent=None, title='', stretch=None)[source]

Plot three bands in a numpy array as a composite RGB image.

Parameters
  • arr (numpy array) – An n-dimensional array in rasterio band order (bands, rows, columns) containing the layers to plot.

  • rgb (list (default = (0, 1, 2))) – Indices of the three bands to be plotted.

  • figsize (tuple (default = (10, 10)) – The x and y integer dimensions of the output plot.

  • str_clip (int (default = 2)) – The percentage of clip to apply to the stretch. Default = 2 (2 and 98).

  • ax (object (optional)) – The axes object where the ax element should be plotted.

  • extent (tuple (optional)) – The extent object that matplotlib expects (left, right, bottom, top).

  • title (string (optional)) – The intended title of the plot.

  • stretch (Boolean (optional)) – Application of a linear stretch. If set to True, a linear stretch will be applied.

Returns

ax – The axes object associated with the 3 band image.

Return type

axes object

Example

>>> import matplotlib.pyplot as plt
>>> import rasterio as rio
>>> import earthpy.plot as ep
>>> from earthpy.io import path_to_example
>>> with rio.open(path_to_example('rmnp-rgb.tif')) as src:
...     img_array = src.read()
>>> # Before you plot, ensure that the input array does not have nodata values like -9999
>>> ep.plot_rgb(img_array)
<matplotlib.axes._subplots.AxesSubplot object at 0x...

(Source code, png, hires.png, pdf)

../_images/earthpy-plot-5.png