enrollcast

https://localopen.github.io/enrollcast
Admin
enrollcast is an R package that projects school enrollment using the cohort survival and grade...
Tokens:13,005
Snippets:92
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install development version of enrollcast from GitHub

Source: https://localopen.github.io/enrollcast/index.html

Installs the development version of enrollcast from GitHub using the pak package. Requires the pak package to be installed first.

```R
# install.packages("pak")
pak::pak("localopen/enrollcast")
```

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

### Example: swing_schedule() with project_enrollment() and output

Source: https://localopen.github.io/enrollcast/reference/swing_schedule.html

Example showing how to build a schedule with swing_years=2, recovery multipliers, and entry=130, then project enrollment. The output shows enrollment held flat for years 1-2, recovery scaling for years 3-5, and entry-driven projection for year 6.

```r
ratios <- data.frame(
  grade_from = c("K", "1"), grade_to = c("1", "2"), ratio = c(0.92, 0.97)
)
schedule <- swing_schedule(ratios,
  horizon = 6, swing_years = 2,
  recovery = c(1.10, 1.10, 1.05), entry = 130
)
project_enrollment(c(K = 80, `1` = 66, `2` = 60), schedule = schedule)
#>    year grade enrollment
#> 1     1     K   80.00000
#> 2     1     1   66.00000
#> 3     1     2   60.00000
#> 4     2     K   80.00000
#> 5     2     1   66.00000
#> 6     2     2   60.00000
#> 7     3     K   88.00000
#> 8     3     1   72.60000
#> 9     3     2   66.00000
#> 10    4     K   96.80000
#> 11    4     1   79.86000
#> 12    4     2   72.60000
#> 13    5     K  101.64000
#> 14    5     1   83.85300
#> 15    5     2   76.23000
#> 16    6     K  130.00000
#> 17    6     1   93.50880
#> 18    6     2   81.33741
```

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

### Example: project_enrollment() with history and ratios

Source: https://localopen.github.io/enrollcast/reference/project_enrollment.html

Example usage of project_enrollment() with a data frame of historical enrollment, computed ratios, and a 3-year projection with entry values. The output shows the projected enrollment for grades K, 1, and 2 for years 2024-2026.

```r
history <- data.frame(
  year = rep(2021:2023, each = 3),
  grade = factor(rep(c("K", "1", "2"), 3), levels = c("K", "1", "2")),
  enrollment = c(100, 90, 80, 110, 95, 88, 120, 99, 91)
)
ratios <- progression_ratios(history)
base <- subset(history, year == 2023, c("grade", "enrollment"))
project_enrollment(base, ratios,
  horizon = 3, entry = c(125, 130, 128),
  start_year = 2023
)
```

```r
#>   year grade enrollment
#> 1 2024     K  125.00000
#> 2 2024     1  111.00000
#> 3 2024     2   95.81579
#> 4 2025     K  130.00000
#> 5 2025     1  115.62500
#> 6 2025     2  107.42982
#> 7 2026     K  128.00000
#> 8 2026     1  120.25000
#> 9 2026     2  111.90607
```

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

### Install development dependencies and check package

Source: https://localopen.github.io/enrollcast/CONTRIBUTING.html

Install all necessary development dependencies and run R CMD check to ensure the package is in a valid state.

```R
devtools::install_dev_deps()
devtools::check()
```

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

### Install enrollcast from CRAN

Source: https://localopen.github.io/enrollcast/index.html

Installs the stable version of the enrollcast package from CRAN.

```R
install.packages("enrollcast")
```

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

### Basic example with default method

Source: https://localopen.github.io/enrollcast/reference/progression_ratios.html

Creates a sample history data frame and computes progression ratios using the default mean method. The output shows grade_from, grade_to, and ratio columns.

```R
history <- data.frame(
  year = rep(2021:2023, each = 3),
  grade = factor(rep(c("K", "1", "2"), 3), levels = c("K", "1", "2")),
  enrollment = c(100, 90, 80, 110, 95, 88, 120, 99, 91)
)
progression_ratios(history)
#>   grade_from grade_to     ratio
#> 1          K        1 0.9250000
#> 2          1        2 0.9678363
```

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

