### Install ffopportunity from GitHub

Source: https://github.com/ffverse/ffopportunity/blob/main/README.md

Install the development version of the ffopportunity package from GitHub using remotes or devtools. Ensure you have the remotes package installed first.

```r
install.packages("ffopportunity", repos = c("https://ffverse.r-universe.dev", getOption("repos")))

# or use remotes/devtools
# install.packages("remotes")
remotes::install_github("ffverse/ffopportunity")
```

--------------------------------

### Install ffopportunity Package

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/quick-start.md

Install the ffopportunity package from r-universe or GitHub.

```r
# From r-universe
install.packages("ffopportunity", 
  repos = c("https://ffverse.r-universe.dev", getOption("repos")))

# Or from GitHub
remotes::install_github("ffverse/ffopportunity")
```

--------------------------------

### Flexible Argument Matching Example

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/errors.md

Shows how arg_match() allows partial matching for parameters like stat_type in ep_summarize().

```r
ep_summarize(predicted_pbp, stat_type = "exp")  # Matches "expected_points"
```

--------------------------------

### Load RDS from GitHub Raw Content

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-utilities.md

Example of loading an RDS file directly from its raw content URL on GitHub.

```r
data <- rds_from_url(
  "https://github.com/nflverse/nfldata/raw/master/data/games.rds"
)
```

--------------------------------

### is_installed()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-utilities.md

Checks if a specified R package is installed and can be loaded, without throwing an error if it's not found. This is useful for managing optional dependencies.

```APIDOC
## is_installed()

### Description
Checks if a package is installed without raising an error. This is useful for handling optional dependencies.

### Signature
```r
is_installed(pkg)
```

### Parameters
#### Path Parameters
- **pkg** (character) - Required - Package name to check.

### Return Value
Logical: TRUE if package is installed and can be loaded, FALSE otherwise.

### Examples
```r
# Check for optional dependency
if (is_installed("progressr")) {
  p <- progressr::progressor(along = season)
} else {
  p <- NULL
}
```
```

--------------------------------

### ep_preprocess()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/MANIFEST.txt

Performs preprocessing and transformations on data. This documentation includes preprocessing steps, internal helper functions, and examples.

```APIDOC
## ep_preprocess()

### Description
Applies preprocessing steps and transformations to the data.

### Method
(Not specified, assumed to be a function call within the R package)

### Endpoint
(Not applicable, this is an R function)

### Parameters
(Details to be found in api-reference-ep_preprocess.md)

### Request Example
(Details to be found in api-reference-ep_preprocess.md)

### Response
(Details to be found in api-reference-ep_preprocess.md)
```

--------------------------------

### Strict Argument Matching Error Example

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/errors.md

Demonstrates an error when an invalid version is provided to functions like ep_build(). Strict matching requires exact version strings.

```r
ep_build(version = "v2.0.0")
# Error in rlang::arg_match0(...) :
# `version` must be one of "latest" or "v1.0.0", not "v2.0.0".
```

--------------------------------

### Check GitHub CLI Availability

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/internal-functions.md

Verifies if the GitHub CLI is installed and accessible in the system's PATH. Raises an error if the 'gh' command is not found.

```r
gh_test <- try(system("gh", intern = TRUE), silent = TRUE)
if (inherits(gh_test, "try-error")) {
  cli::cli_abort("GitHub CLI not available...")
}
```

--------------------------------

### Utility Functions

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/MANIFEST.txt

Provides access to helper and utility functions, including roster retrieval, URL-based data loading, installation checks, and CLI alerts.

```APIDOC
## Utility Functions

### Description
Provides a suite of helper and utility functions for various tasks.

### Methods
- `.get_rosters()`: Retrieves rosters.
- `rds_from_url()`: Loads RDS data from a URL.
- `is_installed()`: Checks if a package is installed.
- `vcli_alert()`: Displays CLI alerts.
- `vcli_rule()`: Applies CLI rules.

### Endpoint
(Not applicable, these are R functions)

### Parameters
(Details to be found in api-reference-utilities.md)

### Request Example
(Details to be found in api-reference-utilities.md)

### Response
(Details to be found in api-reference-utilities.md)
```

--------------------------------

### ep_predict()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/MANIFEST.txt

Handles model loading and prediction, including post-prediction adjustments. Examples are also provided.

```APIDOC
## ep_predict()

### Description
Loads models and performs predictions, with options for post-prediction adjustments.

### Method
(Not specified, assumed to be a function call within the R package)

### Endpoint
(Not applicable, this is an R function)

### Parameters
(Details to be found in api-reference-ep_predict.md)

### Request Example
(Details to be found in api-reference-ep_predict.md)

### Response
(Details to be found in api-reference-ep_predict.md)
```

