wsba_hockey package

Subpackages

Submodules

wsba_hockey.wsba_main module

wsba_hockey.wsba_main.nhl_agg_stats(games_df: DataFrame, group_by: list[Literal['player_id', 'season', 'team_abbr', 'position', 'season_type', 'strength_state']] = ['player_id', 'season', 'team_abbr', 'position', 'season_type', 'strength_state'], params: dict | None = None, sort: dict = {}, metrics: list[tuple] = [], rates: bool = True, comparison: bool = True, exclude: list = [], manual_agg: dict[str] = {}, schedule_path: str = '/home/runner/work/wsba_hockey/wsba_hockey/src/wsba_hockey/tools/schedule/schedule.csv', roster_path: str | None = None) → DataFrame[source]

Given statistical data, columns, and rosters, return aggregated statistics at the skater, goalie, or team level.

Parameters:

  • games_df (pl.DataFrame) – A DataFrame already containing game-by-game statistical data (generated with nhl_calculate_stats).

  • group_by (list[str], optional) – List of columns to group by. You may provide an optional unspecified but this is currently unstable.

  • params (dict or None, optional) –

    Parameters to filter the games_df by before aggregating. Default is None. In order to filter correctly, set each key to the desired column name in the dataframe and the value to the expression to filter by. A third element in the tuple value can indicate whether to perform the filter before aggregating or after. By default, it will occur before (using ‘before’ or ‘after’).

    Ex. ‘TOI’: (‘>=’, 150, ‘before’) or ‘Date’: (‘between’, ‘2025-12-01’, ‘2026-01-01’)

  • sort (dict[str], optional) – Dict of values formatted with the sort column as the key and a bool determining whether to sort ascending or not as the value. Default is empty leading to default sort.

  • metric (list[tuple], optional) –

    List of additional metrics to calculate. Use one of ‘+’, ‘-’, ‘*’, ‘/’ to perform an operation on any existing column (using pl.eval). The first tuple element should be the name of the metric value, the second the numerator, and the third should be the denominator (if there is none then pass None).

    Ex. [(‘time_on_ice_per_games_played’, ‘time_on_ice’, ‘games_played’), (‘goals_saved_above_expected’, ‘expected_goals_against-goals_against’, None)]

  • rates (bool, optional) – If True, calculates per-sixty-minute rates. Defaults to True.

  • comparison (bool, optional) – If True, calculates percentiles for applicable numeric values. Defaults to True.

  • exclude (list[str], optional) – List of columns to exclude from summation. Default is None (summing all columns that are not grouped by).

  • manual_agg (dict[str], optional) – Dict with manual aggregation clause. Default is empty dict.

  • schedule_path (bool, optional) – If True, specifies the path with schedule data necessary to add schedule data to games_df.

  • roster_path (str or None, optional) – File path to the roster data used for mapping players and teams.

Returns:

A DataFrame containing the aggregated statistics according to the selected parameters.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.nhl_calculate_stats(pbp: DataFrame, group: Literal['skater', 'goalie', 'team'], game_strength: Literal['all'] | str | list[str] = 'all', season_types: int | list[int] = [2, 3], schedule_path: str = '/home/runner/work/wsba_hockey/wsba_hockey/src/wsba_hockey/tools/schedule/schedule.csv', roster_path: str = '/home/runner/work/wsba_hockey/wsba_hockey/src/wsba_hockey/tools/rosters/nhl_rosters.csv') → DataFrame[source]

Given play-by-play data, seasonal information, game strength, rosters, and an xG model, return raw-total statistics at the game level for skaters, goalies, or teams.

Parameters:

  • pbp (pl.DataFrame) – A DataFrame containing play-by-play event data.

  • group (Literal['skater', 'goalie', 'team']) – Type of statistics to calculate. Must be one of ‘skater’, ‘goalie’, or ‘team’.

  • game_strength (int or list[str], optional) – List of game strength states to include (e.g., [‘5v5’,’5v4’,’4v5’]). Default is ‘all’.

  • season_types (int or list[int], optional) – List of season_types to include in scraping process. Default is all regular season and playoff games which are the integers 2 and 3 respectively.

  • roster_path (str, optional) – File path to the roster data used for mapping players and teams.

Returns:

A DataFrame containing the aggregated statistics according to the selected parameters.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.nhl_plot_events(pbp: DataFrame, group: Literal['skater', 'goalie', 'team', 'coach', 'game'], entities: int | str | list[int] | list[str], events: Literal['all'] | str | list[str] = ['missed-shot', 'shot-on-goal', 'goal'], season: int | list[int] | None = None, strengths: Literal['all'] | str | list[str] = 'all', season_types: int | list[int] = 2, strengths_title: str | None = None, marker_dict: dict = {'blocked-shot': 'v', 'faceoff': 'X', 'giveaway': '1', 'goal': '*', 'hit': 'P', 'missed-shot': 'o', 'shot-on-goal': 'D', 'takeaway': '2'}, team_colors: dict = {'away': 'primary', 'home': 'primary'}, titles: str | list[str] | None = None, legend: bool = False, rotation: int | None = 0, display_range: str = 'full')[source]

