nfelo DCM

nfelo DCM is an abstraction layer for loading and caching NFL related CSVs stored on the web. DCM stands for Dataframe-CSV Mapping. The goal of the DCM is to get pandas dataframes of fresh data loaded in a way that balances simplicity, efficiency, and performance.

import nfelodcm

## Load 2 dataframes
db = nfelodcm.load(['pbp', 'games'])

## access the PBP dataframe
db['pbp']

Maps

Maps are config files that tell the DCM where data CSVs are located, how they should be retrieved, and what fields to pull. Each CSV has its own config in Maps/{table}.json, where parameters can be set for things like freshness SLAs, CSV parsing engines, iteration strategy, and assignments (mutations).

An important characteristic of these maps is that all fields must be 1) specified in the map and 2) typed. Fields not listed in the map will not be loaded. Untyped fields will throw an error.

Here is a sample config:

{
  "name": "games",
  "description": "nflgamedata games",
  "download_url": "https://raw.githubusercontent.com/nflverse/nfldata/master/data/games.csv",
  "compression": null,
  "engine": "c",
  "freshness": {
    "type": "gh_commit",
    "gh_api_endpoint": "https://api.github.com/repos/nflverse/nfldata/commits",
    "gh_release_tag": null,
    "sla_seconds": 500
  },
  "iter": {
    "type": null,
    "start": null
  },
  "assignments": [
    "fastr_team_id_repl",
    "score_clean"
  ],
  "map": {
    "game_id": "object",
    "season": "int32",
    "week": "int32",
    ...
  }
}

Config Fields

Field	Description
`name`	Table identifier
`description`	Human-readable description
`download_url`	URL to fetch CSV (use `{0}` placeholder for season in iter tables)
`compression`	Compression type (`"gzip"`, `null`)
`engine`	Pandas CSV engine (`"c"`, `"python"`)
`freshness.type`	`"gh_release"` or `"gh_commit"`
`freshness.gh_api_endpoint`	GitHub API endpoint for freshness checks
`freshness.gh_release_tag`	Release tag for `gh_release` type
`freshness.sla_seconds`	Seconds before re-checking freshness
`iter.type`	`"season"` for multi-file tables, `null` for single file
`iter.start`	Starting year for season iteration
`iter.accept_partial`	Allow success if some season files fail
`assignments`	List of assignment function names to apply
`map`	Column name → dtype mapping

Freshness

The DCM uses a two-tier freshness strategy:

SLA Check: If the last freshness check was within sla_seconds, skip the remote check entirely
Remote Check: Query GitHub API to compare remote timestamps against local state

For gh_release tables, freshness is determined by the updated_at timestamp of release assets. For gh_commit tables, freshness is based on the latest commit date.

Per-File Freshness (v0.2.1+)

For season-iterated tables (pbp, rosters, player_stats, etc.), the DCM tracks freshness per-season. When an update is needed, only stale seasons are re-downloaded - cached seasons are read from Data/Parts/{table}/. This significantly reduces bandwidth for incremental updates.

Data Storage

Data/
  games.csv
  pbp.csv                # Combined table CSV
  Parts/
    pbp/
      1999.csv           # Per-season cache (iter tables only)
      2000.csv
      ...
State/
  Tables/
    games.json           # Per-table state (last_local_update, last_freshness_check)
    pbp.json
  Parts/
    pbp.json             # Per-season timestamps (iter tables only)
  Global/
    season_state.json    # Current NFL season state

Assignments

Assignments are DataFrame transformations applied after data is pulled. They take a DataFrame as input and return a mutated DataFrame. Assignments are defined in Engine/Assignments/ and referenced by name in config files.

Common assignments include:

fastr_team_id_repl - Standardize team abbreviations
score_clean - Fix known data errors in game scores
penalty_formatting - Parse penalty descriptions

GitHub Token (Optional)

To increase GitHub API rate limits from 60/hr to 5,000/hr, create a .env file in your working directory:

GITHUB_TOKEN=ghp_your_token_here

The token is used for freshness checks only, not for downloading CSVs. A token is only relevant/needed when pulling many tables with extremely fast processing times. In most use cases, the default rate limit is sufficient.

API

import nfelodcm

# Load tables
db = nfelodcm.load(['pbp', 'games'])

# Get a single DataFrame
df = nfelodcm.get_df('pbp')

# Get table config
config = nfelodcm.get_map('games')

# List available tables
tables = nfelodcm.list_tables()

# Get current season state
season, week = nfelodcm.get_season_state('last_full_week')

Further Detailed Documentation

File	Description
`nfelodcm/Engine/Primatives/README.md`	Core architecture of the DCM data pipeline
`tests/README.md`	Test suite for the DCM

Metadata

Release files for nfelodcm 0.2.22

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nfelodcm 0.2.22
File	Size	Uploaded	Provenance
nfelodcm-0.2.22.tar.gz	42.2 kB	Oct 20, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for nfelodcm 0.2.22
File	Interpreter	ABI	Platform	Reset
nfelodcm-0.2.22-py3-none-any.whl 58.2 kB Oct 20, 2026 Without provenance	Python 3	none	any	Details

Total release size: 100.3 kB

Release files / nfelodcm-0.2.22.tar.gz

Download URL	nfelodcm-0.2.22.tar.gz
Size	42.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`546547fb639b5c39c72cac2215fb8b17e2603428488c8e3c0ff61f1e20efdd82`
BLAKE2b-256 checksum How to use checksums	`69791877ceb43e7ba05c842fa79e0afe4ebec9d23730112c85284e4cba34e490`
Upload date	Oct 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`

Release files / nfelodcm-0.2.22-py3-none-any.whl

Download URL	nfelodcm-0.2.22-py3-none-any.whl
Size	58.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`536c8a122f69bd8c0f7319b90a1a8e1c68213ffe7f768eb15d3a99ac4e0e9235`
BLAKE2b-256 checksum How to use checksums	`843c3409569d5665d936f84373dbac2d24ff5e5a2d3bf02fa3583f065129d673`
Upload date	Oct 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`

Security for nfelodcm 0.2.22

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.