Plotting and display

Every surface inherits these methods: the plotting helpers from BaseSurfacePlot and the display and coordinate methods from BaseSurface.

BaseSurfacePlot

binned_stat_2d

surface.binned_stat_2d(x, y, values, statistic = 'sum', xlim = None, ylim = None, binsize = 1, bins = None)

Create a two-dimensional binned statistic via scipy.

Parameters

• x (numpy.ndarray): A sequence of values to be binned along in the first dimension

• y: A sequence of values to be binned along in the second dimension

• values (numpy.ndarray): The data on which the statistic will be computed. This must have the same shape as x, or a list of sequences that each have the same shape as x

• statistic (str or callable): The statistic to compute via scipy. Per scipy, the following are available:

  • "count": the number of points inside each bin
  • "max": the maximum for points inside each bin
  • "mean": the mean of values for points inside each bin
  • "median": the median for points inside each bin
  • "min": the minimum for points inside each bin
  • "std": the standard deviation for points inside each bin
  • "sum": the sum of the values for points inside each bin
  • {function}: a user-defined function that utilizes a 1-dimensional array of values and outputs a single numerical statistic The default is "sum"

• xlim (tuple of float or tuple of int): The lower and upper bounds of the x coordinates that should be included. This is only used if the bins argument is None

• ylim (tuple of float or tuple of int): The lower and upper bounds of the y coordinates that should be included. This is only used if the bins argument is None

• binsize (float or tuple of float): The size of the bins for any given portion of the surface:

  • a single float: the size of the bins for both dimension
  • a tuple of floats: the size of the bins in each dimension

• bins (int or tuple of ints or numpy.ndarray or tuple of numpy.ndarray,): optional The specifications of each bin:

  • a single int: the number of bins for both dimensions
  • a tuple of ints: the number of bins in each dimension
  • a numpy.ndarray: the bin edges for both dimensions
  • a tuple of numpy.ndarrays: the bin edges in each dimension

Returns

• stat: (nx, ny) numpy.ndarray: The values of the selected statistic in each of the two-dimensional bins

  x_edge: (nx + 1) numpy.ndarray The bin edges along the first dimension

  y_edge: (ny + 1) numpy.ndarray The bin edges along the second dimension

plot

surface.plot(x, y, is_constrained = True, update_display_range = True, zorder = 100, ax = None, **kwargs)

Wrapper for all matplotlib plot functions sportypy supports.

This will plot to areas out of view when the full surface isn't displayed, but the xlim and ylim arguments will constrain the plot's display.

All parameters other than x and y require keywords

Parameters

• x (numpy.ndarray): The x values used in the plot
• y: The y values used in the plot
• is_constrained (boolean): Whether or not the plot should be constrained by the surface's boundary. The default is True
• update_display_range (boolean): Whether or not to allow the plotted points to update the x and y limits of the plot. This is only used when is_constrained == False. The default is False
• zorder (float): Determine the layer onto which the plot will be drawn. It's recommended that this value not be lower than 100. The default is 100
• ax (matplotlib.Axes): The axes object onto which the plot should be added. If not provided, it will use the currently active axes

Returns

• A list of matplotlib.Line2D objects:

scatter

surface.scatter(x, y, is_constrained = True, update_display_range = True, symmetrize = False, zorder = 21, ax = None, **kwargs)

Wrapper for matplotlib's scatter function.

This will create a scatterplot on top of the displayed surface.

Parameters

• x (numpy.ndarray): The x values used in the plot
• y: The y values used in the plot
• is_constrained (boolean): Whether or not the plot should be constrained by the surface's boundary. The default is True
• update_display_range (boolean): Whether or not to allow the plotted points to update the x and y limits of the plot. This is only used when is_constrained == False. The default is False
• symmetrize (boolean): Whether or not to reflect coordinates across the y axis. The default is False
• zorder (int): Determine the layer onto which the plot will be drawn. It's recommended that this value not be lower than 21. The default is 21
• ax (matplotlib.Axes): The axes object onto which the plot should be added. If not provided, it will use the currently active axes

Returns

• A scatterplot of the data:

arrow

surface.arrow(x1, y1, x2, y2, is_constrained = True, update_display_range = True, length_includes_head = True, head_width = 1, zorder = 21, ax = None, **kwargs)

Wrapper for arrow function from matplotlib.

This will plot to areas out of view when the full surface isn't displayed, but the xlim and ylim arguments will constrain the plot's display.