### Weighted method example

Source: https://localopen.github.io/enrollcast/reference/progression_ratios.html

Uses method = "weighted" with weights aligned most-recent to oldest. The comment explains that the 2022->2023 transition gets weight 2 and 2021->2022 gets weight 1.

```R
# For method = "weighted", weights align most-recent to oldest: here the
# 2022->2023 transition gets weight 2 and 2021->2022 gets weight 1.
progression_ratios(history, method = "weighted", weights = c(2, 1))
#>   grade_from grade_to     ratio
#> 1          K        1 0.9166667
#> 2          1        2 0.9645224
```

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

### Example: Create projection matrix from ratios

Source: https://localopen.github.io/enrollcast/reference/progression_matrix.html

Builds a projection matrix from a data frame of ratios for grades K to 2. An infinite ratio is rejected; NA or NaN ratios are kept with a warning. Returns a square numeric matrix with grade dimnames.

```r
ratios <- data.frame(
  grade_from = c("K", "1"),
  grade_to = c("1", "2"),
  ratio = c(0.92, 0.97)
)
progression_matrix(ratios)
#>      K    1 2
#> K 0.00 0.00 0
#> 1 0.92 0.00 0
#> 2 0.00 0.97 0
```

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

### Load enrollcast library

Source: https://localopen.github.io/enrollcast/articles/enrollcast.html

Initializes the package for use.

```R
library(enrollcast)
```

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

### project_enrollment(base, ratios = NULL, horizon = NULL, entry = NULL, schedule = NULL, start_year = NULL)

Source: https://localopen.github.io/enrollcast/reference/project_enrollment.html

Projects grade-level enrollment forward an arbitrary horizon using the grade progression ratio method. Internally builds a projection matrix from ratios and advances enrollment one year at a time, overwriting the entry grade with the supplied exogenous value each year.

```APIDOC
## project_enrollment(base, ratios = NULL, horizon = NULL, entry = NULL, schedule = NULL, start_year = NULL)

### Description
Projects grade-level enrollment forward an arbitrary horizon using the grade progression ratio method. Internally builds a projection matrix from `ratios` and advances enrollment one year at a time (one matrix-vector product per projected year), overwriting the entry grade with the supplied exogenous value each year. `ratios` is optional when a `schedule` is supplied.

### Usage
```r
project_enrollment(
  base,
  ratios = NULL,
  horizon = NULL,
  entry = NULL,
  schedule = NULL,
  start_year = NULL
)
```

### Arguments
- **base** (data frame or named numeric vector) - Required - Most recent observed enrollment: either a data frame with columns `grade` and `enrollment` (optionally `year`), or a named numeric vector. Grade values or vector names must be present and unique. Enrollment must be finite, non-missing, and non-negative.
- **ratios** (data frame or data-frame subclass) - Optional - A data frame with columns `grade_from`, `grade_to`, and `ratio`, as returned by `progression_ratios()`. `grade_from` and `grade_to` must not be missing. `ratio` must be numeric, non-negative, and finite; an infinite ratio (from a zero-enrollment feeder) is rejected, while `NA`/`NaN` ratios (e.g. from sparse history) are kept in the matrix with a warning.
- **horizon** (positive integer) - Optional - Number of years to project.
- **entry** (numeric vector or data frame) - Optional - Exogenous entry-grade enrollment for each projected year: a numeric vector of length `horizon`, or a data frame with an `enrollment` or `value` column. Values must be finite, non-missing, and non-negative. If `NULL`, the entry grade is held constant at its base value and a warning is issued.
- **schedule** (list) - Optional - Prebuilt projection schedule: a list of per-year steps, each `list(matrix = <square projection matrix>, entry = <NULL or a single number>)`, as produced by `swing_schedule()`. When supplied, `ratios` and `entry` must be `NULL` and `horizon` defaults to the schedule length. Each matrix must be numeric and square; non-missing coefficients must be finite and non-negative. `NA`/`NaN` coefficients are preserved and trigger a warning. A missing coefficient can make its output row missing. If that missing enrollment remains after entry replacement, the next matrix multiplication spreads missingness to all grade results because zero times a missing value is still missing. A non-`NULL` entry value then restores only the entry grade. Matrix row and column names must be unique and identical in the same order; all steps must use the same names. A step's `entry` must be `NULL` or one finite, non-negative number.
- **start_year** (integer) - Optional - Label for the base year; output years run from `start_year + 1`. An explicit value and all resulting years must be within the R integer range. If `NULL`, the year is derived from `base$year` when present; that column must contain one unambiguous integer within the same range. With no year column, output years are `1..horizon`.

### Value
A long data frame with columns `year`, `grade`, and `enrollment`, covering the projected years only.

### Examples
```r
history <- data.frame(
  year = rep(2021:2023, each = 3),
  grade = factor(rep(c("K", "1", "2"), 3), levels = c("K", "1", "2")),
  enrollment = c(100, 90, 80, 110, 95, 88, 120, 99, 91)
)
ratios <- progression_ratios(history)
base <- subset(history, year == 2023, c("grade", "enrollment"))
project_enrollment(base, ratios,
  horizon = 3, entry = c(125, 130, 128),
  start_year = 2023
)
#>   year grade enrollment
#> 1 2024     K  125.00000
#> 2 2024     1  111.00000
#> 3 2024     2   95.81579
#> 4 2025     K  130.00000
#> 5 2025     1  115.62500
#> 6 2025     2  107.42982
#> 7 2026     K  128.00000
#> 8 2026     1  120.25000
#> 9 2026     2  111.90607
```
```

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

