Team Stats Module

The team_stats module provides utilities for accessing, analyzing, and visualizing college baseball team statistics across years and NCAA divisions.

Overview

This module allows users to:

  • Retrieve team statistics from cached JSON files.

  • Aggregate statistics for a team over multiple years.

  • Visualize trends in team performance using line plots.

Functions

get_team_stat(stat_name: str, team_name: str, year: int, division: int) → float | int | None

Retrieves a specific statistic for a given team from the cached data.

Parameters:

  • stat_name – Key of the statistic to retrieve.

  • team_name – Name of the team.

  • year – Year of the data.

  • division – NCAA division number.

Returns:

The value of the requested statistic, or None if not found.

display_specific_team_stat(stat_name: str, search_team: str, year: int, division: int) → None

Prints a specific statistic for a team in a readable format.

Parameters:

  • stat_name – Key of the statistic to display.

  • search_team – Name of the team.

  • year – Year of the data.

  • division – NCAA division number.

Returns:

None. Prints the result to the console.

display_team_stats(search_team: str, year: int, division: int) → None

Displays all available statistics for a team for a given year and division.

Parameters:

  • search_team – Name of the team.

  • year – Year of the data.

  • division – NCAA division number.

Returns:

None. Prints all stats for the team.

list_all_teams(year: int, division: int) → list[str]

Returns a list of all team names for a given year and division.

Parameters:

  • year – Year of the data.

  • division – NCAA division number.

Returns:

List of team names (str).

Functions that calculate

average_all_team_stats(year: int, division: int) → dict

Computes the average of all numeric values for each statistic across all teams.

Parameters:

  • year – Year of the data.

  • division – NCAA division number.

Returns:

Dictionary mapping stat names to their average values.

average_team_stat_str(stat_name: str, year: int, division: int) → str

Returns a string representing the average value of a given statistic across all teams for the specified year and division.

Parameters:

  • stat_name – Key of the statistic to average.

  • year – Year of the data.

  • division – NCAA division number.

Returns:

Average value (str) of the specified statistic.

average_team_stat_float(stat_name: str, year: int, division: int) → float | None

Computes the mean of the specified statistic, if available

Parameters:

  • stat_name – Key of the statistic to average.

  • year – Year of the data.

  • division – NCAA division number.

Returns:

Average value (float) of the specified statistic.

get_pythagorean_expectation(team_name: str, year: int, division: int) → float | str

Computes Pythagorean expected win percentage.

Parameters:

  • team_name – Name of the team.

  • year – Year of data.

  • division – NCAA division number.

Returns:

A float that represents expected win percentage.

compare_pythagorean_expectation(team_name: str, year: int, division: int) → str

Computes Pythagorean expected win percentage and compares it with the actual win percentage.

Parameters:

  • team_name – Name of the team.

  • year – Year of data.

  • division – NCAA division number.

Returns:

A string summary with expected and actual win percentages.

plot_team_stat_over_years(stat_name: str, team_name: str, division: int, start_year: int, end_year: int)

Plots the values of a specified statistic for a given team across a range of years in a specific NCAA division.

Parameters:

  • stat_name – Key of the statistic to plot.

  • team_name – Name of the team.

  • division – NCAA division number.

  • start_year – First year in the range.

  • end_year – Last year in the range.

Returns:

None. Displays a matplotlib plot if data is found.

Usage Example

from ncaa_bbStats import plot_team_stat_over_years

# Plot home runs for Northeastern in Division 1 from 2010 to 2024
plot_team_stat_over_years("home_runs", "Northeastern", 1, 2010, 2024)

Data Source

Team statistics are loaded from cached JSON files located in:

src/data/team_stats_cache/divX/YYYY.json

where X is the division number and YYYY is the year.

See Also