--------------------------------

### ep_load()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/MANIFEST.txt

Loads precomputed data. This function is part of the API reference and includes details on its signature, parameters, return value, examples, and error handling.

```APIDOC
## ep_load()

### Description
Loads precomputed data efficiently.

### Method
(Not specified, assumed to be a function call within the R package)

### Endpoint
(Not applicable, this is an R function)

### Parameters
(Details to be found in api-reference-ep_load.md)

### Request Example
(Details to be found in api-reference-ep_load.md)

### Response
(Details to be found in api-reference-ep_load.md, returns an ffopps_load object)
```

--------------------------------

### Summarize Player-Level Expected Points

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-ep_summarize.md

Use stat_type = "expected_points" to get player-level statistics, including fantasy points and expected fantasy points.

```r
# Player-level expected points
player_stats <- ep_summarize(predicted, stat_type = "expected_points")
```

--------------------------------

### Check if Package is Installed (R)

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-utilities.md

Use is_installed to check if a package is available without causing an error. This is useful for conditionally loading optional dependencies or enabling features.

```r
# Check for optional dependency
if (is_installed("progressr")) {
  p <- progressr::progressor(along = season)
} else {
  p <- NULL
}

# Used by ep_load to conditionally enable progress bars
p <- NULL
if (is_installed("progressr")) {
  p <- progressr::progressor(along = season)
}
out <- purrr::map_dfr(urls, nflreadr::progressively(rds_from_url, p))
```

--------------------------------

### RDS Download Warning Example

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/errors.md

Illustrates how rds_from_url() issues a warning and returns an empty tibble if an individual RDS file fails to download from a URL. This allows batch processing to continue.

```r
warning(paste0("Failed to readRDS from <", url, ">"), call. = FALSE)
return(tibble::tibble())
```

--------------------------------

### Get GitHub Release Assets Details

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/internal-functions.md

Fetches details for files attached to a specific GitHub release tag. Returns a data frame with file information including name, size, downloads, and URL.

```r
gh_cli_release_assets <- function(tag, ..., repo = "ffverse/ffopportunity") {
  # Implementation details omitted for brevity
}
```

--------------------------------

### Filter Statistics for a Specific Player

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-ep_summarize.md

This example demonstrates how to filter the summarized statistics to view the fantasy points and expected fantasy points for a particular player across seasons and weeks.

```r
# Filter to specific player
player_stats %>%
  filter(full_name == "Josh Allen") %>%
  select(season, week, fantasy_points, total_fantasy_points_exp)
```

--------------------------------

### Batch Load RDS from Multiple URLs

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-utilities.md

Example of using purrr::map_dfr with rds_from_url to load and combine RDS data from multiple URLs, useful for internal data loading.

```r
urls <- paste0(
  "https://github.com/ffverse/ffopportunity/releases/download/latest-data/ep_weekly_",
  season, ".rds"
)
data <- purrr::map_dfr(urls, rds_from_url)
```

--------------------------------

### Get GitHub Release Tag Names

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/internal-functions.md

Retrieves a list of all release tag names for a specified GitHub repository. Parses JSON output from the 'gh release list' command.

```r
gh_cli_release_tags <- function(repo = "ffverse/ffopportunity") {
  # Implementation details omitted for brevity
}
```

--------------------------------

### Print Method Output for ffopps_build

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/types.md

Shows the typical output format when printing an ffopps_build object, including generation details and a summary of the list components.

```text
<ffopportunity predictions>
Generated 2022-01-11 07:59:33 with model version latest
List of 5
 $ ep_weekly  : tibble [5,756 x 159]
 $ ep_pbp_pass: tibble [18,747 x 57]
 $ ep_pbp_rush: tibble [14,038 x 47]
 $ ep_version : chr "latest"
 $ timestamp  : POSIXct[1:1], format: "2022-01-11 07:59:33"
```

--------------------------------

### Using Exact Version Strings for ep_load()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/errors.md

Demonstrates the correct usage of the version argument in ep_load() by providing exact version strings like 'latest' or 'v1.0.0'.

```r
# Always use exact version string
ep_load(version = "latest")  # Valid
ep_load(version = "v1.0.0")  # Valid
```

--------------------------------

### Pipeline Pattern Flow

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/architecture.md

Illustrates the sequential data flow in the pipeline pattern, from input to output.

```text
Input → Validate → Process → Transform → Output
```

--------------------------------

### Filter using .data pronoun in dplyr

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-utilities.md

Example of using the .data pronoun to filter data within a dplyr pipeline.

```r
ep_data %>%
  dplyr::filter(.data$position == "QB") %>%
  dplyr::select(.data$player_id, .data$full_name)
```