### Basic enrollcast usage: calculate ratios and project enrollment

Source: https://localopen.github.io/enrollcast/index.html

Shows the core workflow: load enrollcast, create a historical grade-level enrollment data frame, calculate progression ratios with progression_ratios() using the 'mean' method, and project enrollment forward with project_enrollment() using an exogenous entry grade vector. The output shows the calculated ratios and the projected enrollment for three years.

```R
library(enrollcast)

# Historical grade-level enrollment (long format).
history <- data.frame(
  year = rep(2021:2023, each = 3),
  grade = factor(rep(c("K", "1", "2"), 3), levels = c("K", "1", "2")),
  enrollment = c(100, 90, 80, 110, 95, 88, 120, 99, 91)
)

# 1. Calculate progression ratios.
ratios <- progression_ratios(history, method = "mean")
ratios
#>   grade_from grade_to     ratio
#> 1          K        1 0.9250000
#> 2          1        2 0.9678363

# 2. Project forward. The entry grade (K) is supplied exogenously.
base <- history[history$year == 2023, c("grade", "enrollment")]
projection <- project_enrollment(
  base = base,
  ratios = ratios,
  horizon = 3,
  entry = c(125, 130, 128),
  start_year = 2023
)
projection
#>   year grade enrollment
#> 1 2024     K  125.00000
#> 2 2024     1  111.00000
#> 3 2024     2   95.81579
#> 4 2025     K  130.00000
#> 5 2025     1  115.62500
#> 6 2025     2  107.42982
#> 7 2026     K  128.00000
#> 8 2026     1  120.25000
#> 9 2026     2  111.90607
```

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

### Fork and clone the repository

Source: https://localopen.github.io/enrollcast/CONTRIBUTING.html

Use this command to fork the enrollcast repository and clone it to your local machine.

```R
usethis::create_from_github("localopen/enrollcast", fork = TRUE)
```

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

### Project multiple schools with lapply() and split()

Source: https://localopen.github.io/enrollcast/index.html

Demonstrates projecting enrollment for multiple schools by splitting the data frame by school and applying the projection workflow with lapply(). The output shows the projected enrollment for the 'North' school.

