Football

from sportypy.surfaces.football import FootballField

FootballField

A subclass of BaseSurfacePlot to make a generic football field.

This allows for the creation of the football field in a way that is entirely parameterized by the field's baseline characteristics.

All attributes should default to 0.0 (if of a numeric type) or an empty string (if of a string type). Customized parameters may be specified via a child class (see below) or by directly specifying all necessary attributes of a valid football field. The attributes needed to instantiate a particular league's surface must be specified in the field_params dictionary. For many leagues, these will be provided in the surface_dimensions.json file in the data/ subdirectory of sportypy.

NOTE: By convention of football data, the origin of the coordinate system will be located in the lower-left corner of the field when viewing the field in TV view. All features will be anchored according to this convention, although this may be adjusted via the x_trans and y_trans attributes.

See the BaseSurfacePlot and BaseSurface class definitions for full details.

Attributes

• league_code (str): The league for which the plot should be drawn. This is case-insensitive but should be the shortened name of the league (e.g. "National Football League" should be either "NFL" or "nfl"). The default is an empty string

• rotation (float): The angle (in degrees) through which to rotate the final plot. The default is 0.0

• x_trans (float): The amount that the x coordinates are to be shifted. By convention, the +x axis extends from the center of the surface towards the right-hand endzone when viewing the field in TV view. The default is 0.0

• y_trans (float): The amount that the y coordinates are to be shifted. By convention, the +y axis extends from the center of the surface towards the top of the field when viewing the field in TV view. The default is 0.0

• field_updates (dict): A dictionary of updated parameters to use for the football field. The default is an empty dictionary

• color_updates (dict): A dictionary of coloring parameters to pass to the plot. Defaults are provided in the class per each rule book, but this allows the plot to be more heavily customized/styled. The default is an empty dictionary

• units (str): The units that the final plot should utilize. The default units are the units specified in the rule book of the league. The default is "default"

• field_params (dict): A dictionary containing the following parameters of the field:

  • field_length (float): The length of the field in TV view
  • field_width (float): The width of the field in TV view
  • endzone_length (float): The length of the endzone in TV view. This is measured from the field side of the goal line
  • minor_line_thickness (float): The thickness of the minor lines on the field. These are usually the hash yard lines and try markings
  • goal_line_thickness (float): The thickness of the goal line
  • boundary_line_thickness (float): The thickness of the boundary lines. This should not include any border around the sidelines, the restricted areas, or team bench areas
  • minor_yard_line_height (float): The height of the minor yard lines on the field in the y direction when viewing the field in TV view
  • field_border_thickness (float): The thickness of the border around the field. This will be uniform around the entirety of the field. This should not include the thickness of the boundary lines
  • field_border_behind_bench (bool): Whether or not to draw the border of the field behind the team bench areas
  • major_yard_line_distance (float): The separation between the midpoints of major yard lines. For example, an NFL field's major yard lines are separated by 5 yards. Major yard lines are considered to be the yard lines that span the entire width of the field
  • sideline_to_major_yard_line (float): The distance separating the major yard line from the interior edge of the boundary lines
  • inbound_cross_hashmark_length (float): The length, in TV view, of the hash mark that crosses major yard lines
  • inbound_hashmark_separation (float): The separation between the hash marks (i.e. the minor yard lines) when measured from their interior edges
  • inbound_cross_hashmark_separation (float): The separation between the hash marks lying on the major yard lines when measured from their interior edges
  • sideline_to_outer_yard_line (float): The distance between the interior edge of the sideline to the exterior edge of a minor yard line
  • sideline_to_bottom_of_numbers (float): The distance between the sideline and the bottom edge of the bounding box of the yardage-marking numbers
  • number_height (float): The height, in TV view, of the yardage-marking numbers
  • try_mark_distance (float): The distance between the goal line and the try mark
  • try_mark_width (float): The width of the try mark
  • arrow_line_dist (float): The major yard line distances which should be marked with a directional arrow. These are measured from the goal line (e.g. a value of 10.0 will place a directional arrow every 10 major yard lines from the goal line towards the middle of the field)
  • yard_line_to_arrow (float): The distance between the inside edge of a directional arrow and the major yard line to which it refers
  • top_number_to_arrow (float): The distance from the top of the bounding box of a yardage-marking number to the top of the directional arrow
  • arrow_base (float): The length of the base of the directional arrow. This is the component of the arrow that is parallel to the major yard line to which the arrow corresponds
  • arrow_length (float): The distance between the tip of the directional arrow and the base
  • number_to_yard_line (float): The separation between the bounding box of the yardage-marking numeral and the nearest yard line
  • number_width (float): The width of the bounding box of the yardage-marking numeral
  • numbers_bottom (list of strings): The text of the markings that run along the bottom of the field in TV view
  • numbers_top (list of strings): The text of the markings that run along the top of the field in TV view
  • number_font (string): The font with which the numerals on the field should be written in. All fonts should be stored in the fonts/ subdirectory
  • restricted_area_width (float): The width of the restricted area
  • coaching_box_width (float): The width of the coaching box
  • team_bench_width (float): The width of the team bench area
  • team_bench_length_field_side (float): The length of the team bench's edge closest to the field
  • team_bench_length_back_side (float): The length of the team bench's edge furthest from the field
  • team_bench_area_border_thickness (float): The thickness of the border around the team bench area. This should not include any borders around the field
  • bench_shape (string): The shape of the bench area. This should either be "trapezoid" or "rectangular"
  • additional_minor_yard_lines (list of floats): Any additional yard lines that should be marked on the field, with 0.0 corresponding to the left-hand goal line in TV view
  • field_bordered (bool): Whether the field border gets a white outline by default (True) or a transparent one (False). The border and its outlines are always drawn, as in sportyR
  • extra_apron_padding (float): Any additional padding around the field apron