Given play-by-play data, plot arbitrary event locations for a group of entities.

Parameters:

  • pbp (pl.DataFrame) – A DataFrame containing play-by-play event data.

  • group (Literal['skater','goalie','team','coach','game']) – Entity type to plot (skater, goalie, team, coach, or game).

  • entities (int|str|list[int]|list[str]) – List of entities for the specified group: - skater/goalie: NHL API player_id(s) - team: team_abbr(s) (e.g. ‘BOS’) - coach: coach name(s) as stored in pbp - game: game_id(s)

  • events (str or list[str] or 'all', optional) – Event types to plot. Defaults to wsba.FENWICK_EVENTS. Use ‘all’ to plot all wsba.EVENTS.

  • season (int|list[int]|None) – If provided, filters season(s). If an int is provided with multiple entities, that season is used for all. If a list is provided, it must align one-to-one with entities. If None, seasons are inferred from pbp.

  • strengths (str or list[str] or 'all', optional) – Strength states to include. Default is ‘all’.

  • season_types (int or list[int], optional) – Season type(s) to include. Default is 2 (regular season).

  • strengths_title (str or None, optional) – Optional label for the selected strengths (used on non-game plots).

  • marker_dict (dict, optional) – Mapping from event_type to matplotlib marker.

  • team_colors (dict, optional) – For game plots, selects ‘primary’ or ‘secondary’ for away/home team colors.

  • titles (str or list[str] or None, optional) – Optional title(s) aligned with entities.

  • legend (bool, optional) – If True, show a legend.

  • display_range (str, optional) – Rink display range. Passed to wsba_rink() / hockey_rink.NHLRink.draw() (e.g. ‘full’, ‘offense’, ‘defense’). Default is ‘full’.

  • rotation (int or None, optional) – Rink rotation (degrees). Default is 0.

Returns:

A dictionary of matplotlib figures: {entity: fig}.

Return type:

dict

wsba_hockey.wsba_main.nhl_scrape_draft_rankings(arg: str | Literal['now'] = 'now', category: int = 0, session=None) → DataFrame[source]

Return NHL draft rankings. :param arg: Date formatted as ‘YYYY-MM-DD’ to scrape draft rankings for specific date or ‘now’ for current draft rankings. Default is ‘now’. :type arg: str, optional :param category: Category number for prospects. When arg='now' this does not apply. Categories: 1=North American Skaters, 2=International Skaters, 3=North American Goalies, 4=International Goalies. Default is 0 (all prospects). :type category: int, optional

Returns:

A DataFrame containing draft rankings.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.nhl_scrape_edge(season: int, group: Literal['skater', 'goalie', 'team'], scrape: list[int | str], season_type: int = 2, session=None) → DataFrame[source]

Return NHL EDGE statistics for selected skaters, goalies, or teams.

Nested API fields such as summaries and detail arrays are returned as JSON strings, making the result directly writable to CSV and Parquet.

Parameters:

  • season (int) – The NHL season formatted such as “20242025”.

  • group (Literal['skater', 'goalie', 'team']) – Type of statistics to calculate. Must be one of ‘skater’, ‘goalie’, or ‘team’.

  • scrape (list[int or str]) – List of skaters, goalies, or teams to scrape (player_ids for skaters/goalies and three letter abbreviation (i.e. ‘BOS’) for teams.)

  • season_type (int, optional) – Season type to include. 2 is the regular season and 3 is the playoffs. Defaults to 2.

Returns:

A DataFrame containing NHL EDGE metrics for the requested skaters, goalies, and/or teams for the specified season.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.nhl_scrape_event_data(game_info: dict[int, dict], session=None) → DataFrame[source]

Given NHL game IDs and event IDs, return event sprite tracking data.

The returned frame is flat and directly writable to CSV or Parquet.

Parameters:

game_info (dict[int, dict]) – Dictionary mapping NHL game IDs to event IDs to scrape.

Returns:

A DataFrame containing event sprite tracking data.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.nhl_scrape_game(game_ids: int | list[int], split_shifts: bool = False, export_roster: bool = False, remove: list[str] = [], xg: bool = False, sources: bool = False, errors: bool = False, session=None) → DataFrame | dict[str, DataFrame] | tuple[DataFrame | dict[str, DataFrame], DataFrame][source]

Return complete play-by-play information for one or more NHL games.

The returned play-by-play and optional roster frames contain only scalar columns or JSON-encoded strings, so they can be written directly to CSV or Parquet.