```R
# fmt: skip
school_history <- data.frame(
  school = rep(c("North", "South"), each = 9),
  year = rep(2021:2023, each = 3, times = 2),
  grade = factor(rep(c("K", "1", "2"), times = 6), levels = c("K", "1", "2")),
  enrollment = c(100, 90, 80, 110, 95, 88, 120, 99, 91, 120, 
                 110, 100, 130, 115, 108, 140, 119, 111)
)

projections <- lapply(
  split(school_history, school_history$school),
  function(df) {
    ratios <- progression_ratios(df)
    base <- df[df$year == max(df$year), c("year", "grade", "enrollment")]
    project_enrollment(base, ratios, horizon = 3, entry = rep(100, 3))
  }
)

projections$North
#>   year grade enrollment
#> 1 2024     K  100.00000
#> 2 2024     1  111.00000
#> 3 2024     2   95.81579
#> 4 2025     K  100.00000
#> 5 2025     1   92.50000
#> 6 2025     2  107.42982
#> 7 2026     K  100.00000
#> 8 2026     1   92.50000
#> 9 2026     2   89.52485
```

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

### project_enrollment() function signature

Source: https://localopen.github.io/enrollcast/reference/project_enrollment.html

Shows the usage signature of the project_enrollment() function with its arguments: base, ratios, horizon, entry, schedule, and start_year.

```r
project_enrollment(
  base,
  ratios = NULL,
  horizon = NULL,
  entry = NULL,
  schedule = NULL,
  start_year = NULL
)
```

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

### Inspect the underlying projection matrix with progression_matrix()

Source: https://localopen.github.io/enrollcast/index.html

Shows how to inspect the projection matrix created from the ratios. The output displays the matrix with grade-to-grade transition probabilities.

```R
progression_matrix(ratios)
#>       K         1 2
#> K 0.000 0.0000000 0
#> 1 0.925 0.0000000 0
#> 2 0.000 0.9678363 0
```

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

### Comparison with stats::weighted.mean()

Source: https://localopen.github.io/enrollcast/reference/progression_ratios.html

Shows how to compute the same K -> 1 ratio using stats::weighted.mean(). Unlike the weights argument in progression_ratios(), weighted.mean() pairs each weight with the value at the same position, and per-year ratios run oldest to newest, so weights must be reversed.

```R
# The same K -> 1 ratio via stats::weighted.mean(). Unlike `weights`
# above, weighted.mean() pairs each weight with the value at the same
# position, and the per-year ratios run oldest to newest -- so the
# weights must be reversed to line up.
k_ratios <- c(95 / 100, 99 / 110) # 2021->2022, then 2022->2023
stats::weighted.mean(k_ratios, rev(c(2, 1)))
#> [1] 0.9166667
```

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

### swing_schedule(ratios, horizon, swing_years, recovery, entry = NULL, grade_order = NULL)

Source: https://localopen.github.io/enrollcast/reference/swing_schedule.html

Assembles a per-year projection schedule for a school passing through a temporary relocation (swing). Enrollment is held flat during swing years, scaled by recovery multipliers, then projected using grade progression ratios.