Leagues

Each class below is a FootballField with that league's rule-book dimensions.

Class	league_code	Description
CFLField	cfl	A subclass of FootballField specific to the CFL.
NCAAField	ncaa	A subclass of FootballField specific to the CFL.
NFHSField	nfhs11	A subclass of FootballField specific to the NFHS.
NFLField	nfl	A subclass of FootballField specific to the NFL.

Methods

draw

FootballField.draw(ax = None, display_range = 'full', xlim = None, ylim = None, rotation = None)

Draw the field.

Parameters

• ax (matplotlib.Axes): An axes object onto which the plot can be drawn. If None is supplied, then the currently-active Axes object will be used

• display_range (str): The portion of the surface to display. The entire surface will always be drawn under the hood, however this parameter limits what is shown in the final plot. The following explain what each display range corresponds to:

  • "full": The entire surface
  • "in bounds only": The full in-bound area of the field
  • "in_bounds_only": The full in-bound area of the field
  • "offense": The offensive half of the field
  • "offence": The offensive half of the field
  • "offensivehalf": The offensive half of the field
  • "offensive_half": The offensive half of the field
  • "offensive half": The offensive half of the field
  • "offensivehalffield": The offensive half of the field
  • "offensive_half_field": The offensive half of the field
  • "offensive half field": The offensive half of the field
  • "defense": The defensive half of the field
  • "defence": The defensive half of the field
  • "defensivehalf": The defensive half of the field
  • "defensive_half": The defensive half of the field
  • "defensive half": The defensive half of the field
  • "defensivehalffield": The defensive half of the field
  • "defensive_half_field": The defensive half of the field
  • "defensive half field": The defensive half of the field
  • "redzone": The offensive red zone
  • "red_zone": The offensive red zone
  • "red zone": The offensive red zone
  • "oredzone": The offensive red zone
  • "offensive_red_zone": The offensive red zone
  • "offensive red zone": The offensive red zone
  • "dredzone": The defensive red zone
  • "defensive_red_zone": The defensive red zone
  • "defensive red zone": The defensive red zone

  The default is "full"

• xlim (float or tuple of floats or None): The display range in the x direction to be used. If a single float is provided, this will be used as the lower bound of the x coordinates to display and the upper bound will be the +x end of the field. If a tuple, the two values will be used to determine the bounds. If None, then the display_range will be used instead to set the bounds. The default is None

• ylim (float or tuple of floats or None): The display range in the y direction to be used. If a single float is provided, this will be used as the lower bound of the y coordinates to display and the upper bound will be the +y side of the field. If a tuple, the two values will be used to determine the bounds. If None, then the display_range will be used instead to set the bounds. The default is None

• rotation (float or None): Angle (in degrees) through which to rotate the field when drawing. If used, this will set the class attribute of _rotation. A alue of 0.0 will correspond to a TV view of the field, where +x is to the right and +y is on top. The rotation occurs counterclockwise. The default is None

cani_plot_leagues

FootballField.cani_plot_leagues(league_code = None)

Show if a league can be plotted, or what leagues are pre-defined.

A user may wish to know if a specific curling league can be plotted. This method allows a user to check if that specific league code comes shipped with sportypy for easier plotting (if they provide the league code), or can also show what leagues are available to be plotted

Parameters

• league_code (str or None): A league code that may or may not be shipped with the package. If the league code is None, this will display all leagues that do come shipped with sportypy. The default is None

Returns

• Nothing, but a message will be printed out:

cani_color_features

FootballField.cani_color_features()

Determine what features of the field can be colored.

This function is a helper function for the user to aid in plot styling and customization. The printed result of this method will be the names of the features that are able to be colored

Returns

• Nothing, but a message will be printed out:

cani_change_dimensions

FootballField.cani_change_dimensions()

Determine what features of the field can be re-parameterized.

This function is a helper function for the user to aid in customizing a field's parameters. The printed result of this method will be the names of the features that are able to be reparameterized. This method is also useful when defining new features and using an existing league's field dimensions as a starting point

Returns

• Nothing, but a message will be printed out:

update_colors

FootballField.update_colors(color_updates = {}, *args, **kwargs)

Update the colors currently used in the plot.

The colors can be passed at the initial instantiation of the class via the color_updates parameter, but this method allows the colors to be updated after the initial instantiation and will re-instantiate the class with the new colors

Parameters

• color_updates (dict): A dictionary where the keys correspond to the name of the feature that's color is to be updated (see cani_color_features() method for a list of these names). The default is an empty dictionary

Returns

• Nothing, but the class is re-instantiated with the updated colors:

update_field_params

FootballField.update_field_params(field_param_updates = {}, *args, **kwargs)

Update the field's defining parameters.

This method should primarily be used in cases when plotting a league not currently supported by sportypy

Parameters

• field_updates (dict): A dictionary where the keys correspond to the name of the parameter of the field that is to be updated (see cani_change_dimensions() method for a list of these parameters). The default is an empty dictionary

Returns

• Nothing, but the class is re-instantiated with the updated parameters:

reset_colors

FootballField.reset_colors()

Reset the features of the field to their default color set.

The colors can be passed at the initial instantiation of the class via the color_updates parameter, and through the update_colors() method, these can be changed. This method allows the colors to be reset to their default values after experiencing such a change

reset_field_params

FootballField.reset_field_params()

Reset the features of the field to their default parameterizations.

The field parameters can be passed at the initial instantiation of the class via the field_updates parameter, and through the update_field_params() method, these can be changed. This method allows the feature parameterization to be reset to their default values after experiencing such a change