Soccer

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

• EPL — English Premier League
• FIFA — Fédération Internationale de Football Association
• MLS — Major League Soccer
• NCAA — National Collegiate Athletic Association
• NWSL — National Women's Soccer League

Extension of the BaseSurfacePlot class to create a soccer pitch.

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 pitch parameters to create a totally-customized pitch. The pitch’s features are parameterized by the basic dimensions of the pitch, which comprise the attributes of the class.

@author: Ross Drucker

class sportypy.surfaces.soccer.SoccerPitch(league_code='', pitch_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 soccer pitch.

This allows for the creation of the soccer pitch in a way that is entirely parameterized by the pitch’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 soccer pitch. The attributes needed to instantiate a particular league’s surface must be specified in the pitch_params dictionary. For many leagues, these will be provided in the surface_dimensions.json file in the data/ subdirectory of sportypy.

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. “Major League Soccer” should be either “MLS” or “mls”). 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 goal when viewing the pitch 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 pitch when viewing the pitch in TV view. The default is 0.0

Type:

float

pitch_updates

A dictionary of updated parameters to use for the soccer pitch. 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

pitch_params

A dictionary containing the following parameters of the pitch:

• pitch_lengthfloat

  The length of the pitch in TV view

• pitch_widthfloat

  The width of the pitch in TV view

• line_thicknessfloat

  The thickness of the lines on the pitch. All lines should have the same thickness

• center_circle_radiusfloat

  The (outer) radius of the center circle on the pitch

• center_mark_radiusfloat

  The radius of the mark at the center at the pitch

• corner_arc_radiusfloat

  The (outer) radius of the arcs in the corners of the pitch

• goal_line_defensive_mark_visibleboolean

  Whether or not the defensive marks beyond the goal line should be visible in the resulting plot

• touchline_defensive_mark_visibleboolean

  Whether or not the defensive marks beyond the touchline should be visible in the resulting plot

• defensive_mark_depthfloat

  The depth (in any direction) of the defensive marks beyond the goal line or touchline

• defensive_mark_distancefloat

  The distance from the interior edge of the goal post to the defensive mark beyond the goal line. This will also be used to determine the distance from the goal line to the defensive mark beyond the touchline

• defensive_mark_separation_from_linefloat

  The distance from the exterior edge of the goal line to the interior edge of the defensive mark

• penalty_box_lengthfloat

  The length of the penalty box in TV view. This is the larger of the two boxes, and is usually 16.5 m (18 yards) from the back edge of the goal line

• penalty_circle_radiusfloat

  The radius of the arc at the top of the penalty box. This is measured from the center of the penalty mark

• penalty_mark_distfloat

  The distance from the back edge of the goal line to the center of the penalty mark

• interior_of_goal_post_to_penalty_boxfloat

  The distance from the interior edge of the goal post to the nearest edge of the penalty box

• interior_of_goal_post_to_goal_boxfloat

  The distance from the interior edge of the goal post to the nearest edge of the goal box

• goal_box_lengthfloat

  The length of the goal box in TV view. This is the smaller of the two boxes, and is usually 5.5 m (6 yards) from the back edge of the goal line

• penalty_mark_radiusfloat

  The radius of the penalty mark

• goal_widthfloat

  The interior distance between the goal posts

• goal_depthfloat

  The depth of the goal from the back edge of the goal line

Type:

dict

cani_change_dimensions()

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

This function is a helper function for the user to aid in customizing a pitch’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 pitch dimensions as a starting point

Return type:

Nothing, but a message will be printed out

cani_color_features()

Determine what features of the pitch 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 pitch.

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 pitch

  • "in bounds only": The full in-bounds area of the pitch

  • "in_bounds_only": The full in-bounds area of the pitch

  • "offense": The offensive half of the pitch. This is the

    TV-right half

  • "offence": The offensive half of the pitch. This is the

    TV-right half

  • "offensivehalfpitch": The offensive half of the pitch.

    This is the TV-right half

  • "offensive_half_pitch": The offensive half of the pitch.

    This is the TV-right half

  • "offensive half pitch": The offensive half of the pitch.

    This is the TV-right half

  • "defense": The defensive half of the pitch. This is the

    TV-left half

  • "defence": The defensive half of the pitch. This is the

    TV-left half

  • "defensivehalfpitch": The defensive half of the pitch.

    This is the TV-left half

  • "defensive_half_pitch": The defensive half of the pitch.

    This is the TV-left half

  • "defensive half pitch": The defensive half of the pitch.

    This is the TV-left half

  The default is "full"

xlimfloat 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 pitch. 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

ylimfloat 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`` upper touchline. 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

rotationfloat or None

Angle (in degrees) through which to rotate the pitch when drawing. If used, this will set the class attribute of _rotation. A value of 0.0 will correspond to a TV view of the pitch, where +``x`` is to the right and +``y`` is on top. The rotation occurs counter clockwise. The default is None

reset_colors()

Reset the features of the pitch 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_pitch_params()

Reset the features of the pitch to their default parameterizations.

The pitch parameters can be passed at the initial instantiation of the class via the pitch_updates parameter, and through the update_pitch_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_pitch_params(pitch_param_updates={}, *args, **kwargs)

Update the pitch’s defining parameters.

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

Parameters:

pitch_updates (dict) – A dictionary where the keys correspond to the name of the parameter of the pitch 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