All parameters other than x1, y1, x2, and y2 require keywords

Parameters

• x1 (numpy.ndarray): The starting x-coordinates of the arrows
• y1 (numpy.ndarray): The starting y-coordinates of the arrows
• x2 (numpy.ndarray): The ending x-coordinates of the arrows
• y2 (numpy.ndarray): The ending y-coordinates of the arrows
• is_constrained (boolean): Whether or not the plot should be constrained by the surface's boundary. The default is True
• update_display_range (boolean): Whether or not to allow the plotted points to update the x and y limits of the plot. This is only used when is_constrained == False. The default is False
• length_includes_head (boolean): Whether or not the head of the arrow is to be included in calculating the length of the arrow. The default is True
• head_width (int): Total width of the full head of the arrow. The default is 1
• zorder (int): Determine the layer onto which the plot will be drawn. It's recommended that this value not be lower than 21. The default is 21
• ax (matplotlib.Axes): The axes object onto which the plot should be added. If not provided, it will use the currently active axes
• **kwargs (dict): Any other matplotlib arrow properties

Returns

• A list of matplotlib.FancyArrow objects:

hexbin

surface.hexbin(x, y, values = None, is_constrained = True, update_display_range = True, symmetrize = False, plot_range = None, plot_xlim = None, plot_ylim = None, gridsize = None, binsize = 1, zorder = 11, clip_on = True, ax = None, **kwargs)

Wrapper for hexbin function from matplotlib.

This will plot to areas out of view when the full surface isn't displayed, but the xlim and ylim arguments will constrain the plot's display.

All parameters other than x and y require keywords

Parameters

• x (numpy.ndarray): A sequence of values to be binned along in the first dimension

• y: A sequence of values to be binned along in the second dimension

• values (numpy.ndarray): The data to use for each hexbin. If None, then values of 1 will be assigned to each (x, y) coordinate

• is_constrained (boolean): Whether or not the plot should be constrained by the surface's boundary. The default is True

• update_display_range (boolean): Whether or not to allow the plotted points to update the x and y limits of the plot. This is only used when is_constrained == False. The default is False

• symmetrize (boolean): Whether or not to reflect coordinates and values across the y axis. The default is False

• plot_range (str): Restrict the portion of the surface that can be plotted to.

  This is achieved by removing values outside of the given range in each surface's draw() method. See the surface draw() method for viable options. This will only affect the x-coordinates and can be used in conjunction with ylim, but will be superceded so long as xlim is provided

  If no values are passed for plot_range, plot_xlim, and plot_ylim, all coordinate values will be used

• plot_xlim (float or tuple of floats): The range of x coordinates to include in the plot:

  • a single float: the lower bound of the x coordinates
  • a tuple of floats: the lower and upper bounds of the x coordinates

  If no values are passed for plot_range, plot_xlim, and plot_ylim, all coordinate values will be used

• plot_ylim (float or tuple of floats): The range of y coordinates to include in the plot:

  • a single float: the lower bound of the y coordinates
  • a tuple of floats: the lower and upper bounds of the y coordinates

  If no values are passed for plot_range, plot_xlim, and plot_ylim, all coordinate values will be used

• gridsize (int or tuple of ints): The grid specification. If passed as a single integer, this is the number of hexagons in the x direction. The number of hexagons in the y direction is then chosen such that each hexagon is approximately regular. If passed as a tuple, the first integer will be the number of hexagons in the x direction, and the second will be the number of hexagons in the y direction

• binsize (float or tuple of floats): The size of the bins for any given portion of the surface:

  • a single float: the size of the bins for both dimension
  • a tuple of floats: the size of the bins in each dimension

• zorder (float): Determine the layer onto which the plot will be drawn. It's recommended that this value be between 11 and 15. The default is 11

• clip_on (boolean): Whether or not the matplotlib artist uses clipping. Other plotting features will automatically be set to the same value as is_constrained, but this may result in oddities specific to hexbin. The default is True

• ax (matplotlib.Axes): The axes object onto which the plot should be added. If not provided, it will use the currently active axes

• **kwargs (dict): Any other matplotlib hexbin properties

Returns

• A matplotlib.PolyCollection object of the hexbins:

heatmap

surface.heatmap(x, y, values = None, is_constrained = True, update_display_range = True, symmetrize = False, plot_range = None, plot_xlim = None, plot_ylim = None, statistic = 'sum', binsize = 1, bins = None, zorder = 11, ax = None, **kwargs)

