wsba-hockey 1.1.6__py3-none-any.whl → 1.1.8__py3-none-any.whl

wsba_hockey/__init__.py

@@ -1 +1 @@
-from wsba_hockey.wsba_main import nhl_scrape_game,nhl_scrape_schedule,nhl_scrape_season,nhl_scrape_seasons_info,nhl_scrape_standings,nhl_scrape_roster,nhl_scrape_draft_rankings,nhl_scrape_prospects,nhl_calculate_stats,nhl_shooting_impacts,nhl_apply_xG,nhl_plot_skaters_shots,nhl_plot_games,repo_load_rosters,repo_load_schedule,repo_load_teaminfo,repo_load_pbp,repo_load_seasons
+from wsba_hockey.wsba_main import nhl_scrape_game,nhl_scrape_schedule,nhl_scrape_season,nhl_scrape_seasons_info,nhl_scrape_standings,nhl_scrape_roster,nhl_scrape_draft_rankings,nhl_scrape_prospects,nhl_calculate_stats,nhl_apply_xG,nhl_plot_skaters_shots,nhl_plot_games,repo_load_rosters,repo_load_schedule,repo_load_teaminfo,repo_load_pbp,repo_load_seasons

wsba_hockey/api/api/index.py

@@ -90,14 +90,7 @@ def schedule_info(season: int):
 
 @app.get("/nhl/games/{game_id}")
 def pbp(game_id: int):
-    info = rs.get(f'https://api-web.nhle.com/v1/gamecenter/{game_id}/play-by-play').json()
-
-    season = info['season']
-    dataset = ds.dataset(f's3://weakside-breakout/pbp/parquet/nhl_pbp_{season}.parquet', format='parquet')
-    filter_expr = (ds.field('game_id')==game_id)
-
-    table = dataset.to_table(use_threads=True,filter=filter_expr)
-    df = table.to_pandas()
+    df = pd.read_csv(f'data/sources/20242025/{game_id}.csv')
 
     df = df.fillna('')
 

wsba_hockey/tools/scraping.py

@@ -1,6 +1,7 @@
 import re
 import warnings
 import os
+import asyncio
 import numpy as np
 import pandas as pd
 import requests as rs
@@ -179,7 +180,7 @@ def get_game_info(game_id):
             'coaches':get_game_coaches(game_id),
             'json_shifts':json_shifts}
 
-def parse_json(info):
+async def parse_json(info):
     #Given game info, return JSON document
 
     #Retreive data
@@ -340,7 +341,7 @@ def clean_html_pbp(info):
 
     return cleaned_html
 
-def parse_html(info):
+async def parse_html(info):
     #Given game info, return HTML event data
 
     #Retreive game information and html events
@@ -561,7 +562,7 @@ def espn_game_id(date,away,home):
     #Return: ESPN game id
     return game_id
 
-def parse_espn(date,away,home):
+async def parse_espn(date,away,home):
     #Given a date formatted as YYYY-MM-DD and teams, return game events
     game_id = espn_game_id(date,away,home)
     url = f'https://www.espn.com/nhl/playbyplay/_/gameId/{game_id}'
@@ -711,15 +712,24 @@ def assign_target(data):
     #Revert sort and return dataframe
     return data.reset_index()
 
-def combine_pbp(info,sources):
+async def combine_pbp(info,sources):
     #Given game info, return complete play-by-play data for provided game
 
-    html_pbp = parse_html(info)
+    #Create tasks
+    html_task = asyncio.create_task(parse_html(info))
+    if info['season'] in [20052006, 20062007, 20072008, 20082009, 20092010]:
+        json_task = asyncio.create_task(parse_espn(str(info['game_date']),info['away_team_abbr'],info['home_team_abbr']))
+        json_type = 'espn'
+    else:
+        json_task = asyncio.create_task(parse_json(info))
+        json_type = 'nhl'
 
+    html_pbp, json_pbp = await asyncio.gather(html_task, json_task)
+    
     #Route data combining - json if season is after 2009-2010:
-    if str(info['season']) in ['20052006','20062007','20072008','20082009','20092010']:
+    if json_type == 'espn':
         #ESPN x HTML
-        espn_pbp = parse_espn(str(info['game_date']),info['away_team_abbr'],info['home_team_abbr']).rename(columns={'coords_x':'x',"coords_y":'y'}).sort_values(['period','seconds_elapsed']).reset_index()
+        espn_pbp = json_pbp.rename(columns={'coords_x':'x',"coords_y":'y'}).sort_values(['period','seconds_elapsed']).reset_index()
         merge_col = ['period','seconds_elapsed','event_type','event_team_abbr']
 
         #Merge pbp
@@ -727,8 +737,6 @@ def combine_pbp(info,sources):
 
     else:
         #JSON x HTML
-        json_pbp = parse_json(info)
-
         if sources:
             dirs_html = f'sources/{info['season']}/HTML/'
             dirs_json = f'sources/{info['season']}/JSON/'
@@ -1077,12 +1085,10 @@ def combine_shifts(info,sources):
     #Return: full shifts data converted to play-by-play format
     return full_shifts
 
-def combine_data(info,sources):
+async def combine_data(info,sources):
     #Given game info, return complete play-by-play data
 
-    game_id = info['game_id']
-
-    pbp = combine_pbp(info,sources)
+    pbp = await combine_pbp(info,sources)
     shifts = combine_shifts(info,sources)
 
     #Combine data    

wsba_hockey/workspace.py

@@ -1,7 +1,7 @@
 import numpy as np
 import pandas as pd
-import wsba_main as wsba
-import data_pipelines as data
+import wsba_hockey as wsba
+import wsba_hockey.data_pipelines as data
 import numpy as np
 
 season_load = wsba.repo_load_seasons()

wsba_hockey/wsba_main.py

@@ -2,7 +2,9 @@ import random
 import os
 import requests as rs
 import pandas as pd
+import asyncio
 import time
+from typing import Literal, Union
 from datetime import datetime, timedelta, date
 from wsba_hockey.tools.scraping import *
 from wsba_hockey.tools.xg_model import *
