Football

Football is currently supported for the following leagues (in alphabetical order):

• CFL — Canadian Football League
• NCAA — National Collegiate Athletic Association
• NFHS — National Federation of State High Schools
• NFL — National Football League

Extension of the BaseSurfacePlot class to create a football field.

This is a second-level child class of the BaseSurface class, and as such will have access to its attributes and methods. sportypy will ship with pre-defined leagues that will have their own subclass, but a user can manually specify their own field parameters to create a totally-customized field. The field’s features are parameterized by the basic dimensions of the field, which comprise the attributes of the class.

@author: Ross Drucker

class sportypy.surfaces.football.FootballField(league_code='', field_updates={}, color_updates={}, rotation=0.0, x_trans=0.0, y_trans=0.0, units='default', **added_features)

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.

league_code

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

Type:

str

rotation

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

Type:

float

x_trans

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

Type:

float

y_trans

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

Type:

float

field_updates

A dictionary of updated parameters to use for the football field. The default is an empty dictionary

Type:

dict

color_updates

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

Type:

dict

units

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"

Type:

str

field_params

A dictionary containing the following parameters of the field:

• field_lengthfloat

  The length of the field in TV view

• field_widthfloat

  The width of the field in TV view

• endzone_lengthfloat

  The length of the endzone in TV view. This is measured from the field side of the goal line

• minor_line_thicknessfloat

  The thickness of the minor lines on the field. These are usually the hash yard lines and try markings

• goal_line_thicknessfloat

  The thickness of the goal line

• boundary_line_thicknessfloat

  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_heightfloat

  The height of the minor yard lines on the field in the y direction when viewing the field in TV view

• field_border_thicknessfloat

  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_benchbool

  Whether or not to draw the border of the field behind the team bench areas

• major_yard_line_distancefloat

  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_linefloat

  The distance separating the major yard line from the interior edge of the boundary lines

• inbound_cross_hashmark_lengthfloat

  The length, in TV view, of the hash mark that crosses major yard lines

• inbound_hashmark_separationfloat

  The separation between the hash marks (i.e. the minor yard lines) when measured from their interior edges

• inbound_cross_hashmark_separationfloat

  The separation between the hash marks lying on the major yard lines when measured from their interior edges

• sideline_to_outer_yard_linefloat

  The distance between the interior edge of the sideline to the exterior edge of a minor yard line

• sideline_to_bottom_of_numbersfloat

  The distance between the sideline and the bottom edge of the bounding box of the yardage-marking numbers

• number_heightfloat

  The height, in TV view, of the yardage-marking numbers

• try_mark_distancefloat

  The distance between the goal line and the try mark

• try_mark_widthfloat

  The width of the try mark

• arrow_line_distfloat

  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_arrowfloat

  The distance between the inside edge of a directional arrow and the major yard line to which it refers

• top_number_to_arrowfloat

  The distance from the top of the bounding box of a yardage-marking number to the top of the directional arrow

• arrow_basefloat

  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_lengthfloat

  The distance between the tip of the directional arrow and the base

• number_to_yard_linefloat

  The separation between the bounding box of the yardage-marking numeral and the nearest yard line

• number_widthfloat

  The width of the bounding box of the yardage-marking numeral

• numbers_bottomlist of strings

  The text of the markings that run along the bottom of the field in TV view

• numbers_toplist of strings

  The text of the markings that run along the top of the field in TV view

• number_fontstring

  The font with which the numerals on the field should be written in. All fonts should be stored in the fonts/ subdirectory

• restricted_area_widthfloat

  The width of the restricted area

• coaching_box_widthfloat

  The width of the coaching box

• team_bench_widthfloat

  The width of the team bench area

• team_bench_length_field_sidefloat

  The length of the team bench’s edge closest to the field

• team_bench_length_back_sidefloat

  The length of the team bench’s edge furthest from the field

• team_bench_area_border_thicknessfloat

  The thickness of the border around the team bench area. This should not include any borders around the field

• bench_shapestring

  The shape of the bench area. This should either be “trapezoid” or “rectangular”

• additional_minor_yard_lineslist 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_borderedbool

  Whether or not the field should have a border

• extra_apron_paddingfloat

  Any additional padding around the field apron

Type:

dict

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

Return type:

Nothing, but a message will be printed out

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

Return type:

Nothing, but a message will be printed out

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

Return type:

Nothing, but a message will be printed out

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

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()

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

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

Return type:

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

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

Return type:

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