Wrapper for pcolormesh function from matplotlib.

This will plot to areas out of view when the full surface isn't displayed, but the xlim and ylim arguments will constrain the plot's display.

All parameters other than x and y require keywords

Parameters

• x (numpy.ndarray): A sequence of values to be binned along in the first dimension

• y: A sequence of values to be binned along in the second dimension

• values (numpy.ndarray): The data to use for color-mapping. If None, then values of 1 will be assigned to each (x, y) coordinate

• is_constrained (boolean): Whether or not the plot should be constrained by the surface's boundary. The default is True

• update_display_range (boolean): Whether or not to allow the plotted points to update the x and y limits of the plot. This is only used when is_constrained == False. The default is False

• symmetrize (boolean): Whether or not to reflect coordinates and values across the y axis. The default is False

• plot_range (str): Restrict the portion of the surface that can be plotted to.

  This is achieved by removing values outside of the given range in each surface's draw() method. See the surface draw() method for viable options. This will only affect the x-coordinates and can be used in conjunction with ylim, but will be superceded so long as xlim is provided

  If no values are passed for plot_range, plot_xlim, and plot_ylim, all coordinate values will be used

• plot_xlim (float or tuple of floats): The range of x coordinates to include in the plot:

  • a single float: the lower bound of the x coordinates
  • a tuple of floats: the lower and upper bounds of the x coordinates

  If no values are passed for plot_range, plot_xlim, and plot_ylim, all coordinate values will be used

• plot_ylim (float or tuple of floats): The range of y coordinates to include in the plot:

  • a single float: the lower bound of the y coordinates
  • a tuple of floats: the lower and upper bounds of the y coordinates

  If no values are passed for plot_range, plot_xlim, and plot_ylim, all coordinate values will be used

• statistic (str or callable): The statistic to compute via scipy. Per scipy, the following are available:

  • "count": the number of points inside each bin
  • "max": the maximum for points inside each bin
  • "mean": the mean of values for points inside each bin
  • "median": the median for points inside each bin
  • "min": the minimum for points inside each bin
  • "std": the standard deviation for points inside each bin
  • "sum": the sum of the values for points inside each bin
  • {function}: a user-defined function that utilizes a 1-dimensional array of values and outputs a single numerical statistic The default is "sum"

• binsize (float or tuple of floats): The size of the bins for any given portion of the surface:

  • a single float: the size of the bins for both dimension
  • a tuple of floats: the size of the bins in each dimension

• bins (int or tuple of ints or numpy.ndarray or tuple of numpy.ndarray,): optional The specifications of each bin:

  • a single int: the number of bins for both dimensions
  • a tuple of ints: the number of bins in each dimension
  • a numpy.ndarray: the bin edges for both dimensions
  • a tuple of numpy.ndarrays: the bin edges in each dimension

• zorder (float): Determine the layer onto which the heatmap will be drawn. It's recommended that this value be between 11 and 15. The default is 11

• ax (matplotlib.Axes): The axes object onto which the heatmap should be added. If not provided, it will use the currently active axes

• **kwargs (dict): Any other matplotlib heatmap properties

Returns

• A matplotlib.QuadMesh object of the heat map:

contour

surface.contour(x, y, values = None, fill = True, is_constrained = True, update_display_range = True, symmetrize = False, plot_range = None, plot_xlim = None, plot_ylim = None, statistic = 'sum', binsize = 1, bins = None, zorder = 11, ax = None, **kwargs)

Wrapper for matplotlib contour and contourf functions.

This will plot to areas out of view when the full surface isn't displayed, but the xlim and ylim arguments will constrain the plot's display.

All parameters other than x and y require keywords

Parameters

• x (numpy.ndarray): A sequence of values to be binned along in the first dimension

• y: A sequence of values to be binned along in the second dimension

• values (numpy.ndarray): The data to use for color-mapping. If None, then values of 1 will be assigned to each (x, y) coordinate

• fill (boolean): Whether or not to fill in the contours. The default is True

• is_constrained (boolean): Whether or not the plot should be constrained by the surface's boundary. The default is True

• update_display_range (boolean): Whether or not to allow the plotted points to update the x and y limits of the plot. This is only used when is_constrained == False. The default is False

• symmetrize (boolean): Whether or not to reflect coordinates and values across the y axis. The default is False

