{"id":47122541,"url":"https://github.com/timothyf/baseball-data-lab","last_synced_at":"2026-03-12T19:32:48.444Z","repository":{"id":258096787,"uuid":"866057574","full_name":"timothyf/baseball-data-lab","owner":"timothyf","description":"A Python application and library that generates comprehensive advanced stat summary sheets for MLB players, customizable by year, providing in-depth analysis and visualizations. It can also be used as a library module, enabling users to develop their own features and extend functionality for custom applications and data processing needs.","archived":false,"fork":false,"pushed_at":"2025-09-09T18:47:53.000Z","size":81918,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-09T22:06:06.669Z","etag":null,"topics":["analytics","baseball","baseball-analytics","baseball-data","baseball-statistics","mlb","python","sabermetrics","statcast"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/timothyf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-01T15:18:14.000Z","updated_at":"2025-09-09T18:47:56.000Z","dependencies_parsed_at":"2024-10-26T00:30:43.329Z","dependency_job_id":"5abfb7dd-49b1-4789-91c7-68a8a15774ba","html_url":"https://github.com/timothyf/baseball-data-lab","commit_stats":null,"previous_names":["timothyf/mlb_stats","timothyf/mlb-data-lab","timothyf/baseball-data-lab"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/timothyf/baseball-data-lab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timothyf%2Fbaseball-data-lab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timothyf%2Fbaseball-data-lab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timothyf%2Fbaseball-data-lab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timothyf%2Fbaseball-data-lab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timothyf","download_url":"https://codeload.github.com/timothyf/baseball-data-lab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timothyf%2Fbaseball-data-lab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30439899,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T14:34:45.044Z","status":"ssl_error","status_checked_at":"2026-03-12T14:09:33.793Z","response_time":114,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","baseball","baseball-analytics","baseball-data","baseball-statistics","mlb","python","sabermetrics","statcast"],"created_at":"2026-03-12T19:32:47.085Z","updated_at":"2026-03-12T19:32:48.410Z","avatar_url":"https://github.com/timothyf.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Baseball Data Lab\n`baseball-data-lab` is a Python application and library for creating advanced stat\nsummary sheets for MLB players. It supports yearly customizations and provides\nvisualizations. The project can also be imported as a library so you can extend\nits functionality for custom applications or data processing workflows. It uses\nthe [`pybaseball`](https://github.com/jldbc/pybaseball) and\n[`MLB-StatsAPI`](https://github.com/toddrob99/MLB-StatsAPI) libraries along with\nother Python packages to gather and format data for dashboards, reports and\nother analytical tools.\n\nThe project retrieves data from MLB and FanGraphs to ensure accurate,\nup‑to‑date statistics. Future releases will continue to expand the\napplication's capabilities so it can serve as both a standalone tool and a\nreusable library.\n\n\n## Sample Summary Sheets\nBelow are samples of the summary sheets that can be generated by this project. The first sample is a Batting Summary for Riley Greene for the 2024 season. The second sample is a Pitching Summary for Tarik Skubal for the 2024 season.\n\n\u003cdiv id=\"user-content-toc\"\u003e\n  \u003csummary\u003e\n\u003ch1 align=\"center\" style=\"padding:100px\"\u003e\n\u003cimg src=\"docs/images/batter_summary_riley_greene.png?sanitize=true\" alt=\"Riley Greene Batter Sheet\" width=\"300\" /\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n\u003cimg src=\"docs/images/pitcher_summary_tarik_skubal.png?sanitize=true\" alt=\"Tarik Skubal Pitcher Sheet\" width=\"300\"/\u003e\n\u003c/h1\u003e\n  \u003c/summary\u003e\n\nIn addition to the baseball stats you would expect, the summary sheets also include the following \"advanced\" stats:\n\u003ctable\u003e\n\u003cthead\u003e\n  \u003cth colspan=2\u003eBatters\u003c/th\u003e\n  \u003cth\u003e\u003c/th\u003e\n  \u003cth colspan=3\u003ePitchers\u003c/th\u003e\n\u003c/thead\u003e\n\u003ctr\u003e\n  \u003ctd class=\"batter-col\"\u003eBB%\u003c/td\u003e\n  \u003ctd class=\"batter-col\"\u003eUBR\u003c/td\u003e\n  \u003ctd\u003e\u0026nbsp;\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eK/9\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eOpponent Avg\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eSwing %\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd class=\"batter-col\"\u003eK%\u003c/td\u003e\n  \u003ctd class=\"batter-col\"\u003ewRC\u003c/td\u003e\n  \u003ctd\u003e\u0026nbsp;\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eBB/9\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eWHIP\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eSplits\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd class=\"batter-col\"\u003eOBP\u003c/td\u003e\n  \u003ctd class=\"batter-col\"\u003ewRAA\u003c/td\u003e\n  \u003ctd\u003e\u0026nbsp;\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eK/BB\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eBABIP\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd class=\"batter-col\"\u003eSLG\u003c/td\u003e\n  \u003ctd class=\"batter-col\"\u003ewOBA\u003c/td\u003e\n  \u003ctd\u003e\u0026nbsp;\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eH/9\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eLOB%\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd class=\"batter-col\"\u003eOPS\u003c/td\u003e\n  \u003ctd class=\"batter-col\"\u003ewRC+\u003c/td\u003e\n  \u003ctd\u003e\u0026nbsp;\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eHR/9\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eERA-\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd class=\"batter-col\"\u003eISO\u003c/td\u003e\n  \u003ctd class=\"batter-col\"\u003eWAR\u003c/td\u003e\n  \u003ctd\u003e\u0026nbsp;\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eK%\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eFIP-\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd class=\"batter-col\"\u003eSpd\u003c/td\u003e\n  \u003ctd class=\"batter-col\"\u003eSplits\u003c/td\u003e\n  \u003ctd\u003e\u0026nbsp;\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eBB%\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eFIP\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd class=\"batter-col\"\u003eBABIP\u003c/td\u003e\n  \u003ctd class=\"batter-col\"\u003e\u0026nbsp;\u003c/td\u003e\n  \u003ctd\u003e\u0026nbsp;\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eK-BB%\u003c/td\u003e\n  \u003ctd class=\"pitcher-col\"\u003eRS/9\u003c/td\u003e\n\u003c/tr\u003e\n\n  \n\u003c/table\u003e\n\n\n\u003c/div\u003e\n\n## Project Structure\n\nThe project is organized as follows:\n\n```text\nbaseball-data-lab/\n├── README.md\n├── setup.py\n├── requirements.txt\n├── baseball_data_lab/        # Source code\n│   ├── apis/            # API clients for MLB and FanGraphs\n│   ├── data_viz/        # Plotting utilities\n│   ├── player/          # Player models and helpers\n│   ├── summary_sheets/  # Classes that generate summary sheets\n│   ├── team/            # Team utilities\n│   └── ...\n├── examples/           # Example scripts for data collection\n└── tests/               # Unit tests\n```\n  \n\n## Installation\n\n\nTo get started with the project, follow these steps:\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/timothyf/baseball-data-lab.git\ncd baseball-data-lab\n```\n\n2. Set up a Python virtual environment (optional but recommended):\n```bash\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n3. Install the required dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\n## Usage\n\n#### Generating Player Summary Sheets\nThere are several scripts in the `examples` directory for some basic functionality:\n```bash\npython examples/generate_player_summary.py [options]\n\nOptions:\n    --players [1 or more player names]\n    --teams [1 or more team names]\n    --year [specify a 4-digit year]\n```\n\n#### Saving Statcast Data\nRun the project by executing the script in the `examples` directory:\n```bash\npython examples/save_statcast_data.py [options]\n\n    --players [1 or more player names]\n    --teams [1 or more team names]\n    --year [specify a 4-digit year]\n```\n\n## Examples\n#### Generate a player sheet for Riley Greene\n```bash\npython examples/generate_player_summary.py --players 'Riley Greene'\n```\nOutput:\u003cbr/\u003e\n`output/2024/Tigers/batter_summary_riley_greene.png`\u003cbr/\u003e\u003cbr/\u003e\n\u003cimg src=\"docs/images/batter_summary_riley_greene.png?sanitize=true\" alt=\"Riley Greene Batter Sheet\" width=\"300\" /\u003e\n\n#### Generate player sheets for all of the 2024 Detroit Tigers\n```bash\npython examples/generate_player_summary.py --teams 'Detroit Tigers' --year 2024\n```\n\n\u003cbr/\u003e\n\n## Database Setup\n\nTo set up the PostgreSQL database for Baseball Data Lab, follow these steps:\n\n1. **Install PostgreSQL:**  \n   Download and install PostgreSQL from [postgresql.org](https://www.postgresql.org/download/).\n\n2. **Create the Database:**\n   Open your terminal and run:\n   ```bash\n   createdb baseball_data_lab_db\n   ```\n3. **Initialize the Schema:**\n   Run the provided `setup_db.sql` file to create the tables:\n   ```bash\n   psql -d baseball_data_lab_db -f setup_db.sql\n   ```\n4. **Verify the Setup:**\n   Connect to your database and list the tables:\n   ```bash\n   psql -d baseball_data_lab_db\n   \\dt\n   ```\n   You should see tables such as `games`, `players`, `umpires` and `plate_appearances`.\n\n\n## Inspiration\n\nThis project was inspired by my time working in the R\u0026D department of the Washington Nationals, and the pitching summary project from Thomas Nestico. Here is a link to an article describing his project:\n\nhttps://medium.com/@thomasjamesnestico/creating-the-perfect-pitching-summary-7b8a981ef0c5\n\n\n## Copyright Notice\n\nThis package and its author are not affiliated with MLB or any MLB team. This API wrapper interfaces with MLB's Stats API. Use of MLB data is subject to the notice posted at http://gdx.mlb.com/components/copyright.txt.\n\n\n\u003cstyle\u003e\ntable td.batter-col {\n    background-color: lightblue;\n    color: black;\n}\ntable td.pitcher-col {\n    background-color: lightgreen;\n    color: black;\n}\n\u003c/style\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimothyf%2Fbaseball-data-lab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimothyf%2Fbaseball-data-lab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimothyf%2Fbaseball-data-lab/lists"}