--------------------------------

### Build EP Data from Play-by-Play

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/architecture.md

Build fresh EP data for custom season ranges or model versions. This path involves downloading models, loading play-by-play data, preprocessing, making predictions, and summarizing results. Performance is computation-heavy.

```R
ep_build(season, version)
```

--------------------------------

### Print Method for ep_build() Result

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-ep_build.md

Shows how to use the custom print method for the `ffopps_build` object returned by `ep_build()`. This method provides a concise summary including the model version and generation timestamp.

```r
print(result)
```

--------------------------------

### Filter using .env pronoun with external variable

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-utilities.md

Example of using the .env pronoun to reference an external variable within a dplyr filter.

```r
threshold <- 100
ep_data %>%
  dplyr::filter(.data$fantasy_points > .env$threshold)
```

--------------------------------

### ep_build()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/MANIFEST.txt

Builds data from play-by-play information. This API reference entry covers its signature, parameters, return value, execution steps, and error handling.

```APIDOC
## ep_build()

### Description
Builds data from raw play-by-play information.

### Method
(Not specified, assumed to be a function call within the R package)

### Endpoint
(Not applicable, this is an R function)

### Parameters
(Details to be found in api-reference-ep_build.md)

### Request Example
(Details to be found in api-reference-ep_build.md)

### Response
(Details to be found in api-reference-ep_build.md, returns an ffopps_build object)
```

--------------------------------

### Download ffopportunity Models

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/configuration.md

Use `ep_cache_models()` to download and cache model files. The `ask` argument controls interactive confirmation, and `force` re-downloads existing models.

```r
# Interactive download with confirmation
ep_cache_models(version = "latest")

# Silent download without confirmation
ep_cache_models(version = "latest", ask = FALSE)

# Force re-download (updates existing models)
ep_cache_models(version = "latest", force = TRUE)
```

--------------------------------

### Run Package Tests

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/INDEX.md

Execute the test suite for the ffopportunity package using devtools or testthat.

```r
devtools::test()
```

```r
testthat::test_dir("tests/testthat")
```

--------------------------------

### Download ffverse Models

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/quick-start.md

Download necessary models for ffverse functionality. Set 'ask = FALSE' to avoid interactive prompts.

```r
# Download models
ep_cache_models(ask = FALSE)
```

--------------------------------

### Access Components of ep_build() Result

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-ep_build.md

Demonstrates how to access the individual components of the list returned by `ep_build()`. These components include weekly game-level summaries, pass play data, and rush play data.

```r
weekly_data <- result$ep_weekly
pass_plays <- result$ep_pbp_pass
rush_plays <- result$ep_pbp_rush
```

--------------------------------

### Check Model and Blueprint File Existence

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/errors.md

Asserts that the model and blueprint files exist before attempting to load them. Call ep_cache_models() to download if files are missing.

```r
stopifnot(file.exists(model_path), file.exists(blueprint_path))
```

--------------------------------

### Load and Access ffopps_load Attributes

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/types.md

Demonstrates how to load data using ep_load() and access its metadata attributes such as ep_version, ep_timestamp, and ep_type. The print method for this object also displays metadata.

```r
data <- ep_load(2021)
attr(data, "ep_version")    # "latest"
attr(data, "ep_timestamp")  # POSIXct timestamp
attr(data, "ep_type")       # "weekly"

# Print method displays metadata
print(data)
# → <ffopportunity predictions>
# → Generated 2022-09-12 12:59:18 with ep model version "latest"
```

--------------------------------

### Chaining ep_predict with dplyr

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-ep_predict.md

Illustrates how to chain ep_predict within a data processing pipeline using the pipe operator, starting from loading play-by-play data and ending with predictions.

```r
# Chain operations
result <- nflreadr::load_pbp(2021) %>%
  ep_preprocess() %>%
  ep_predict()
```

--------------------------------

### Build Data from Raw Sources

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/quick-start.md

Build expected points data for a specific season or multiple seasons. The process includes loading, preprocessing, predicting, and summarizing steps, with progress shown. Results can be accessed for weekly summaries, pass plays, and rush plays.

```r
# Build for 2021 season
result <- ep_build(2021)
# Shows progress: Loading → Preprocessing → Predicting → Summarizing

# Access results
weekly_summary <- result$ep_weekly
pass_data <- result$ep_pbp_pass
rush_data <- result$ep_pbp_rush

# Build for multiple seasons
multi <- ep_build(2019:2021)
```

--------------------------------

### Hardhat Integration for Feature Engineering

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/architecture.md

Outlines the process of using Hardhat blueprints for reproducible feature engineering.

```text
Original Features → Recipe (stored in .rds) → Transformed Features
                     ↓
                  .forge_and_predict()
                     ↓
                  xgb.predict()
```

