{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Usage Guide: Analyzing Volleyball Data" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Overview\n", "\n", "This guide details how to use `pyvolleydata` to access clean, standardized data from Major League Volleyball (MLV), League One Volleyball (LOVB), and Athlete Unlimited Pro Volleyball (AUPVB)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Installation\n", "\n", "You can install the `pyvolleydata` package with:\n", "\n", "```bash\n", "$ pip install pyvolleydata\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Getting Started\n", "\n", "To use `pyvolleydata` in a project, start by importing the package:" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "1.0.0\n" ] } ], "source": [ "import pyvolleydata\n", "print(pyvolleydata.__version__)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Accessing League Data\n", "\n", "All loading functions in `pyvolleydata` require two arguments:\n", "\n", "* **`league`**: One of `'mlv'`, `'lovb'`, or `'au'`.\n", "* **`seasons`**: The year of the season (e.g., `2025`)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Schedule\n", "`load_schedule(league, seasons)`" ] }, { "cell_type": "code", "execution_count": 15, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " season date home_team away_team ... result match_id phase league\n", "0 2025 2025-01-08 Atlanta Salt Lake ... 1:3 2161068 Week 1 lovb\n", "1 2025 2025-01-09 Houston Austin ... 3:2 2161288 Week 1 lovb\n", "2 2025 2025-01-10 Austin Madison ... 3:0 2161289 Week 1 lovb\n", "3 2025 2025-01-10 Houston Nebraska ... 0:3 2161290 Week 1 lovb\n", "4 2025 2025-01-15 Austin Atlanta ... 1:3 2161291 Week 2 lovb\n", "\n", "[5 rows x 10 columns]\n" ] } ], "source": [ "from pyvolleydata.get_data import load_schedule\n", "\n", "# Get the lovb schedule for 2025\n", "schedule = load_schedule('lovb', 2025)\n", "print(schedule.head())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Officials\n", "`load_mlv_officials(league, seasons)`" ] }, { "cell_type": "code", "execution_count": 16, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " match_id season match_datetime ... last_name level league\n", "0 2125268 2024 2024-01-26T00:00:00.000Z ... Prater USA mlv\n", "1 2125268 2024 2024-01-26T00:00:00.000Z ... McLarty USA mlv\n", "2 2125268 2024 2024-01-26T00:00:00.000Z ... Chen USA mlv\n", "3 2125268 2024 2024-01-26T00:00:00.000Z ... TerMolen USA mlv\n", "4 2125270 2024 2024-02-02T00:00:00.000Z ... Prater AA mlv\n", "\n", "[5 rows x 9 columns]\n" ] } ], "source": [ "from pyvolleydata.get_data import load_officials\n", "\n", "# Get the mlv official data for all seasons\n", "officials = load_officials('mlv')\n", "print(officials.head())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Player Information\n", "`load_player_info(league, seasons)`" ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " match_id season ... team_color league\n", "2279 2249759 2025 ... cadmiumOrange au\n", "2280 2249759 2025 ... cadmiumOrange au\n", "2281 2249759 2025 ... cadmiumOrange au\n", "2282 2249759 2025 ... cadmiumOrange au\n", "2283 2249759 2025 ... cadmiumOrange au\n", "\n", "[5 rows x 29 columns]\n" ] } ], "source": [ "from pyvolleydata.get_data import load_player_info\n", "\n", "# Get the au player-info data for 2025\n", "player_info = load_player_info('au', 2025)\n", "print(player_info.head())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Team Staff\n", "`load_team_staff(league, seasons)`" ] }, { "cell_type": "code", "execution_count": 18, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " match_id season match_datetime ... first_name last_name league\n", "0 2125268 2024 2024-01-26T00:00:00.000Z ... Cathy George mlv\n", "1 2125268 2024 2024-01-26T00:00:00.000Z ... Bill Walton mlv\n", "2 2125268 2024 2024-01-26T00:00:00.000Z ... Denis Dimitrov mlv\n", "3 2125268 2024 2024-01-26T00:00:00.000Z ... Angel Perez mlv\n", "4 2125268 2024 2024-01-26T00:00:00.000Z ... Carlos Cardona mlv\n", "\n", "[5 rows x 9 columns]\n" ] } ], "source": [ "from pyvolleydata.get_data import load_team_staff\n", "\n", "# Get the mlv team-staff data for 2024 and 2025\n", "team_staff = load_team_staff('mlv', [2024, 2025])\n", "print(team_staff.head())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Play-by-Play\n", "`load_pbp(league, seasons)`" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " match_id season match_datetime ... home_score away_score league\n", "0 2161068 2025 2025-01-09T00:30:00.000Z ... 1 0 lovb\n", "1 2161068 2025 2025-01-09T00:30:00.000Z ... 1 0 lovb\n", "2 2161068 2025 2025-01-09T00:30:00.000Z ... 1 0 lovb\n", "3 2161068 2025 2025-01-09T00:30:00.000Z ... 1 0 lovb\n", "4 2161068 2025 2025-01-09T00:30:00.000Z ... 1 0 lovb\n", "\n", "[5 rows x 15 columns]\n" ] } ], "source": [ "from pyvolleydata.get_data import load_pbp\n", "\n", "# Get the lovb pbp data for all seasons\n", "pbp = load_pbp('lovb')\n", "print(pbp.head())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Events Log\n", "`load_events_log(league, seasons)`" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " match_id season ... verified_method league\n", "0 2249759 2025 ... NaN au\n", "1 2249759 2025 ... NaN au\n", "2 2249759 2025 ... NaN au\n", "3 2249759 2025 ... NaN au\n", "4 2249759 2025 ... NaN au\n", "\n", "[5 rows x 45 columns]\n" ] } ], "source": [ "from pyvolleydata.get_data import load_events_log\n", "\n", "# Get the au events log data for 2025\n", "events_log = load_events_log('au', 2025)\n", "print(events_log.head())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Player Boxscore\n", "`load_player_boxscore(league, seasons`)" ] }, { "cell_type": "code", "execution_count": 27, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " match_id season match_datetime ... spike_hp points league\n", "6881 2160916 2025 2025-01-10T00:00:00.000Z ... 1.0 0.0 mlv\n", "6882 2160916 2025 2025-01-10T00:00:00.000Z ... 0.0 0.0 mlv\n", "6883 2160916 2025 2025-01-10T00:00:00.000Z ... 0.0 2.0 mlv\n", "6884 2160916 2025 2025-01-10T00:00:00.000Z ... NaN NaN mlv\n", "6885 2160916 2025 2025-01-10T00:00:00.000Z ... NaN NaN mlv\n", "\n", "[5 rows x 37 columns]\n" ] } ], "source": [ "from pyvolleydata.get_data import load_player_boxscore\n", "\n", "# Get the mlv player-boxscore data for 2025\n", "player_boxscore = load_player_boxscore('mlv', 2025)\n", "print(player_boxscore.head())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Team Boxscore\n", "`load_team_boxscore(league, seasons)`" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " match_id season match_datetime ... spike_hp points league\n", "0 2161068 2025 2025-01-09T00:30:00.000Z ... 1 6 lovb\n", "1 2161068 2025 2025-01-09T00:30:00.000Z ... 1 6 lovb\n", "2 2161068 2025 2025-01-09T00:30:00.000Z ... 3 10 lovb\n", "3 2161068 2025 2025-01-09T00:30:00.000Z ... 2 4 lovb\n", "4 2161068 2025 2025-01-09T00:30:00.000Z ... 0 6 lovb\n", "\n", "[5 rows x 29 columns]\n" ] } ], "source": [ "from pyvolleydata.get_data import load_team_boxscore\n", "\n", "# Get the lovb team-boxscore data for 2025\n", "team_boxscore = load_team_boxscore('lovb', 2025)\n", "print(team_boxscore.head())" ] } ], "metadata": { "kernelspec": { "display_name": ".venv", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.14.2" } }, "nbformat": 4, "nbformat_minor": 4 }