CUNYsports (0.1.1) is an R package for accessing and
exploring collegiate athletics data from the City University of
New York (CUNY).
The package provides a simple interface for retrieving sports data from an included SQLite database. The database contains information about teams, players, games, seasons, schools, opponents, and other aspects of CUNY athletics.
Currently, only basketball-related data are available. Work is underway to expand coverage to additional sports.
The project is part of the CUNY Sports Analytics Initiative at The Open Data Lab.
CUNY athletics data are publicly available across individual college athletics websites. However, the information is distributed across sources and is not always easy to access or combine.
CUNYsports provides a centralized and reproducible way
to work with these data in R.
The package includes:
The package supports sports analytics, student research, dashboards, scouting reports, data visualization, teaching, and other analyses of CUNY athletics.
The current release focuses on CUNY men’s and women’s basketball.
Basketball data include:
The project is designed to expand to additional CUNY sports over time.
Install the CRAN release with:
install.packages("CUNYsports")Or install the development version from GitHub:
devtools::install_github("nyc-open-data-lab/CUNYsports")Then load the package:
library(CUNYsports)CUNYsports provides a small set of functions for
exploring and accessing the database.
Use cuny_table_names() to see the tables available in
the installed database.
cuny_table_names()If you know what kind of data you want but not the exact table name,
use cuny_find_tables().
cuny_find_tables("basketball")
cuny_find_tables("player")
cuny_find_tables("game")
cuny_find_tables("scoring")The function searches the package’s table catalog and returns tables whose metadata match the search term.
Use cuny_table_info() to view table-level
documentation.
cuny_table_info("basketball_player_season_stats")Table metadata include descriptions, data grain, season coverage, sources, candidate keys and relationships, likely analytical uses, and notes.
Use cuny_columns_info() to view documentation for
variables within a table.
cuny_columns_info("basketball_game_by_game_combined")The column catalog describes variable names, suggested names, data types, example values, key roles, and notes.
Use cuny_pull_table() to retrieve a complete database
table as an R data frame.
player_stats <- cuny_pull_table("basketball_player_season_stats")Then use standard R tools:
library(dplyr)
player_stats |>
filter(gender == "W")For men’s basketball:
player_stats |>
filter(gender == "M")Three additional tables make common analyses easier and document important cleaning decisions.
| Table | What it contains | Good starting point for |
|---|---|---|
basketball_player_season_stats |
Consolidated player-season records, including overall statistics, conference statistics, and career-high fields | Player comparisons, development, leaderboards, and scouting |
basketball_game_by_game_combined |
One record per scraped school-game perspective, with team and opponent statistics in the same row | Matchup analysis, game trends, dashboards, and retrospective performance analysis |
basketball_player_records_removed |
Player records excluded by the cleaning process, with source and removal metadata | Auditing, troubleshooting, and data-quality review |
These tables complement rather than replace the more detailed source-oriented tables in the database.
basketball_player_season_stats brings together
player-season statistics and related conference and career-high
information, reducing the need to combine multiple player tables
manually.
library(CUNYsports)
library(dplyr)
players <- cuny_pull_table("basketball_player_season_stats")
players |>
select(
player_name,
season_label,
school,
gender,
games_played,
points_per_game,
rebounds_per_game,
assists
) |>
arrange(desc(points_per_game))The table also includes identifiers such as player_id,
school_id, and season_id, plus
conference-specific statistics and career-high fields. Check the column
documentation for field definitions and availability.
basketball_game_by_game_combined places team and
opponent box-score statistics side by side, so users can compare both
performances without joining the separate game tables themselves.
games <- cuny_pull_table("basketball_game_by_game_combined")
games |>
select(
school,
opponent_name,
season_label,
game_date,
result,
point_differential,
total_rebounds,
opponent_total_rebounds,
outrebounded_opponent
)The table includes derived indicators such as:
is_close_game: absolute point differential of five
points or feweris_blowout: absolute point differential of at least 20
pointsoutrebounded_opponent: the scraped team had more
rebounds than its opponentoutshot_opponent: the scraped team had a higher field
goal percentagefewer_turnovers: the scraped team committed fewer
turnovers than its opponentModeling note: These indicators describe completed games. They should not be used as same-game predictors of wins or losses because doing so would introduce information from after the game into the model. For prospective predictions, construct features using only information available before tipoff.
basketball_player_records_removed preserves information
about player records excluded during cleaning.
removed_records <- cuny_pull_table("basketball_player_records_removed")
removed_records |>
count(removal_reason, sort = TRUE)Fields such as source_table, source_row_id,
removal_reason, duplicate_count, and
record_rank help users inspect and understand cleaning
decisions. This is an audit table, not the recommended source for
ordinary player analysis.
A typical CUNYsports workflow looks like this:
library(CUNYsports)
library(dplyr)
# Discover available datasets
cuny_table_names()
cuny_find_tables("player")
# Read the documentation
cuny_table_info("basketball_player_season_stats")
cuny_columns_info("basketball_player_season_stats")
# Retrieve an analysis-ready dataset
players <- cuny_pull_table("basketball_player_season_stats")
# Begin analysis
players |>
filter(gender == "W") |>
arrange(desc(points_per_game))The workflow follows four steps:
flowchart LR
A["Discover"] --> B["Understand"] --> C["Retrieve"] --> D["Analyze"]
A --- A1["cuny_table_names() / cuny_find_tables()"]
B --- B1["cuny_table_info() / cuny_columns_info()"]
C --- C1["cuny_pull_table()"]
D --- D1["Your analysis"]
CUNYsports stores its athletics data in an included
SQLite database. The database contains analytical tables and reusable
dimension tables.
The database contains both detailed source-oriented tables and consolidated analysis-ready tables covering:
Men’s and women’s basketball records are stored together in
applicable tables and can be distinguished using the gender
variable.
Shared dimensions provide standardized identifiers and attributes:
dim_seasonsdim_schoolsdim_playersdim_gamesdim_opponentsdim_player_yearThese dimensions support consistent joins and longitudinal analysis
across the database. In the combined game table, school_id
and game_id identify the school-specific game perspective
and are the recommended candidate composite key, subject to uniqueness
validation.
Advanced users can access the SQLite database directly with
cuny_db().
con <- cuny_db()
DBI::dbListTables(con)The connection can also be used with database-backed workflows:
dplyr::tbl(con, "basketball_game_by_game_combined")When finished, disconnect:
DBI::dbDisconnect(con)For most users, cuny_pull_table() provides the simplest
way to retrieve data.
| Function | Purpose |
|---|---|
cuny_table_names() |
View all available database tables |
cuny_find_tables() |
Search for tables using catalog metadata |
cuny_table_info() |
View documentation for a table |
cuny_columns_info() |
View documentation for columns in a table |
cuny_pull_table() |
Retrieve a complete table into R |
cuny_db() |
Open a direct connection to the SQLite database |
Two catalogs are included with the package:
table_catalogContains table-level metadata describing the structure, coverage, relationships, and potential uses of each database table.
column_catalogContains column-level metadata describing each variable’s meaning, suggested name, data type, example values, and database role.
The helper functions cuny_table_info() and
cuny_columns_info() provide convenient access to these
catalogs. The three consolidated and audit tables are documented
alongside the existing tables.
The underlying data are derived from publicly available CUNY athletics websites. The data engineering pipeline collects and standardizes information across institutions and seasons before constructing relational tables for distribution through the package.
Recent pipeline improvements include:
Because source websites and historical records can vary, users should consult the documentation and validate completeness for their specific research question.
CUNYsports is part of the CUNY Sports Analytics
Initiative, a project of The Open Data Lab focused on building
open data infrastructure for CUNY athletics.
The broader initiative supports:
The goal is not simply to collect athletics data, but to make them easier for students, researchers, coaches, fans, and the broader CUNY community to explore and use.
Planned areas of development include:
CUNYsports is developed as part of The
Open Data Lab, an open-source initiative focused on making public
and institutional data easier to access, analyze, and use.
The package is developed and maintained by Christian Martinez with contributions from students and collaborators working on the CUNY Sports Analytics Initiative.
CUNYsports is released under the MIT License.