--------------------------------

### Load XGBoost Model and Hardhat Recipe

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/internal-functions.md

Loads an XGBoost model and its corresponding hardhat recipe from the cache. Ensures model and blueprint files exist before loading. Supports different model file types.

```r
.load_model_objs(variable, version, model_file_type = c(".ubj", ".xgb"))
```

```r
stopifnot(file.exists(model_path), file.exists(blueprint_path))
```

```r
xgboost::xgb.load(model_path)
```

```r
readRDS(blueprint_path)
```

--------------------------------

### Chain Preprocessing with Other Operations

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-ep_preprocess.md

Demonstrates how ep_preprocess() can be seamlessly integrated into a data processing pipeline using the pipe operator (%>%).

```r
preprocessed <- nflreadr::load_pbp(2021) %>%
  ep_preprocess()
```

--------------------------------

### Build Expected Points Model - ep_build()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/configuration.md

Builds the expected points model. Uses the most recent season and the latest version by default. The season parameter is dynamic and changes with the current date.

```r
ep_build(
  season = nflreadr::most_recent_season(),
  version = "latest"
)
```

--------------------------------

### Filter Data by Player Position

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/quick-start.md

Filter the loaded data to select players based on their position. Examples include filtering for Quarterbacks (QB), Receivers (WR and TE), and Running Backs (RB).

```r
data <- ep_load(2021)

# Quarterbacks
qbs <- data %>% filter(position == "QB")

# Receivers (WR + TE)
receivers <- data %>% filter(position %in% c("WR", "TE"))

# Running backs
rbs <- data %>% filter(position == "RB")
```

--------------------------------

### Accessing Components of ffopps_build

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/types.md

Demonstrates how to extract individual dataframes and metadata from an ffopps_build object returned by ep_build().

```r
result <- ep_build(2021)

# Extract individual dataframes
weekly <- result$ep_weekly
pass_plays <- result$ep_pbp_pass
rush_plays <- result$ep_pbp_rush

# Check metadata
result$ep_version
result$timestamp
```

--------------------------------

### Model URL Pattern for ep_load()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/errors.md

This is the pattern used for downloading RDS files from GitHub releases for ep_load().

```text
https://github.com/ffverse/ffopportunity/releases/download/{version}-data/ep_{type}_{season}.rds
```

--------------------------------

### Typical ep_predict Usage

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-ep_predict.md

Demonstrates the standard workflow of loading play-by-play data, preprocessing it, and then generating expected points predictions. Accesses the predicted rush and pass dataframes.

```r
# Typical usage within ep_build
pbp <- nflreadr::load_pbp(2021)
preprocessed <- ep_preprocess(pbp)
predictions <- ep_predict(preprocessed)

# Access predicted columns
rush_data <- predictions$rush_df
pass_data <- predictions$pass_df

# Check expected yards
head(rush_data$rushing_yards_exp)
head(pass_data$yards_after_catch_exp)
```

--------------------------------

### Feature Engineering Steps

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/architecture.md

Illustrates common feature engineering techniques applied, including categorical encoding, missing value imputation, and derivation of new metrics.

```text
Categorical encoding (down, qtr as factors)
Missing value imputation (temp=60°F, wind=8mph for unknown)
Derived metrics (implied_total, run_gap_dir, relative_to_sticks)
```

--------------------------------

### ep_build() Function

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-ep_build.md

Builds expected fantasy points predictions by downloading models, loading play-by-play data, applying predictions, and summarizing to player level. It accepts optional season and version parameters.

```APIDOC
## ep_build()

### Description
Build expected fantasy points predictions by downloading models, loading play-by-play data, applying predictions, and summarizing to player level.

### Signature
```r
ep_build(
  season = nflreadr::most_recent_season(),
  version = "latest"
)
```

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Parameters
- **season** (numeric vector) - Optional - Default: `nflreadr::most_recent_season()` - Four-digit year(s) of NFL season(s). Must be >= 2006.
- **version** (character) - Optional - Default: `"latest"` - Expected points model version. One of `"latest"` or `"v1.0.0"` (currently identical).

### Return Value
A list of class `ffopps_build` containing:
- **ep_weekly** (tibble) - Game-level summary by player. One row per player per game with all expected points metrics.
- **ep_pbp_pass** (tibble) - Expected points data on pass plays (57 columns). Includes passing and receiving player predictions.
- **ep_pbp_rush** (tibble) - Expected points data on rush plays (47 columns). Includes rushing player predictions.
- **ep_version** (character) - The model version used (e.g., "latest" or "v1.0.0").
- **timestamp** (POSIXct) - Timestamp of when the build was completed.

### Throws/Errors
- Raises error if season < 2006
- Raises error if invalid version specified (must match "latest" or "v1.0.0")
- May raise errors if:
  - Play-by-play data cannot be downloaded from nflreadr
  - Models cannot be cached/downloaded from GitHub
  - Preprocessing or prediction fails

### Examples
```r
# Build expected points for 2021 season
result <- ep_build(season = 2021)