```APIDOC
## swing_schedule(ratios, horizon, swing_years, recovery, entry = NULL, grade_order = NULL)

### Description
Assembles a per-year `project_enrollment()` schedule for a school passing through a temporary relocation ("swing"): enrollment is held flat at the depressed observed level during the swing (identity steps), scaled by year-over-year recovery multipliers for the recovery window (diagonal steps), then projected with the grade progression ratio method (the normal projection matrix) for the remaining years.

### Usage
```r
swing_schedule(
  ratios,
  horizon,
  swing_years,
  recovery,
  entry = NULL,
  grade_order = NULL
)
```

### Arguments

#### ratios
- **ratios** (data frame) - Required - A data frame or data-frame subclass with columns `grade_from`, `grade_to`, and `ratio`, as returned by `progression_ratios()`. `grade_from` and `grade_to` must not be missing. `ratio` must be numeric, non-negative, and finite; an infinite ratio (from a zero-enrollment feeder) is rejected, while `NA`/`NaN` ratios (e.g. from sparse history) are kept in the matrix with a warning.

#### horizon
- **horizon** (integer) - Required - Number of years to project (a positive integer).

#### swing_years
- **swing_years** (integer) - Required - Number of leading years the school is swinging (a non-negative integer); enrollment is held flat at `base`.

#### recovery
- **recovery** (numeric vector or matrix) - Required - Recovery multipliers applied for one year each, immediately after the swing and compounding on the prior year: a numeric vector (whole-school, one multiplier per recovery year) or a grade-by-year numeric matrix (one row per grade). Values must be finite, non-missing, and non-negative. Named matrix rows are matched and reordered by grade; unnamed rows are interpreted in projection grade order. Use `numeric(0)` for no recovery window.

#### entry
- **entry** (numeric vector) - Optional - Exogenous entry-grade enrollment for the normal grade progression ratio years only: one finite, non-missing, non-negative numeric value for each of the `horizon - swing_years - length(recovery)` years after recovery. Must be empty when there are no normal years.

#### grade_order
- **grade_order** (character vector) - Optional - Optional character vector giving the low-to-high grade order. If omitted, the order is reconstructed from the transition chain. Every non-entry grade in `grade_order` must appear as a `grade_to` in `ratios`. Must not contain duplicates or missing values.

### Value
A list of `horizon` projection steps suitable for the `schedule` argument of `project_enrollment()`.

### Examples
```r
ratios <- data.frame(
  grade_from = c("K", "1"), grade_to = c("1", "2"), ratio = c(0.92, 0.97)
)
schedule <- swing_schedule(ratios,
  horizon = 6, swing_years = 2,
  recovery = c(1.10, 1.10, 1.05), entry = 130
)
project_enrollment(c(K = 80, `1` = 66, `2` = 60), schedule = schedule)
#>    year grade enrollment
#> 1     1     K   80.00000
#> 2     1     1   66.00000
#> 3     1     2   60.00000
#> 4     2     K   80.00000
#> 5     2     1   66.00000
#> 6     2     2   60.00000
#> 7     3     K   88.00000
#> 8     3     1   72.60000
#> 9     3     2   66.00000
#> 10    4     K   96.80000
#> 11    4     1   79.86000
#> 12    4     2   72.60000
#> 13    5     K  101.64000
#> 14    5     1   83.85300
#> 15    5     2   76.23000
#> 16    6     K  130.00000
#> 17    6     1   93.50880
#> 18    6     2   81.33741
```
```

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

### progression_matrix(ratios, grade_order = NULL)

Source: https://localopen.github.io/enrollcast/reference/progression_matrix.html

Assembles the projection matrix used to advance enrollment. Progression ratios are placed on the sub-diagonal; the entry-grade row is left at zero. The ratios must form a single low-to-high chain.

```APIDOC
## progression_matrix(ratios, grade_order = NULL)

### Description
Assembles the projection matrix used to advance enrollment. Progression ratios are placed on the sub-diagonal (each non-entry grade is fed by the grade below); the entry-grade row is left at zero because entry enrollment is supplied exogenously to `project_enrollment()`. The ratios must form a single low-to-high chain: each `grade_to` must be the grade immediately above its `grade_from` in the resolved order.

### Usage
```r
progression_matrix(ratios, grade_order = NULL)
```

### Arguments
- **ratios** (data.frame) - Required - A data frame or data-frame subclass with columns `grade_from`, `grade_to`, and `ratio`, as returned by `progression_ratios()`. `grade_from` and `grade_to` must not be missing. `ratio` must be numeric, non-negative, and finite; an infinite ratio (from a zero-enrollment feeder) is rejected, while `NA`/`NaN` ratios (e.g. from sparse history) are kept in the matrix with a warning.
- **grade_order** (character vector) - Optional - Optional character vector giving the low-to-high grade order. If omitted, the order is reconstructed from the transition chain. Every non-entry grade in `grade_order` must appear as a `grade_to` in `ratios`. Must not contain duplicates or missing values.

### Value
A square numeric matrix with grade dimnames.

### Examples
```r
ratios <- data.frame(
  grade_from = c("K", "1"),
  grade_to = c("1", "2"),
  ratio = c(0.92, 0.97)
)
progression_matrix(ratios)
#>      K    1 2
#> K 0.00 0.00 0
#> 1 0.92 0.00 0
#> 2 0.00 0.97 0
```
```

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

### Initialize a Git branch for pull request

Source: https://localopen.github.io/enrollcast/CONTRIBUTING.html