Parameters:

  • game_ids (int or list[int] or ['random', int, int, int]) – NHL game ID, IDs, or a random-game request in the form ['random', n, start_year, end_year].

  • split_shifts (bool, optional) – If True, returns a dict with separate ‘pbp’ and ‘shifts’ DataFrames. Default is False.

  • export_roster (bool, optional) – If True, returns a second DataFrame with rosters for all players in the provided games. Default is False.

  • remove (list[str], optional) – List of event types to remove from the result. Default is an empty list.

  • xg (bool, optional) – If True, calculates xG for the play-by-play data (for most accurate values leave ‘remove’ empty).

  • sources (bool, optional) – If True, saves raw HTML, JSON, SHIFTS, and single-game full play-by-play to a separate folder in the working directory. Default is False.

  • errors (bool, optional) – If True, includes a list of game IDs that failed to scrape in the return. Default is False.

  • session (HTTP session, optional) – Reusable Scrapy-backed session. If omitted, the package uses its thread-local default session.

Returns:

If split_shifts is False, returns a single DataFrame of play-by-play data.

If split_shifts is True, returns a dictionary with keys:

  • ’pbp’: play-by-play events

  • ’shifts’: shift change events

  • ’errors’ (optional): list of game IDs that failed if errors=True

If export_roster is True, returns a tuple of (pbp, roster_df), where pbp is either a DataFrame or a dict (depending on split_shifts).

wsba_hockey.wsba_main.nhl_scrape_game_info(game_ids: list[int], session=None) → DataFrame[source]

Return landing-page information for one or more NHL games.

Nested API fields are JSON-encoded before return so the result can be written directly to CSV or Parquet.

Parameters:

game_ids (int or list[int]) – NHL game ID or IDs to retrieve.

Returns:

An DataFrame containing information for each game.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.nhl_scrape_game_roster(game_ids: int | list[int], session=None) → DataFrame[source]

Return rosters for one or more individual games.

The result contains only export-compatible scalar columns.

Parameters:

  • game_ids (int or list[int]) – NHL game ID or IDs to retrieve.

  • session (HTTP session, optional) – HTTP session to reuse for all roster requests and other scraping calls. If omitted, the package reuses its default pooled session.

Returns:

A DataFrame containing the rosters for all games in the specified list.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.nhl_scrape_player_info(player_ids: list[int], session=None) → DataFrame[source]

Return landing-page data for specified players.

Nested API fields are JSON-encoded before return so the DataFrame can be written directly to CSV or Parquet.

Parameters:

player_ids (int or list[int]) – NHL API player ID or IDs to retrieve.

Returns:

A DataFrame containing player data for specified players.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.nhl_scrape_prospects(team: str, session=None) → DataFrame[source]

Return prospects for the specified team.

Parameters:

team (str) – Three character team abbreviation such as ‘BOS’

Returns:

A DataFrame containing the prospect data for the specified team.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.nhl_scrape_roster(season: int, teams: str | list[str] | None = None, session=None) → DataFrame[source]

Return rosters for selected teams in a given season.

Parameters:

  • season (int) – The NHL season formatted such as “20242025”.

  • teams (str or list[str], optional) – Team abbreviation or list of three-letter team abbreviations.

Returns:

A DataFrame containing the rosters for all teams in the specified season.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.nhl_scrape_schedule(season: int | Literal['now'] = 'now', start: str | None = None, end: str | None = None, session=None) → DataFrame[source]

Retrieve NHL schedule data for a season and optional date range.

Nested API fields are JSON-encoded before return so the DataFrame can be written directly to CSV or Parquet.

Parameters:

  • season (int or str, optional) – NHL season formatted as YYYYYYYY or 'now'. Defaults to 'now'.

  • start (str, optional) – Date string (MM-DD) at which to start. Defaults to None.

  • end (str, optional) – Date string (MM-DD) at which to end. Defaults to None.

  • session (HTTP session, optional) – HTTP session to reuse for this and other scraping calls. If omitted, the package reuses its default pooled session.

Returns:

A DataFrame containing schedule data for the requested range.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.nhl_scrape_season(season: int, split_shifts: bool = False, export_roster: bool = False, season_types: list[int] = [2, 3], remove: list[str] = [], start: str | None = None, end: str | None = None, local: bool = False, local_path: str = '/home/runner/work/wsba_hockey/wsba_hockey/src/wsba_hockey/tools/schedule/schedule.csv', xg: bool = False, sources: bool = False, errors: bool = False, session=None) → DataFrame | dict[str, DataFrame] | tuple[DataFrame | dict[str, DataFrame], DataFrame][source]

Scrape all play-by-play occurring within an NHL season.