# Access individual components
weekly_data <- result$ep_weekly
pass_plays <- result$ep_pbp_pass
rush_plays <- result$ep_pbp_rush

# Build for multiple seasons
multi_season <- ep_build(season = 2019:2021)

# Use specific model version
v1_result <- ep_build(season = 2020, version = "v1.0.0")

# Check metadata
print(result)  # Uses custom print method showing version and timestamp
```

### Print Method
The custom `print.ffopps_build()` method displays:
- Alert: "<ffopportunity predictions>"
- Generated timestamp and model version
- Structure of the returned list (max 2 levels)

### Source File
`R/ep_build.R:20-70`

### Execution Steps
The function internally:

1. Validates inputs (season range, version matching)
2. Calls `ep_cache_models()` to ensure models are available
3. Calls `nflreadr::load_pbp()` to download play-by-play data
4. Calls `ep_preprocess()` to prepare data for modeling
5. Calls `ep_predict()` to generate expected points predictions
6. Calls `ep_summarize()` to aggregate to game-level summaries
7. Returns results wrapped in an `ffopps_build` S3 object

### See Also
- `ep_load()` - Load precomputed expected points data
- `ep_preprocess()` - Preprocess play-by-play data
- `ep_predict()` - Generate predictions
- `ep_summarize()` - Summarize predictions to player level
- `ep_cache_models()` - Download and cache models
```

--------------------------------

### Valid Type Arguments for ep_load()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/errors.md

Shows the correct and exact type arguments that can be used with the ep_load() function.

```r
# Type must be exact
ep_load(type = "weekly")      # Valid
ep_load(type = "pbp_pass")    # Valid
ep_load(type = "pbp_rush")    # Valid
```

--------------------------------

### Load Weekly EP Data with ep_load()

Source: https://github.com/ffverse/ffopportunity/blob/main/README.md

Download the latest version of the Expected Points (EP) data for specified seasons and type. This function requires the ffopportunity package to be loaded.

```r
library(ffopportunity)
ep_load(season = 2020:2021, type = "weekly")
```

--------------------------------

### Model URL Pattern for ep_cache_models()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/errors.md

This is the pattern used for downloading zip files from GitHub releases for ep_cache_models().

```text
https://github.com/ffverse/ffopportunity/releases/download/{version}-model/{version}.zip
```

--------------------------------

### Load Precomputed EP Data

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/architecture.md

Use this path to quickly load precomputed expected points data without requiring any computation. Data is downloaded from GitHub releases.

```R
ep_load(season, type, version)
```

--------------------------------

### ep_load()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-ep_load.md

Loads precomputed expected points data from automated GitHub releases. Users can specify the season, data type, and model version.

```APIDOC
## ep_load()

### Description
Loads precomputed expected points data from automated GitHub releases. Users can specify the season, data type, and model version.

### Signature
```r
ep_load(
  season = nflreadr::most_recent_season(),
  type = c("weekly", "pbp_pass", "pbp_rush"),
  version = c("latest", "v1.0.0")
)
```

### Parameters
#### Parameters
- **season** (numeric vector) - Optional - Default: `nflreadr::most_recent_season()` - Four-digit year(s) of NFL season(s). Must be >= 2006.
- **type** (character) - Optional - Default: `"weekly"` - Data type to download. One of `"weekly"` (game-level player summary), `"pbp_pass"` (pass play data), or `"pbp_rush"` (rush play data).
- **version** (character) - Optional - Default: `"latest"` - Expected points model version. One of `"latest"` or `"v1.0.0"` (currently identical).

### Return Value
A tibble (data.frame) of expected points data with additional attributes:
- `ep_version`: The model version used
- `ep_timestamp`: Timestamp of when the data was generated
- `ep_type`: The data type loaded
- Object class: `ffopps_load`, `tbl_df`, `tbl`, `data.frame`

The returned dataframe contains 159 columns including season, posteam, week, game_id, player_id, position, and expected points predictions for various play outcomes.

### Throws/Errors
- Raises error if season < 2006
- Raises error if invalid type specified (must match one of three allowed values)
- Raises error if invalid version specified (must match "latest" or "v1.0.0")
- Attempts to download data from GitHub releases; may fail with network errors

### Examples
```r
# Load current season data
ep_load()

# Load multiple seasons
ep_load(season = 2020:2021)