• plot_range (str): Restrict the portion of the surface that can be plotted to.

  This is achieved by removing values outside of the given range in each surface's draw() method. See the surface draw() method for viable options. This will only affect the x-coordinates and can be used in conjunction with ylim, but will be superceded so long as xlim is provided

  If no values are passed for plot_range, plot_xlim, and plot_ylim, all coordinate values will be used

• plot_xlim (float or tuple of floats): The range of x coordinates to include in the plot:

  • a single float: the lower bound of the x coordinates
  • a tuple of floats: the lower and upper bounds of the x coordinates

  If no values are passed for plot_range, plot_xlim, and plot_ylim, all coordinate values will be used

• plot_ylim (float or tuple of floats): The range of y coordinates to include in the plot:

  • a single float: the lower bound of the y coordinates
  • a tuple of floats: the lower and upper bounds of the y coordinates

  If no values are passed for plot_range, plot_xlim, and plot_ylim, all coordinate values will be used

• statistic (str or callable): The statistic to compute via scipy. Per scipy, the following are available:

  • "count": the number of points inside each bin
  • "max": the maximum for points inside each bin
  • "mean": the mean of values for points inside each bin
  • "median": the median for points inside each bin
  • "min": the minimum for points inside each bin
  • "std": the standard deviation for points inside each bin
  • "sum": the sum of the values for points inside each bin
  • {function}: a user-defined function that utilizes a 1-dimensional array of values and outputs a single numerical statistic The default is "sum"

• binsize (float or tuple of floats): The size of the bins for any given portion of the surface:

  • a single float: the size of the bins for both dimension
  • a tuple of floats: the size of the bins in each dimension

• bins (int or tuple of ints or numpy.ndarray or tuple of numpy.ndarray,): optional The specifications of each bin:

  • a single int: the number of bins for both dimensions
  • a tuple of ints: the number of bins in each dimension
  • a numpy.ndarray: the bin edges for both dimensions
  • a tuple of numpy.ndarrays: the bin edges in each dimension

• zorder (float): Determine the layer onto which the plot will be drawn. It's recommended that this value be between 11 and 15. The default is 11

• ax (matplotlib.Axes): The axes object onto which the plot should be added. If not provided, it will use the currently active axes

• **kwargs (dict): Any other matplotlib contour properties

Returns

• A matplotlib.QuadContourSet object of the contour plot:

BaseSurface

copy_

surface.copy_(param)

Copy what's passed in (if possible).

Most of the plotting functions require an iterable object to be passed in as coordinates. This allows for an iterable array to be copied while also handling the case where a single point may be passed to it.

Parameters

• param (iterable): Any iterable that should be copied. Ususally, these are pandas data frames. However, if a float or int is passed in, this will also work

Returns

• param (iterable or float or int): The copied array, or the passed-in float or int

convert_xy

surface.convert_xy(x, y)

Reposition and scale the x and y coordinates.

The x and y coordinates must be moved to the proper position and rescaled to the size used for the final surface plot.

Parameters

• x (float): The x coordinate(s)
• y (float): The y coordinate(s)

Returns

• x (float): The x coordinate(s) adjusted to the proper position and scale
• y (float): The y coordinate(s) adjusted to the proper position and scale

set_plot_display_range

surface.set_plot_display_range(ax = None, display_range = 'full', xlim = None, ylim = None, for_plot = False, for_display = True)

Set the x and y limits for the plot.

Parameters

• ax (matplotlib.Axes or None): The Axes object onto which xlim and ylim will be set. The default is None
• display_range (str): The portion of the surface to display. The entire surface is drawn regardless, however this reduces the displayed range to be what is desired. This is passed to each surface's _get_plot_range_limits() method to determine the xlim and ylim to be shown. If an invalid value is passed to this method, the full surface will be shown by default. The default is "full"
• xlim (float or tuple of floats or None): If a single float is passed, this will be the lower bound of x to display. If a tuple is passed, it will be the lower and upper bounds of x to display. If None, then the value will be set by the surface's _get_plot_range_limits() method. The default is None
• ylim (float or tuple of floats or None): If a single float is passed, this will be the lower bound of y to display. If a tuple is passed, it will be the lower and upper bounds of y to display. If None, then the value will be set by the surface's _get_plot_range_limits() method. The default is None

Returns

• ax (matplotlib.Axes): A matplotlib Axes object with the surface drawn on it