Parameters:

  • season (int) – The NHL season formatted such as “20242025”.

  • split_shifts (bool, optional) – If True, returns a dict with separate ‘pbp’ and ‘shifts’ DataFrames. Default is False.

  • export_roster (bool, optional) – If True, returns a second DataFrame with rosters for all players in the provided games. Default is False.

  • season_types (list[int], optional) – Season types to include: 2 for regular season and 3 for playoffs. Defaults to [2, 3].

  • remove (list[str], optional) – List of event types to remove from the result. Default is an empty list.

  • start (str, optional) – The date string (MM-DD) to start the schedule scrape at. Default is None

  • end (str, optional) – The date string (MM-DD) to end the schedule scrape at. Default is None

  • local (bool, optional) – If True, use the local schedule file instead of scraping it.

  • local_path (str, optional) – Path to the schedule data used when local=True. Defaults to the package schedule file.

  • xg (bool, optional) – If True, calculates xG for the play-by-play data (for most accurate values leave ‘remove’ empty).

  • sources (bool, optional) – If True, saves raw HTML, JSON, SHIFTS, and single-game full play-by-play to a separate folder in the working directory. Default is False.

  • errors (bool, optional) – If True, includes a list of game IDs that failed to scrape in the return. Default is False.

  • session (HTTP session, optional) – HTTP session to reuse for schedule and game requests. If omitted, the package reuses its default pooled session.

Returns:

If split_shifts is False, returns a single DataFrame of play-by-play data.

If split_shifts is True, returns a dictionary with keys:

  • ’pbp’: play-by-play events

  • ’shifts’: shift change events

  • ’errors’ (optional): list of game IDs that failed if errors=True.

When export_roster=True, the return is (result, roster_df). Any nested API fields are encoded as JSON strings for portable table export.

wsba_hockey.wsba_main.nhl_scrape_seasons(analytic: bool = False, session=None) → list[int][source]

Returns list of NHL seasons

Parameters:

analytic (bool, optional) – Filters list of seasons to those only included in the WSBA Hockey package (2007-2008 and beyond) if True. Default is False.

Returns:

A list of all NHL seasons.

Return type:

list[int]

wsba_hockey.wsba_main.nhl_scrape_seasons_info(seasons: list[int] = [], session=None) → DataFrame[source]

Return information about NHL seasons.

Nested values from the API are JSON-encoded so the returned DataFrame can be written directly to CSV or Parquet.

Parameters:

seasons (list[int], optional) – NHL seasons formatted as YYYYYYYY. An empty list returns all seasons.

Returns:

A DataFrame containing the information for requested seasons.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.nhl_scrape_standings(arg: int | list[int] | Literal['now'] = 'now', season_type: int = 2, session=None) → DataFrame[source]

Return regular-season standings or a playoff bracket.

Nested values from the API are JSON-encoded before return so the result can be written directly to CSV or Parquet.

Parameters:

  • arg (int or list[int] or str, optional) – A date (YYYY-MM-DD), NHL season (for example 20242025), list of seasons, or 'now'. Defaults to 'now'.

  • season_type (int, optional) – 2 for standings or 3 for the playoff bracket. Defaults to 2.

Returns:

A DataFrame containing the standings information (or playoff bracket).

Return type:

pl.DataFrame

wsba_hockey.wsba_main.nhl_scrape_team_info(country: bool = False, session=None) → DataFrame[source]

Return team or country information from the NHL API.

Parameters:

country (bool, optional) – If True, returns country information instead of NHL team information.

Returns:

A DataFrame containing team or country information from the NHL API.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.repo_load_rosters(seasons: int | list[int] | None = None) → DataFrame[source]

Returns roster data from repository

Parameters:

seasons (int | list[int] | None, optional) – Season or seasons to return. If None, all repository roster data is returned.

Returns:

A DataFrame containing roster data for supplied seasons.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.repo_load_schedule(seasons: int | list[int] | None = None) → DataFrame[source]

Returns schedule data from repository

Parameters:

seasons (int | list[int] | None, optional) – Season or seasons to return. If None, all repository schedule data is returned.

Returns:

A DataFrame containing the schedule data for the specified season and date range.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.repo_load_teaminfo() → DataFrame[source]

Returns team data from repository

Args:

Returns:

A DataFrame containing general team information.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.utility_get_schema(df: DataFrame) → DataFrame[source]

Returns schema for provided dataframe

Parameters:

df (pl.DataFrame) – Any dataframe generated by functions in the wsba-hockey package

Returns:

A DataFrame containing the schema for the specified dataframe.

Return type:

pl.DataFrame

wsba_hockey.wsba_main.utility_get_unique(df: DataFrame) → DataFrame[source]

Returns unique values in each column for provided dataframe.

Parameters:

df (pl.DataFrame) – Any dataframe generated by functions in the wsba-hockey package

Returns:

A DataFrame containing the unique values in each column for the specified dataframe.

Return type:

pl.DataFrame

Module contents