# Load specific data type
ep_load(2021, type = "pbp_pass")

# Load with specific model version
ep_load(2006, type = "pbp_rush", version = "v1.0.0")

# Access metadata
data <- ep_load(2021, type = "weekly")
attr(data, "ep_version")
attr(data, "ep_timestamp")
```
```

--------------------------------

### Use Preprocessed Data with ep_predict()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-ep_preprocess.md

Shows how the output of ep_preprocess() can be directly piped into the ep_predict() function to generate expected points predictions.

```r
predictions <- ep_preprocess(pbp) %>%
  ep_predict()
```

--------------------------------

### ep_build()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/configuration.md

Builds or retrieves expected points (EP) models for a specified NFL season and version. It allows users to access pre-trained models or specify a particular version.

```APIDOC
## ep_build()

### Description
Builds or retrieves expected points (EP) models for a specified NFL season and version.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **season** (numeric) - Optional - Default Value: Most recent season. Dynamic - changes with current date.
- **version** (character) - Optional - Default Value: "latest". Mirrors v1.0.0 currently.
```

--------------------------------

### ffopps_build S3 Class Structure

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/architecture.md

Describes the structure and components of the ffopps_build S3 class, used for list container return values.

```text
ep_build() → list(ep_weekly, ep_pbp_pass, ep_pbp_rush, ep_version, timestamp)
           → class: ffopps_build
           → custom print method
```

--------------------------------

### Load Expected Points Data - ep_load()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/configuration.md

Loads expected points data. Defaults to the most recent season, 'weekly' type, and 'latest' version. The season parameter is dynamic. For 'type' and 'version', the first element is used if not specified.

```r
ep_load(
  season = nflreadr::most_recent_season(),
  type = c("weekly", "pbp_pass", "pbp_rush"),
  version = c("latest", "v1.0.0")
)
```

--------------------------------

### Pre-cache Models for Offline Use

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/quick-start.md

Download necessary models for offline analysis. After caching, functions like ep_build() and ep_predict() will use the local cached models.

```r
# Download models for offline work
ep_cache_models(version = "latest", ask = FALSE)

# Now ep_build() and ep_predict() will use cached models
result <- ep_build(2021)
```

--------------------------------

### Load and Preprocess Play-by-Play Data

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/quick-start.md

Load play-by-play data for a specific season and preprocess it for modeling. The output includes rush and pass dataframes.

```r
# Load your own play-by-play data
pbp <- nflreadr::load_pbp(2021)

# Preprocess for modeling
preprocessed <- ep_preprocess(pbp)
str(preprocessed)  # List with rush_df and pass_df

# Could modify data here...

# Generate predictions
predictions <- ep_predict(preprocessed)

# Summarize
summary_stats <- ep_summarize(predictions)
```

--------------------------------

### Analyze Expected vs. Actual Performance

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/quick-start.md

Compare actual fantasy points to expected fantasy points for players. Calculates and arranges players by their outperformance.

```r
data <- ep_load(2021)

# Compare fantasy points to expected
performance <- data %>%
  dplyr::select(
    full_name, position, posteam, week,
    total_fantasy_points, total_fantasy_points_exp
  ) %>%
  dplyr::mutate(
    outperformance = total_fantasy_points - total_fantasy_points_exp
  ) %>%
  dplyr::arrange(desc(outperformance))

head(performance)
```

--------------------------------

### ep_summarize()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/MANIFEST.txt

Aggregates player and team statistics for fantasy points scoring. Includes details on the aggregation process and scoring rules.

```APIDOC
## ep_summarize()

### Description
Aggregates player and team statistics, applying fantasy points scoring rules.

### Method
(Not specified, assumed to be a function call within the R package)

### Endpoint
(Not applicable, this is an R function)

### Parameters
(Details to be found in api-reference-ep_summarize.md)

### Request Example
(Details to be found in api-reference-ep_summarize.md)

### Response
(Details to be found in api-reference-ep_summarize.md)
```

--------------------------------

### data.table Operations for Performance

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/architecture.md

Demonstrates the use of data.table for efficient data manipulation and summary statistics.

```text
dplyr::transmute() → data.table := operators → summary statistics
```

--------------------------------

### Predict Expected Points - ep_predict()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/configuration.md

Predicts expected points using preprocessed play-by-play data. Defaults to the 'latest' version. Requires output from ep_preprocess() as input.

```r
ep_predict(
  preprocessed_pbp,
  version = c("latest", "v1.0.0")
)
```

--------------------------------

### Invoke GitHub CLI Command

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/internal-functions.md

Executes a GitHub CLI command and captures its output. Handles potential errors by checking for warnings from the system command.