Create a new Git branch specifically for your proposed changes.

```R
usethis::pr_init("brief-description-of-change")
```

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

### Push changes and create pull request

Source: https://localopen.github.io/enrollcast/CONTRIBUTING.html

Push your local commits to GitHub and initiate the pull request process in your browser.

```R
usethis::pr_push()
```

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

### BibTeX citation for enrollcast package

Source: https://localopen.github.io/enrollcast/authors.html

BibTeX entry for citing the enrollcast R package version 0.1.0. Use this in LaTeX documents to reference the package. The entry includes the title, author, year, note, and URL as generated from the package DESCRIPTION file.

```bibtex
@Manual{,
  title = {enrollcast: Project School Enrollment with Grade Progression Ratios},
  author = {Rory Lawless},
  year = {2026},
  note = {R package version 0.1.0},
  url = {https://localopen.github.io/enrollcast/},
}
```

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

### progression_ratios() function usage

Source: https://localopen.github.io/enrollcast/reference/progression_ratios.html

Shows the function signature with all arguments and defaults. Use this to call progression_ratios() with a long data frame of historical enrollment.

```R
progression_ratios(
  data,
  year = "year",
  grade = "grade",
  enrollment = "enrollment",
  method = c("mean", "geometric", "median", "last", "weighted"),
  n_years = NULL,
  weights = NULL,
  grade_order = NULL
)
```

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

### Project enrollment forward

Source: https://localopen.github.io/enrollcast/articles/enrollcast.html

Projects future enrollment based on base year data, ratios, and exogenous entry values.

```R
base <- history[history$year == 2023, c("grade", "enrollment")]
projection <- project_enrollment(
  base = base,
  ratios = ratios,
  horizon = 3,
  entry = c(125, 130, 128),
  start_year = 2023
)
projection
```

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

### Function usage: progression_matrix(ratios, grade_order = NULL)

Source: https://localopen.github.io/enrollcast/reference/progression_matrix.html

Shows the call signature for `progression_matrix()`. The `ratios` argument is a data frame with columns `grade_from`, `grade_to`, and `ratio`; the optional `grade_order` is a low-to-high grade vector.

```r
progression_matrix(ratios, grade_order = NULL)
```

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

### Generate progression matrix

Source: https://localopen.github.io/enrollcast/articles/enrollcast.html

Converts calculated ratios into a projection matrix.

```R
progression_matrix(ratios)
```

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

### Model school modernization swing

Source: https://localopen.github.io/enrollcast/articles/enrollcast.html

Creates a projection schedule that accounts for temporary enrollment depression and recovery during school modernization.

```R
depressed <- c(K = 80, `1` = 66, `2` = 60)
schedule <- swing_schedule(ratios,
  horizon = 6, swing_years = 2,
  recovery = c(1.10, 1.10, 1.05), entry = 130
)
project_enrollment(depressed, schedule = schedule, start_year = 2023)
```

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

### swing_schedule() function signature

Source: https://localopen.github.io/enrollcast/reference/swing_schedule.html

Usage signature for swing_schedule(). Arguments: ratios, horizon, swing_years, recovery, entry, grade_order.

```r
swing_schedule(
  ratios,
  horizon,
  swing_years,
  recovery,
  entry = NULL,
  grade_order = NULL
)
```

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

### progression_ratios

Source: https://localopen.github.io/enrollcast/reference/progression_ratios.html

Computes grade progression ratios from historical enrollment data. Accepts a data frame with year, grade, and enrollment columns, and returns a data frame with grade_from, grade_to, and ratio columns.