@@ -14,44 +16,44 @@ from wsba_hockey.tools.plotting import *
 
 ## GLOBAL VARIABLES ##
 SEASONS = [
-    '20072008',
-    '20082009',
-    '20092010',
-    '20102011',
-    '20112012',
-    '20122013',
-    '20132014',
-    '20142015',
-    '20152016',
-    '20162017',
-    '20172018',
-    '20182019',
-    '20192020',
-    '20202021',
-    '20212022',
-    '20222023',
-    '20232024',
-    '20242025'
+    20072008,
+    20082009,
+    20092010,
+    20102011,
+    20112012,
+    20122013,
+    20132014,
+    20142015,
+    20152016,
+    20162017,
+    20172018,
+    20182019,
+    20192020,
+    20202021,
+    20212022,
+    20222023,
+    20232024,
+    20242025
 ]
 
-CONVERT_SEASONS = {'2007': '20072008', 
-                   '2008': '20082009', 
-                   '2009': '20092010', 
-                   '2010': '20102011', 
-                   '2011': '20112012', 
-                   '2012': '20122013', 
-                   '2013': '20132014', 
-                   '2014': '20142015', 
-                   '2015': '20152016', 
-                   '2016': '20162017', 
-                   '2017': '20172018', 
-                   '2018': '20182019', 
-                   '2019': '20192020', 
-                   '2020': '20202021', 
-                   '2021': '20212022', 
-                   '2022': '20222023', 
-                   '2023': '20232024', 
-                   '2024': '20242025'}
+CONVERT_SEASONS = {2007: 20072008, 
+                   2008: 20082009, 
+                   2009: 20092010, 
+                   2010: 20102011, 
+                   2011: 20112012, 
+                   2012: 20122013, 
+                   2013: 20132014, 
+                   2014: 20142015, 
+                   2015: 20152016, 
+                   2016: 20162017, 
+                   2017: 20172018, 
+                   2018: 20182019, 
+                   2019: 20192020, 
+                   2020: 20202021, 
+                   2021: 20212022, 
+                   2022: 20222023, 
+                   2023: 20232024, 
+                   2024: 20242025}
 
 CONVERT_TEAM_ABBR = {'L.A':'LAK',
                      'N.J':'NJD',
@@ -64,46 +66,25 @@ PER_SIXTY = ['Fi','xGi','Gi','A1','A2','P1','P','Si','OZF','NZF','DZF','FF','FA'
 #Some games in the API are specifically known to cause errors in scraping.
 #This list is updated as frequently as necessary
 KNOWN_PROBS = {
-    '2007020011':'Missing shifts data for game between Chicago and Minnesota.',
-    '2007021178':'Game between the Bruins and Sabres is missing data after the second period, for some reason.',
-    '2008020259':'HTML data is completely missing for this game.',
-    '2008020409':'HTML data is completely missing for this game.',
-    '2008021077':'HTML data is completely missing for this game.',
-    '2009020081':'HTML pbp for this game between Pittsburgh and Carolina is missing all but the period start and first faceoff events, for some reason.',
-    '2009020658':'Missing shifts data for game between New York Islanders and Dallas.',
-    '2009020885':'Missing shifts data for game between Sharks and Blue Jackets.',
-    '2010020124':'Game between Capitals and Hurricanes is sporadically missing player on-ice data',
-    '2012020018':'HTML events contain mislabeled events.',
-    '2013020971':'On March 10th, 2014, Stars forward Rich Peverley suffered from a cardiac episode midgame and as a result, the remainder of the game was postponed.  \nThe game resumed on April 9th, and the only goal scorer in the game, Blue Jackets forward Nathan Horton, did not appear in the resumed game due to injury.  Interestingly, Horton would never play in the NHL again.',
-    '2018021133':'Game between Lightning and Capitals has incorrectly labeled event teams (i.e. WSH TAKEAWAY - #71 CIRELLI (Cirelli is a Tampa Bay skater in this game)).',
-    '2019020876':'Due to the frightening collapse of Blues defensemen Jay Bouwmeester, a game on February 2nd, 2020 between the Ducks and Blues was postponed.  \nWhen the game resumed, Ducks defensemen Hampus Lindholm, who assisted on a goal in the inital game, did not play in the resumed match.'
+    2007020011:'Missing shifts data for game between Chicago and Minnesota.',
+    2007021178:'Game between the Bruins and Sabres is missing data after the second period, for some reason.',
+    2008020259:'HTML data is completely missing for this game.',
+    2008020409:'HTML data is completely missing for this game.',
+    2008021077:'HTML data is completely missing for this game.',
+    2009020081:'HTML pbp for this game between Pittsburgh and Carolina is missing all but the period start and first faceoff events, for some reason.',
+    2009020658:'Missing shifts data for game between New York Islanders and Dallas.',
+    2009020885:'Missing shifts data for game between Sharks and Blue Jackets.',
+    2010020124:'Game between Capitals and Hurricanes is sporadically missing player on-ice data',
+    2012020018:'HTML events contain mislabeled events.',
+    2013020971:'On March 10th, 2014, Stars forward Rich Peverley suffered from a cardiac episode midgame and as a result, the remainder of the game was postponed.  \nThe game resumed on April 9th, and the only goal scorer in the game, Blue Jackets forward Nathan Horton, did not appear in the resumed game due to injury.  Interestingly, Horton would never play in the NHL again.',
+    2018021133:'Game between Lightning and Capitals has incorrectly labeled event teams (i.e. WSH TAKEAWAY - #71 CIRELLI (Cirelli is a Tampa Bay skater in this game)).',
+    2019020876:'Due to the frightening collapse of Blues defensemen Jay Bouwmeester, a game on February 2nd, 2020 between the Ducks and Blues was postponed.  \nWhen the game resumed, Ducks defensemen Hampus Lindholm, who assisted on a goal in the inital game, did not play in the resumed match.'
 }
 
 SHOT_TYPES = ['wrist','deflected','tip-in','slap','backhand','snap','wrap-around','poke','bat','cradle','between-legs']
 
 NEW = 2024
 
-STANDINGS_END = {
-    '20072008':'04-06',
-    '20082009':'04-12',
-    '20092010':'04-11',
-    '20102011':'04-10',
-    '20112012':'04-07',
-    '20122013':'04-28',
-    '20132014':'04-13',
-    '20142015':'04-11',
-    '20152016':'04-10',
-    '20162017':'04-09',
-    '20172018':'04-08',
-    '20182019':'04-06',
-    '20192020':'03-11',
-    '20202021':'05-19',
-    '20212022':'04-01',
-    '20222023':'04-14',
-    '20232024':'04-18',
-    '20242025':'04-17'
-}
-
 EVENTS = ['faceoff','hit','giveaway','takeaway','blocked-shot','missed-shot','shot-on-goal','goal','penalty']
 
 DIR = os.path.dirname(os.path.realpath(__file__))
@@ -112,29 +93,41 @@ INFO_PATH = os.path.join(DIR,'tools\\teaminfo\\nhl_teaminfo.csv')
 DEFAULT_ROSTER = os.path.join(DIR,'tools\\rosters\\nhl_rosters.csv')
 
 ## SCRAPE FUNCTIONS ##
-def nhl_scrape_game(game_ids,split_shifts = False, remove = ['period-start','period-end','challenge','stoppage','shootout-complete','game-end'],verbose = False, sources = False, errors = False):
-    #Given a set of game_ids (NHL API), return complete play-by-play information as requested
-    # param 'game_ids' - NHL game ids (or list formatted as ['random', num_of_games, start_year, end_year])
-    # param 'split_shifts' - boolean which splits pbp and shift events if true
-    # param 'remove' - list of events to remove from final dataframe
-    # param 'xg' - xG model to apply to pbp for aggregation
-    # param 'verbose' - boolean which adds additional event info if true
-    # param 'sources - boolean scraping the html and json sources to a master directory if true 
-    # param 'errors' - boolean returning game ids which did not scrape if true
-
+def nhl_scrape_game(game_ids:list[int], split_shifts:bool = False, remove:list[str] = [], verbose:bool = False, sources:bool = False, errors:bool = False):
+    """
+    Given a set of game_ids (NHL API), return complete play-by-play information as requested.
+
+    Args:
+        game_ids (List[int] or ['random', int, int, int]):
+            List of NHL game IDs to scrape or use ['random', n, start_year, end_year] to fetch n random games.
+        split_shifts (bool, optional):
+            If True, returns a dict with separate 'pbp' and 'shifts' DataFrames. Default is False.
+        remove (List[str], optional):
+            List of event types to remove from the result. Default is an empty list.
+        verbose (bool, optional):
+            If True, generates extra event features (such as those required to calculate xG). Default is False.
+        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.
+
+    Returns:
+        pd.DataFrame:
+            If split_shifts is False, returns a single DataFrame of play-by-play data.
+        dict[str, pd.DataFrame]:
+            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
+    """
+    
     pbps = []
     if game_ids[0] == 'random':
         #Randomize selection of game_ids
         #Some ids returned may be invalid (for example, 2020021300)
         num = game_ids[1]
-        try: 
-            start = game_ids[2]
-        except:
-            start = 2007
-        try:
-            end = game_ids[3]
-        except:
-            end = (date.today().year)-1
+        start = game_ids[2] if len(game_ids) > 1 else 2007
+        end = game_ids[3] if len(game_ids) > 2 else (date.today().year)-1
 
         game_ids = []
         i = 0
@@ -161,13 +154,13 @@ def nhl_scrape_game(game_ids,split_shifts = False, remove = ['period-start','per
     error_ids = []
     prog = 0
     for game_id in game_ids:
-        print("Scraping data from game " + str(game_id) + "...",end="")
+        print(f'Scraping data from game {game_id}...',end='')
         start = time.perf_counter()
 
         try:
             #Retrieve data
             info = get_game_info(game_id)
-            data = combine_data(info, sources)
+            data = asyncio.run(combine_data(info, sources))
                 
             #Append data to list
             pbps.append(data)
@@ -186,19 +179,19 @@ def nhl_scrape_game(game_ids,split_shifts = False, remove = ['period-start','per
                 data.to_csv(f'{dirs}{info['game_id']}.csv',index=False)
 
             print(f" finished in {secs:.2f} seconds. {prog}/{len(game_ids)} ({(prog/len(game_ids))*100:.2f}%)")
-        except:
+        except Exception as e:
             #Games such as the all-star game and pre-season games will incur this error
             #Other games have known problems
             if game_id in KNOWN_PROBS.keys():
                 print(f"\nGame {game_id} has a known problem: {KNOWN_PROBS[game_id]}")
             else:
-                print(f"\nUnable to scrape game {game_id}.  Ensure the ID is properly inputted and formatted.")
+                print(f"\nUnable to scrape game {game_id}.  Exception: {e}")
             
             #Track error
             error_ids.append(game_id)
  
     #Add all pbps together
-    if len(pbps) == 0:
+    if not pbps:
         print("\rNo data returned.")
         return pd.DataFrame()
     df = pd.concat(pbps)
@@ -210,7 +203,7 @@ def nhl_scrape_game(game_ids,split_shifts = False, remove = ['period-start','per
         ""
 
     #Print final message
-    if len(error_ids) > 0:
+    if error_ids:
         print(f'\rScrape of provided games finished.\nThe following games failed to scrape: {error_ids}')
     else:
         print('\rScrape of provided games finished.')
@@ -218,7 +211,7 @@ def nhl_scrape_game(game_ids,split_shifts = False, remove = ['period-start','per
     #Split pbp and shift events if necessary
     #Return: complete play-by-play with data removed or split as necessary
     
-    if split_shifts == True:
+    if split_shifts:
         remove.append('change')
         
         #Return: dict with pbp and shifts seperated
@@ -242,22 +235,40 @@ def nhl_scrape_game(game_ids,split_shifts = False, remove = ['period-start','per
         else:
             return pbp
 
-def nhl_scrape_schedule(season,start = "09-01", end = "08-01"):
-    #Given a season, return schedule data
-    # param 'season' - NHL season to scrape
-    # param 'start' - Start date in season
-    # param 'end' - End date in season
+def nhl_scrape_schedule(season:int, start:str = '', end:str = ''):
+    """
+    Given season and an optional date range, retrieve NHL schedule data.
+
+    Args:
+        season (int): 
+            The NHL season formatted such as "20242025".
+        start (str, optional): 
+            The date string (MM-DD) to start the schedule scrape at. Default is a blank string.
+        end (str, optional): 
+            The date string (MM-DD) to end the schedule scrape at. Default is a blank string.
+
+    Returns:
+        pd.DataFrame: 
+            A DataFrame containing the schedule data for the specified season and date range.
+    """
 
     api = "https://api-web.nhle.com/v1/schedule/"
 
-    #Determine how to approach scraping; if month in season is after the new year the year must be adjusted
-    new_year = ["01","02","03","04","05","06"]
-    if start[:2] in new_year:
-        start = str(int(season[:4])+1)+"-"+start
-        end = str(season[:-4])+"-"+end
+    #If either start or end are blank then find start and endpoints for specified season
+    if start == '' or end == '':
+        season_data = rs.get('https://api.nhle.com/stats/rest/en/season').json()['data']
+        season_data = [s for s in season_data if s['id'] == season][0]
+        start = season_data['startDate'][0:10]
+        end = season_data['endDate'][0:10]
     else:
-        start = str(season[:4])+"-"+start
-        end = str(season[:-4])+"-"+end
+        #Determine how to approach scraping; if month in season is after the new year the year must be adjusted
+        new_year = ["01","02","03","04","05","06"]
+        if start[:2] in new_year:
+            start = f'{int(str(season)[:4])+1}-{start}'
+            end = f'{str(season)[:-4]}-{end}'
+        else:
+            start = f'{int(str(season)[:4])}-{start}'
+            end = f'{str(season)[:-4]}-{end}'
 
     form = '%Y-%m-%d'
 
@@ -274,9 +285,9 @@ def nhl_scrape_schedule(season,start = "09-01", end = "08-01"):
     for i in range(day):
         #For each day, call NHL api and retreive info on all games of selected game
         inc = start+timedelta(days=i)
-        print("Scraping games on " + str(inc)[:10]+"...")
+        print(f'Scraping games on {str(inc)[:10]}...')
         
-        get = rs.get(api+str(inc)[:10]).json()
+        get = rs.get(f'{api}{str(inc)[:10]}').json()
         gameWeek = pd.json_normalize(list(pd.json_normalize(get['gameWeek'])['games'])[0])
         
         #Return nothing if there's nothing
@@ -302,43 +313,81 @@ def nhl_scrape_schedule(season,start = "09-01", end = "08-01"):
     #Return: specificed schedule data
     return df
 
-def nhl_scrape_season(season,split_shifts = False, season_types = [2,3], remove = ['period-start','period-end','game-end','challenge','stoppage'], start = "09-01", end = "08-01", local=False, local_path = SCHEDULE_PATH, verbose = False, sources = False, errors = False):
-    #Given season, scrape all play-by-play occuring within the season
-    # param 'season' - NHL season to scrape
-    # param 'split_shifts' - boolean which splits pbp and shift events if true
-    # param 'remove' - list of events to remove from final dataframe
-    # param 'start' - Start date in season
-    # param 'end' - End date in season
-    # param 'local' - boolean indicating whether to use local file to scrape game_ids
-    # param 'local_path' - path of local file
-    # param 'verbose' - boolean which adds additional event info if true
-    # param 'sources - boolean scraping the html and json sources to a master directory if true 
-    # param 'errors' - boolean returning game ids which did not scrape if true
-
+def nhl_scrape_season(season:int, split_shifts:bool = False, season_types:list[int] = [2,3], remove:list[str] = [], start:str = '', end:str = '', local:bool=False, local_path:str = SCHEDULE_PATH, verbose:bool = False, sources:bool = False, errors:bool = False):
+    """
+    Given season, scrape all play-by-play occuring within the season.
+
+    Args:
+        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.
+        season_types (List[int], optional):
+            List of season_types to include in scraping process.  Default is all regular season and playoff games which are 2 and 3 respectfully.
+        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 a blank string.
+        end (str, optional): 
+            The date string (MM-DD) to end the schedule scrape at. Default is a blank string.
+        local (bool, optional):
+            If True, use local file to retreive schedule data.
+        local_path (bool, optional):
+            If True, specifies the path with schedule data necessary to scrape a season's games (only relevant if local = True).
+        verbose (bool, optional):
+            If True, generates extra event features (such as those required to calculate xG). Default is False.
+        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.
+
+    Returns:
+        pd.DataFrame:
+            If split_shifts is False, returns a single DataFrame of play-by-play data.
+        dict[str, pd.DataFrame]:
+            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
+    """
+     
     #Determine whether to use schedule data in repository or to scrape
     if local:
         load = pd.read_csv(local_path)
         load['date'] = pd.to_datetime(load['date'])
-        
-        start = f'{(season[0:4] if int(start[0:2])>=9 else season[4:8])}-{int(start[0:2])}-{int(start[3:5])}'
-        end =  f'{(season[0:4] if int(end[0:2])>=9 else season[4:8])}-{int(end[0:2])}-{int(end[3:5])}'
-        
-        load = load.loc[(load['season'].astype(str)==season)&
+
+        if start == '' or end == '':
+            season_data = rs.get('https://api.nhle.com/stats/rest/en/season').json()['data']
+            season_data = [s for s in season_data if s['id'] == season][0]
+            start = season_data['startDate'][0:10]
+            end = season_data['endDate'][0:10]
+            
+            form = '%Y-%m-%d'
+
+            #Create datetime values from dates
+            start = datetime.strptime(start,form)
+            end = datetime.strptime(end,form)
+
+        else:   
+            start = f'{(str(season)[0:4] if int(start[0:2])>=9 else str(season)[4:8])}-{start[0:2]}-{start[3:5]}'
+            end =  f'{(str(season)[0:4] if int(end[0:2])>=9 else str(season)[4:8])}-{end[0:2]}-{end[3:5]}'
+            
+        load = load.loc[(load['season']==season)&
                         (load['season_type'].isin(season_types))&
                         (load['date']>=start)&(load['date']<=end)]
         
-        game_ids = list(load['id'].astype(str))
+        game_ids = load['id'].to_list()
     else:
         load = nhl_scrape_schedule(season,start,end)
-        load = load.loc[(load['season'].astype(str)==season)&(load['season_type'].isin(season_types))]
-        game_ids = list(load['id'].astype(str))
+        load = load.loc[(load['season']==season)&(load['season_type'].isin(season_types))]
+        game_ids = load['id'].to_list()
 
     #If no games found, terminate the process
     if not game_ids:
         print('No games found for dates in season...')
         return ""
     
-    print(f"Scraping games from {season[0:4]}-{season[4:8]} season...")
+    print(f"Scraping games from {str(season)[0:4]}-{str(season)[4:8]} season...")
     start = time.perf_counter()
 
     #Perform scrape
@@ -354,11 +403,22 @@ def nhl_scrape_season(season,split_shifts = False, season_types = [2,3], remove
     #Return: Complete pbp and shifts data for specified season as well as dataframe of game_ids which failed to return data
     return data
 
-def nhl_scrape_seasons_info(seasons = []):
-    #Returns info related to NHL seasons (by default, all seasons are included)
+def nhl_scrape_seasons_info(seasons:list[int] = []):
+    """
+    Returns info related to NHL seasons (by default, all seasons are included)
+    Args:
+        seasons (List[int], optional): 
+            The NHL season formatted such as "20242025".
+
+    Returns:
+        pd.DataFrame: 
+            A DataFrame containing the information for requested seasons.
+    """
+
+    #
     # param 'season' - list of seasons to include
 
-    print("Scraping info for seasons: " + str(seasons))
+    print(f'Scraping info for seasons: {seasons}')
     api = "https://api.nhle.com/stats/rest/en/season"
     info = "https://api-web.nhle.com/v1/standings-season"
     data = rs.get(api).json()['data']
@@ -374,12 +434,20 @@ def nhl_scrape_seasons_info(seasons = []):
     else:
         return df.sort_values(by=['id'])
 
-def nhl_scrape_standings(arg = "now", season_type = 2):
-    #Returns standings
-    # param 'arg' - by default, this is "now" returning active NHL standings.  May also be a specific date formatted as YYYY-MM-DD, a season (scrapes the last standings date for the season) or a year (for playoffs).
-    # param 'season_type' - by default, this scrapes the regular season standings.  If set to 3, it returns the playoff bracket for the specified season
+def nhl_scrape_standings(arg:str | int = "now", season_type:int = 2):
+    """
+    Returns standings or playoff bracket
+    Args:
+        arg (str or int, optional):
+            Date formatted as 'YYYY-MM-DD' to scrape standings, NHL season such as "20242025", or 'now' for current standings. Default is 'now'.
+        season_type (int, optional):
+            Part of season to scrape.  If 3 (playoffs) then scrape the playoff bracket for the season implied by arg. When arg = 'now' this is ignored. Default is 2.
+
+    Returns:
+        pd.DataFrame: 
+            A DataFrame containing the standings information (or playoff bracket).
+    """
 
-    #arg param is ignored when set to "now" if season_type param is 3
     if season_type == 3:
         if arg == "now":
             arg = NEW
@@ -399,14 +467,28 @@ def nhl_scrape_standings(arg = "now", season_type = 2):
         else:
             print(f"Scraping standings for date: {arg}")
 
-        api = f"https://api-web.nhle.com/v1/standings/{arg[4:8]}-{STANDINGS_END[arg]}"
+        season_data = rs.get('https://api.nhle.com/stats/rest/en/season').json()['data']
+        season_data = [s for s in season_data if s['id'] == arg][0]
+        end = season_data['regularSeasonEndDate'][0:10]
+
+        api = f"https://api-web.nhle.com/v1/standings/{end}"
         data = rs.get(api).json()['standings']
 
         return pd.json_normalize(data)
 
-def nhl_scrape_roster(season):
-    #Given a nhl season, return rosters for all participating teams
-    # param 'season' - NHL season to scrape
+def nhl_scrape_roster(season: int):
+    """
+    Returns rosters for all teams in a given season.
+
+    Args:
+        season (int):
+            The NHL season formatted such as "20242025".
+
+    Returns:
+        pd.DataFrame: 
+            A DataFrame containing the rosters for all teams in the specified season.
+    """
+
     print("Scrpaing rosters for the "+ season + "season...")
     teaminfo = pd.read_csv(info_path)
 
@@ -435,8 +517,18 @@ def nhl_scrape_roster(season):
 
     return pd.concat(rosts)
 
-def nhl_scrape_prospects(team):
-    #Given team abbreviation, retreive current team prospects
+def nhl_scrape_prospects(team:str):
+    """
+    Returns prospects for specified team
+
+    Args:
+        team (str):
+            Three character team abbreviation such as 'BOS'
+
+    Returns:
+        pd.DataFrame: 
+            A DataFrame containing the prospect data for the specified team.
+    """
 
     api = f'https://api-web.nhle.com/v1/prospects/{team}'
 
@@ -452,10 +544,20 @@ def nhl_scrape_prospects(team):
     #Return: team prospects
     return prospects
 
-def nhl_scrape_team_info(country = False):
-    #Given option to return franchise or country, return team information
+def nhl_scrape_team_info(country:bool = False):
+    """
+    Returns team or country information from the NHL API.
+
+    Args:
+        country (bool, optional):
+            If True, returns country information instead of NHL team information.
 
-    print('Scraping team information...')
+    Returns:
+        pd.DataFrame: 
+            A DataFrame containing team or country information from the NHL API.
+    """
+
+    print(f'Scraping {'country' if country else 'team'} information...')
     api = f'https://api.nhle.com/stats/rest/en/{'country' if country else 'team'}'
     
     data =  pd.json_normalize(rs.get(api).json()['data'])
@@ -467,8 +569,19 @@ def nhl_scrape_team_info(country = False):
 
     return data.sort_values(by=(['country3Code','countryCode','iocCode','countryName'] if country else ['fullName','triCode','id']))
 
-def nhl_scrape_player_data(player_ids):
-    #Given player id, return player information
+def nhl_scrape_player_data(player_ids:list[int]):
+    """
+    Returns player data for specified players.
+
+    Args:
+        player_ids (list[int]):
+            List of NHL API player IDs to retrieve information for.
+
+    Returns:
+        pd.DataFrame: 
+            A DataFrame containing player data for specified players.
+    """
+
     infos = []
     for player_id in player_ids:
         player_id = int(player_id)
@@ -489,15 +602,28 @@ def nhl_scrape_player_data(player_ids):
     else:
         return pd.DataFrame()
 
-def nhl_scrape_draft_rankings(arg = 'now', category = ''):
-    #Given url argument for timeframe and prospect category, return draft rankings
-    #Category 1 is North American Skaters
-    #Category 2 is International Skaters
-    #Category 3 is North American Goalie
-    #Category 4 is International Goalie
+def nhl_scrape_draft_rankings(arg:str = 'now', category:int = 0):
+    """
+    Returns draft rankings
+    Args:
+        arg (str, optional):
+            Date formatted as 'YYYY-MM-DD' to scrape draft rankings for specific date or 'now' for current draft rankings. Default is 'now'.
+        category (int, optional):
+            Category number for prospects.  When arg = 'now' this does not apply.
+
+            - Category 1 is North American Skaters.
+            - Category 2 is International Skaters.
+            - Category 3 is North American Goalie.
+            - Category 4 is International Goalie
+
+            Default is 0 (all prospects).
+    Returns:
+        pd.DataFrame: 
+            A DataFrame containing draft rankings.
+    """
 
     #Player category only applies when requesting a specific season
-    api = f"https://api-web.nhle.com/v1/draft/rankings/{arg}/{category}" if category != "" else f"https://api-web.nhle.com/v1/draft/rankings/{arg}"
+    api = f"https://api-web.nhle.com/v1/draft/rankings/{arg}/{category}" if category > 0 else f"https://api-web.nhle.com/v1/draft/rankings/{arg}"
     data = pd.json_normalize(rs.get(api).json()['rankings'])
 
     #Add player name columns
@@ -506,10 +632,16 @@ def nhl_scrape_draft_rankings(arg = 'now', category = ''):
     #Return: prospect rankings
     return data
 
-def nhl_apply_xG(pbp):
-    #Given play-by-play data, return this data with xG-related columns
-
-    #param 'pbp' - play-by-play data
+def nhl_apply_xG(pbp: pd.DataFrame):
+    """
+    Given play-by-play data, return this data with xG-related columns
+    Args:
+        pbp (pd.DataFrame):
+            A DataFrame containing play-by-play data generated within the WBSA Hockey package.
+    Returns:
+        pd.DataFrame: 
+            A DataFrame containing input play-by-play data with xG column.
+    """
 
     print(f'Applying WSBA xG to model with seasons: {pbp['season'].drop_duplicates().to_list()}')
 
@@ -518,7 +650,7 @@ def nhl_apply_xG(pbp):
     
     return pbp
 
-def nhl_shooting_impacts(agg,type):
+def shooting_impacts(agg, type):
     #Given stats table generated from the nhl_calculate_stats function, return table with shot impacts
     #Only 5v5 is supported as of now
 
@@ -868,7 +1000,7 @@ def nhl_shooting_impacts(agg,type):
         #Return: skater stats with shooting impacts
         return df
 
-def nhl_calculate_stats(pbp,type,season_types,game_strength,split_game=False,roster_path=DEFAULT_ROSTER,shot_impact=False):
+def nhl_calculate_stats(pbp:pd.DataFrame, type:Literal['skater','goalie','team'], season_types:list[int], game_strength: Union[Literal['all'], list[str]], split_game:bool = False, roster_path:str = DEFAULT_ROSTER, shot_impact:bool = False):
     #Given play-by-play, seasonal information, game_strength, rosters, and xG model, return aggregated stats
     # param 'pbp' - play-by-play dataframe
     # param 'type' - type of stats to calculate ('skater', 'goalie', or 'team')
@@ -879,6 +1011,33 @@ def nhl_calculate_stats(pbp,type,season_types,game_strength,split_game=False,ros
     # param 'roster_path' - path to roster file
     # param 'shot_impact' - boolean determining if the shot impact model will be applied to the dataset
 
+    """
+    Given play-by-play data, seasonal information, game strength, rosters, and an xG model,
+    return aggregated statistics at the skater, goalie, or team level.
+
+    Args:
+        pbp (pd.DataFrame):
+            A DataFrame containing play-by-play event data.
+        type (Literal['skater', 'goalie', 'team']):
+            Type of statistics to calculate. Must be one of 'skater', 'goalie', or 'team'.
+        season (int): 
+            The NHL season formatted such as "20242025".
+        season_types (List[int], optional):
+            List of season_types to include in scraping process.  Default is all regular season and playoff games which are 2 and 3 respectfully.
+        game_strength (str or list[str]):
+            List of game strength states to include (e.g., ['5v5','5v4','4v5']).
+        split_game (bool, optional):
+            If True, aggregates stats separately for each game; otherwise, stats are aggregated across all games.  Default is False.
+        roster_path (str, optional):
+            File path to the roster data used for mapping players and teams.
+        shot_impact (bool, optional):
+            If True, applies shot impact metrics to the stats DataFrame.  Default is False.
+
+    Returns:
+        pd.DataFrame:
+            A DataFrame containing the aggregated statistics according to the selected parameters.
+    """
+    
     print(f"Calculating statistics for all games in the provided play-by-play data at {game_strength} for {type}s...\nSeasons included: {pbp['season'].drop_duplicates().to_list()}...")
     start = time.perf_counter()
 
@@ -970,7 +1129,7 @@ def nhl_calculate_stats(pbp,type,season_types,game_strength,split_game=False,ros
 
         #Apply shot impacts if necessary
         if shot_impact:
-            complete = nhl_shooting_impacts(complete,'goalie')
+            complete = shooting_impacts(complete,'goalie')
         
         end = time.perf_counter()
         length = end-start
@@ -1014,7 +1173,7 @@ def nhl_calculate_stats(pbp,type,season_types,game_strength,split_game=False,ros
         ]+[f'{stat}/60' for stat in PER_SIXTY[11:len(PER_SIXTY)]]]
         #Apply shot impacts if necessary
         if shot_impact:
-            complete = nhl_shooting_impacts(complete,'team')
+            complete = shooting_impacts(complete,'team')
         
         end = time.perf_counter()
         length = end-start
@@ -1117,7 +1276,7 @@ def nhl_calculate_stats(pbp,type,season_types,game_strength,split_game=False,ros
         
         #Apply shot impacts if necessary (Note: this will remove skaters with fewer than 150 minutes of TOI due to the shot impact TOI rule)
         if shot_impact:
-            complete = nhl_shooting_impacts(complete,'skater')
+            complete = shooting_impacts(complete,'skater')
         
         end = time.perf_counter()
         length = end-start
@@ -1125,16 +1284,34 @@ def nhl_calculate_stats(pbp,type,season_types,game_strength,split_game=False,ros
 
         return complete
 
-def nhl_plot_skaters_shots(pbp,skater_dict,strengths,marker_dict=event_markers,onice = 'indv',title = True,legend=False):
-    #Returns dict of plots for specified skaters
-    # param 'pbp' - pbp to plot data
-    # param 'skater_dict' - skaters to plot shots for (format: {'Patrice Bergeron':['20242025','BOS']})
-    # param 'strengths' - strengths to include in plotting
-    # param 'marker_dict' - dict with markers to use for events
-    # param 'onice' - can set which shots to include in plotting for the specified skater ('indv', 'for', 'against')
-    # param 'title' - bool including title when true
-    # param 'legend' - bool which includes legend if true
-    # param 'xg' - xG model to apply to pbp for plotting
+def nhl_plot_skaters_shots(pbp:pd.DataFrame, skater_dict:dict, strengths:Union[Literal['all'], list[str]], marker_dict:dict = event_markers, onice:Literal['indv','for','against'] = ['indv'], title:bool = True, legend:bool = False):
+    """
+    Return a dictionary of shot plots for the specified skaters.
+
+    Args:
+        pbp (pd.DataFrame):
+            A DataFrame containing play-by-play event data to be visualized.
+        skater_dict (dict[str, list[str]]):
+            Dictionary of skaters to plot, where each key is a player name and the value is a list 
+            with season and team info (e.g., {'Patrice Bergeron': ['20242025', 'BOS']}).
+        strengths (str or list[str]):
+            List of game strength states to include (e.g., ['5v5','5v4','4v5']).
+        marker_dict (dict[str, dict], optional):
+            Dictionary of event types mapped to marker styles used in plotting.
+        onice (Literal['indv', 'for', 'against'], optional):
+            Determines which shot events to include for the player:
+            - 'indv': only the player's own shots,
+            - 'for': shots taken by the player's team while they are on ice,
+            - 'against': shots taken by the opposing team while the player is on ice.
+        title (bool, optional):
+            Whether to include a plot title.
+        legend (bool, optional):
+            Whether to include a legend on the plots.
+
+    Returns:
+        dict[str, matplotlib.figure.Figure]:
+            A dictionary mapping each skater’s name to their corresponding matplotlib shot plot figure.
+    """
 
     print(f'Plotting the following skater shots: {skater_dict}...')
 
@@ -1149,15 +1326,28 @@ def nhl_plot_skaters_shots(pbp,skater_dict,strengths,marker_dict=event_markers,o
     #Return: list of plotted skater shot charts
     return skater_plots
 
-def nhl_plot_games(pbp,events,strengths,game_ids='all',marker_dict=event_markers,team_colors={'away':'primary','home':'primary'},legend=False):
-    #Returns dict of plots for specified games
-    # param 'pbp' - pbp to plot data
-    # param 'events' - type of events to plot
-    # param 'strengths' - strengths to include in plotting
-    # param 'game_ids' - games to plot (list if not set to 'all')
-    # param 'marker_dict' - dict with colors to use for events
-    # param 'legend' - bool which includes legend if true
-    # param 'xg' - xG model to apply to pbp for plotting
+def nhl_plot_games(pbp:pd.DataFrame, events:list[str], strengths:Union[Literal['all'], list[str]], game_ids: Union[Literal['all'], list[int]] = 'all', marker_dict:dict = event_markers, team_colors:dict = {'away':'primary','home':'primary'}, legend:bool =False):
+    """
+    Returns a dictionary of event plots for the specified games.
+
+    Args:
+        pbp (pd.DataFrame):
+            A DataFrame containing play-by-play event data.
+        events (list[str]):
+            List of event types to include in the plot (e.g., ['shot-on-goal', 'goal']).
+        strengths (str or list[str]):
+            List of game strength states to include (e.g., ['5v5','5v4','4v5']).
+        game_ids (str or list[int]):
+            List of game IDs to plot. If set to 'all', plots will be generated for all games in the DataFrame.
+        marker_dict (dict[str, dict]):
+            Dictionary mapping event types to marker styles and/or colors used in plotting.
+        legend (bool):
+            Whether to include a legend on the plots.
+
+    Returns:
+        dict[int, matplotlib.figure.Figure]:
+            A dictionary mapping each game ID to its corresponding matplotlib event plot figure.
+    """
 
     #Find games to scrape
     if game_ids == 'all':

{wsba_hockey-1.1.6.dist-info → wsba_hockey-1.1.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wsba_hockey
-Version: 1.1.6
+Version: 1.1.8
 Summary: WeakSide Breakout's complete Python package of access to hockey data, primairly including the scraping of National Hockey League schedule, play-by-play, and shifts information.
 Author-email: Owen Singh <owenbksingh@gmail.com>
 Project-URL: Homepage, https://github.com/owensingh38/wsba_hockey/

{wsba_hockey-1.1.6.dist-info → wsba_hockey-1.1.8.dist-info}/RECORD

@@ -1,8 +1,8 @@
-wsba_hockey/__init__.py,sha256=yfr8z5PA503iaIQv30ngancwT_WnsuK-tZETKlHcI0M,377
+wsba_hockey/__init__.py,sha256=qye0rq22KeaUzBPH__pqjBA_igwsmHemOAbaY_G2tNY,356
 wsba_hockey/data_pipelines.py,sha256=SITapG3nbea6-_EsXujMW2JBQxtRaQ33XMcE6ohn2Ko,10853
-wsba_hockey/workspace.py,sha256=MwuyqyLW0dHNa06WEm60RkvbFoCn8LBXhnki66V-ttY,954
-wsba_hockey/wsba_main.py,sha256=Ucies8d27gWtzf8xprnu7hEcqGGHvOza8HCE0O80X-s,54031
-wsba_hockey/api/api/index.py,sha256=tABWg5cYCY-fPaNJ6W_bMJKEYrjn93YGy84VlkHzIXA,6853
+wsba_hockey/workspace.py,sha256=DrOm6DYPEmk9FEzAxpFgn_8zd0wNTca7muED0eDMdlc,968
+wsba_hockey/wsba_main.py,sha256=7RJtcpqsAuSWEtxs1CgZXkfZU3GR1MJc0_HG_S7gb08,61959
+wsba_hockey/api/api/index.py,sha256=r2keq105Ve8V0JAsSZMIPs9geVHX2Fuxyi4MqnzCt48,6537
 wsba_hockey/evidence/weakside-breakout/node_modules/duckdb/vendor.py,sha256=lmu0TB0rIYkAuV9-csFJgW-1hJojso_-EZpEoorUUKM,4949
 wsba_hockey/evidence/weakside-breakout/node_modules/flatted/python/flatted.py,sha256=ke8FuEflns-WlphCcQ9CC0qJqWqX3zEEuak74o6rgE8,3879
 wsba_hockey/evidence/weakside-breakout/node_modules/flatted/python/test.py,sha256=uTOn6HJd7KeY_PTRvvufv60dmvON3KWp3nnqACj8IlA,2129
@@ -134,15 +134,15 @@ wsba_hockey/flask/app.py,sha256=J51iA65h9xyJfLgdH0h2sVSbfIR7xgGd2Oy8bJsmpAk,1873
 wsba_hockey/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wsba_hockey/tools/agg.py,sha256=OkIYd-ApvGVYe2JJLOI21jnDIN5LH8nkeH7eo0reWFI,23364
 wsba_hockey/tools/plotting.py,sha256=81hBaM7tcwUNB4-tovPn7QreOUz6B2NuI_SR4-djVSk,6029
-wsba_hockey/tools/scraping.py,sha256=h6C016U0qmNQpHWMh7Xvn3ud57zKzRbRQ06Odl-rC_I,52573
+wsba_hockey/tools/scraping.py,sha256=-sv29886AWAMhhpJ14282WTolBZni8eXBvj4OtNVY-U,52863
 wsba_hockey/tools/xg_model.py,sha256=nOr_2RBijLgPmJ0TTs4wbSsORYmRqWCKRjLKDm7sAhI,18342
 wsba_hockey/tools/archive/old_scraping.py,sha256=hEjMI1RtfeZnf0RBiJFI38oXkLZ3WofeH5xqcF4pzgM,49585
 wsba_hockey/tools/utils/__init__.py,sha256=vccXhOtzARoR99fmEWU1OEI3qCIdQ9Z42AlRA_BUhrs,114
 wsba_hockey/tools/utils/config.py,sha256=D3Uk05-YTyrhfReMTTLfNI3HN_rON2uo_CDE9oER3Lg,351
 wsba_hockey/tools/utils/save_pages.py,sha256=CsyL_0n-b-4pJoUauwU3HpnCO6n69-RlBMJQBd_qGDc,4979
 wsba_hockey/tools/utils/shared.py,sha256=dH_JwZfia5fib8rksy5sW-mBp0pluBPvw37Vdr8Kap0,14211
-wsba_hockey-1.1.6.dist-info/licenses/LICENSE,sha256=Nr_Um1Pd5FQJTWWgm7maZArdtYMbDhzXYSwyJIZDGik,1114
-wsba_hockey-1.1.6.dist-info/METADATA,sha256=2CLs8qTA1iS8P7ToF4My86KkMRrt5zYoX9ynbQTS4zk,3566
-wsba_hockey-1.1.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-wsba_hockey-1.1.6.dist-info/top_level.txt,sha256=acU7s3x-RZC1zGiqCOmO0g267iqCg34lzIfdmYxxGmQ,12
-wsba_hockey-1.1.6.dist-info/RECORD,,
+wsba_hockey-1.1.8.dist-info/licenses/LICENSE,sha256=Nr_Um1Pd5FQJTWWgm7maZArdtYMbDhzXYSwyJIZDGik,1114
+wsba_hockey-1.1.8.dist-info/METADATA,sha256=qacIIM92WbKqxYPI96wimlHYw2NLxCMZkmwTQHnO-5M,3566
+wsba_hockey-1.1.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+wsba_hockey-1.1.8.dist-info/top_level.txt,sha256=acU7s3x-RZC1zGiqCOmO0g267iqCg34lzIfdmYxxGmQ,12
+wsba_hockey-1.1.8.dist-info/RECORD,,