```r
out <- purrr::quietly(system)(cli_command, intern = TRUE)
if (length(out$warnings)) {
  cli::cli_abort("GitHub CLI error...")
}
```

--------------------------------

### Preprocess Play-by-Play Data - ep_preprocess()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/configuration.md

Preprocesses play-by-play data for the expected points model. This function requires a play-by-play dataframe as input and has no optional parameters.

```r
ep_preprocess(pbp)
```

--------------------------------

### Build EP Data with ep_build()

Source: https://github.com/ffverse/ffopportunity/blob/main/README.md

Build Expected Points (EP) data from base nflverse data for a given season and version. This function processes play-by-play data to generate EP predictions.

```r
ep_build(season = 2021, version = "latest")
```

--------------------------------

### Create New Columns

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/quick-start.md

Add new columns to the dataset, such as calculating efficiency based on existing fantasy points and projected fantasy points.

```r
# Create new columns
data %>% mutate(efficiency = total_fantasy_points / total_fantasy_points_exp)
```

--------------------------------

### Build Expected Points

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/README.md

Builds expected points from raw data. This function is part of the API reference for the ffopportunity package.

```APIDOC
## ep_build

### Description
Builds expected points from raw data.

### Method
Not specified (assumed R function call)

### Endpoint
Not applicable (R function)

### Parameters
Not specified in source.

### Request Example
Not specified in source.

### Response
Not specified in source.
```

--------------------------------

### Preprocess NFL Play-by-Play Data

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-ep_preprocess.md

Loads play-by-play data for a given season and preprocesses it using ep_preprocess(). This is the primary way to prepare data for EP modeling.

```r
pbp <- nflreadr::load_pbp(2021)
preprocessed <- ep_preprocess(pbp)
```

--------------------------------

### Analyze Player Outperformance

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-ep_summarize.md

This snippet shows how to calculate and rank players by their outperformance, defined as actual fantasy points minus expected fantasy points.

```r
# Analyze performance vs expectations
player_stats %>%
  select(player_id, full_name, fantasy_points, total_fantasy_points_exp) %>%
  mutate(outperformance = fantasy_points - total_fantasy_points_exp) %>%
  arrange(desc(outperformance))
```

--------------------------------

### Filter Starters

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/quick-start.md

Filter the dataset to include only players who have played in at least 10 games.

```r
# Filter to starters (multiple games)
starters <- data %>%
  group_by(full_name) %>%
  filter(n() >= 10)
```

--------------------------------

### Load Data with Local nflreadr Data

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/quick-start.md

Troubleshoot network timeouts during data loading by using local nflreadr data with ffverse preprocessing and prediction functions.

```r
# Use ep_build() with local nflreadr data instead
pbp <- nflreadr::load_pbp(2021)
result <- ep_preprocess(pbp) %>% ep_predict() %>% ep_summarize()
```

--------------------------------

### Control Verbose Output in ffopportunity

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/configuration.md

Set the `ffopportunity.verbose` option to TRUE to display progress messages during operations like `ep_build()`. Set it to FALSE to suppress these messages.

```r
# Enable verbose output (default)
options(ffopportunity.verbose = TRUE)
result <- ep_build(2021)  # Shows progress messages

# Suppress progress messages
options(ffopportunity.verbose = FALSE)
result <- ep_build(2021)  # Runs silently
```

--------------------------------

### Upload Files to GitHub Release

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/internal-functions.md

Uploads specified files to a GitHub release. Supports overwriting existing files. Issues warnings for missing files but continues with available ones.

```r
gh_cli_release_upload <- function(files, tag, ..., repo = "ffverse/ffopportunity", overwrite = TRUE) {
  # Implementation details omitted for brevity
}
```

--------------------------------

### Load and Predict NFL Play-by-Play Data

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-ep_summarize.md

This snippet demonstrates how to load 2021 play-by-play data, preprocess it, and generate predictions using the ep_preprocess and ep_predict functions.

```r
# Load and predict
predicted <- nflreadr::load_pbp(2021) %>%
  ep_preprocess() %>%
  ep_predict()
```

--------------------------------

### Helper Functions and Operators

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/README.md

Provides helper functions and operators for the ffopportunity package. This is part of the API reference.

```APIDOC
## utilities

### Description
Helper functions and operators.

### Method
Not specified (assumed R function call)

### Endpoint
Not applicable (R function)

### Parameters
Not specified in source.

### Request Example
Not specified in source.

### Response
Not specified in source.
```

--------------------------------

### ffopps_load S3 Class Structure

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/architecture.md

Details the structure and attributes of the ffopps_load S3 class, a data wrapper with metadata.