```APIDOC
## progression_ratios

### Description
Calculates cohort survival / grade progression ratios from historical grade-level enrollment. For each non-entry grade, the ratio is enrollment in that grade divided by enrollment in the grade below one year earlier, summarised across the available year-to-year transitions.

### Usage
```r
progression_ratios(
  data,
  year = "year",
  grade = "grade",
  enrollment = "enrollment",
  method = c("mean", "geometric", "median", "last", "weighted"),
  n_years = NULL,
  weights = NULL,
  grade_order = NULL
)
```

### Arguments
- **data** (data.frame) - Required - A long data frame or data-frame subclass of historical enrollment with one row per grade per year. Enrollment may be `NA`, but non-missing values must be finite and non-negative; `NaN` and infinite values are rejected. Year values must be coercible to finite integers and must not be missing.
- **year** (character) - Optional - Distinct, non-missing character scalar naming the year column in `data`. Default is `"year"`.
- **grade** (character) - Optional - Distinct, non-missing character scalar naming the grade column in `data`. Default is `"grade"`.
- **enrollment** (character) - Optional - Distinct, non-missing character scalar naming the enrollment column in `data`. Default is `"enrollment"`.
- **method** (character) - Optional - How to summarise per-year ratios into one ratio per grade: `"mean"` (default), `"geometric"`, `"median"`, `"last"` (most recent transition only), or `"weighted"`.
- **n_years** (integer) - Optional - Use only the most recent `n_years` available adjacent-year transitions. If `n_years` exceeds the number of available transitions, all are used.
- **weights** (numeric) - Optional - For `method = "weighted"`, a finite, non-missing, non-negative numeric vector aligned most-recent to oldest, with one weight per transition year used and a positive sum. Do not supply weights for other methods.
- **grade_order** (character) - Optional - Optional character vector giving the low-to-high grade order. If omitted, factor levels, numeric ordering, or (with a warning) alphabetical ordering is used.

### Value
A data frame with columns `grade_from`, `grade_to`, and `ratio`, one row per non-entry grade.

### Details
Only transitions between observed consecutive calendar years are used. If the history has one or more calendar-year gaps but still contains an adjacent year pair, the gaps are reported in a warning and are not bridged. Histories with no adjacent year pair are rejected. Gap detection examines the complete supplied history before `n_years` selects recent adjacent transitions, so an older gap still warns even when it lies outside the selected transitions.

### Examples
```r
history <- data.frame(
  year = rep(2021:2023, each = 3),
  grade = factor(rep(c("K", "1", "2"), 3), levels = c("K", "1", "2")),
  enrollment = c(100, 90, 80, 110, 95, 88, 120, 99, 91)
)
progression_ratios(history)
#>   grade_from grade_to     ratio
#> 1          K        1 0.9250000
#> 2          1        2 0.9678363

# For method = "weighted", weights align most-recent to oldest: here the
# 2022->2023 transition gets weight 2 and 2021->2022 gets weight 1.
progression_ratios(history, method = "weighted", weights = c(2, 1))
#>   grade_from grade_to     ratio
#> 1          K        1 0.9166667
#> 2          1        2 0.9645224

# The same K -> 1 ratio via stats::weighted.mean(). Unlike `weights`
# above, weighted.mean() pairs each weight with the value at the same
# position, and the per-year ratios run oldest to newest -- so the
# weights must be reversed to line up.
k_ratios <- c(95 / 100, 99 / 110) # 2021->2022, then 2022->2023
stats::weighted.mean(k_ratios, rev(c(2, 1)))
#> [1] 0.9166667
```
```

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

### Calculate progression ratios

Source: https://localopen.github.io/enrollcast/articles/enrollcast.html

Computes grade progression ratios from historical data using the mean method.

```R
ratios <- progression_ratios(history, method = "mean")
ratios
```

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

### Define historical enrollment data

Source: https://localopen.github.io/enrollcast/articles/enrollcast.html

Creates a data frame representing historical enrollment counts by year and grade.

```R
history <- data.frame(
  year = rep(2021:2023, each = 3),
  grade = factor(rep(c("K", "1", "2"), 3), levels = c("K", "1", "2")),
  enrollment = c(100, 90, 80, 110, 95, 88, 120, 99, 91)
)
history
```

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

### Combine history and projection

Source: https://localopen.github.io/enrollcast/articles/enrollcast.html

Merges historical data with projected results for visualization or analysis.

```R
observed <- data.frame(
  year = history$year,
  grade = as.character(history$grade),
  enrollment = history$enrollment
)
combined <- rbind(observed, projection)
head(combined)
```
Tokens:
Raw