```text
ep_load() → tibble with metadata attributes
          → class: c("ffopps_load", "tbl_df", "tbl", "data.frame")
          → custom print method
          → attributes: ep_version, ep_timestamp, ep_type
```

--------------------------------

### Load and Select Data

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/quick-start.md

Load data for a specific season and select relevant columns for analysis.

```r
data <- ep_load(2021)

# Select specific columns
data %>% select(full_name, position, total_fantasy_points)
```

--------------------------------

### .data and .env

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-utilities.md

Data pronouns imported from rlang, used within tidyverse functions to disambiguate column names from variables.

```APIDOC
## .data and .env

Data pronouns for tidy evaluation: `.data` and `.env` imported from rlang.

### Usage

Used within dplyr and other tidyverse functions to disambiguate column names from variables.

### Examples

```r
# Within dplyr pipeline
ep_data %>%
  dplyr::filter(.data$position == "QB") %>%
  dplyr::select(.data$player_id, .data$full_name)

# Refer to external variable
threshold <- 100
ep_data %>%
  dplyr::filter(.data$fantasy_points > .env$threshold)
```
```

--------------------------------

### Forge and Predict with XGBoost Model

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/internal-functions.md

Applies a pre-trained XGBoost model and hardhat recipe to input data. Suppresses warnings by default. Appends predictions to the input dataframe.

```r
.forge_and_predict(df, variable, version)
```

--------------------------------

### Lazy Model Loading Flow

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/architecture.md

Shows the sequence of operations for lazy model loading, from caching to prediction.

```text
ep_cache_models()  # Downloads to cache
    ↓
ep_predict()       # Loads from cache on demand
    ├─ .load_model_objs()  # Load one model
    └─ .forge_and_predict()  # Apply and append
```

--------------------------------

### Check if ffopportunity Models Exist

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/configuration.md

Determine if model files for the latest version are present in the cache directory. This uses `rappdirs::user_cache_dir()` to find the correct location.

```r
cache_dir <- rappdirs::user_cache_dir("ffopportunity", "ffverse")
latest_models <- file.path(cache_dir, "latest")
model_exists <- dir.exists(latest_models)
```

--------------------------------

### ep_load()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/configuration.md

Loads play-by-play data for a given NFL season, type, and version. Supports loading weekly, pass, or rush play-by-play data.

```APIDOC
## ep_load()

### Description
Loads play-by-play data for a given NFL season, type, and version.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **season** (numeric) - Optional - Default Value: Most recent season. Dynamic - changes with current date.
- **type** (character) - Optional - Default Value: "weekly". First element if not specified. Accepts: "weekly", "pbp_pass", "pbp_rush".
- **version** (character) - Optional - Default Value: "latest". First element if not specified. Accepts: "latest", "v1.0.0".
```

--------------------------------

### Load XGBoost Model

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/errors.md

Loads an XGBoost model from a specified file path. If the file is corrupt or in the wrong format, an xgboost error will occur. Recovery involves deleting the cache and re-downloading.

```r
model <- xgboost::xgb.load(model_path)
```

--------------------------------

### Load Play-by-Play Data

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/architecture.md

Downloads raw play-by-play data for a specified NFL season using the nflreadr package.

```R
nflreadr::load_pbp(season)
```

--------------------------------

### ep_preprocess()

Source: https://github.com/ffverse/ffopportunity/blob/main/_autodocs/api-reference-ep_preprocess.md

Preprocesses NFL play-by-play data to prepare it for expected points predictions. It takes a play-by-play dataframe and returns a list containing preprocessed dataframes for rushing and passing plays.

```APIDOC
## ep_preprocess(pbp)

### Description
Preprocesses NFL play-by-play data to prepare it for expected points predictions. It takes a play-by-play dataframe and returns a list containing preprocessed dataframes for rushing and passing plays.

### Parameters
#### Path Parameters
- **pbp** (data.frame) - Required - Play-by-play dataframe from `nflreadr::load_pbp()`.

### Return Value
A list of two dataframes:
- `rush_df` (data.frame): Preprocessed rushing plays, including rushing and qb_kneel plays with expected points features transformed.
- `pass_df` (data.frame): Preprocessed passing plays, including pass and qb_spike plays with expected points features transformed.

Both dataframes include original nflreadr columns plus transformations and engineered features for model input.

### Examples
```r
# Preprocess a season of data
pbp <- nflreadr::load_pbp(2021)
preprocessed <- ep_preprocess(pbp)

# Access individual components
rush_data <- preprocessed$rush_df
pass_data <- preprocessed$pass_df

# Chain with other operations
preprocessed <- nflreadr::load_pbp(2021) %>%
  ep_preprocess()

# Use with ep_predict
predictions <- ep_preprocess(pbp) %>%
  ep_predict()
```
```