plan_screening: Plan the human screening set with the SAFE stopping rule

In screenllm: LLM-Assisted Title/Abstract Screening for Systematic Reviews

Plan the human screening set with the SAFE stopping rule

Description

Applies the SAFE rule from Spillias et al. (2026) to a ranking produced by rank_records(). Walks the ranked corpus from highest score to lowest, and returns the position where SAFE fires along with the subset of records the human should screen (everything at or above that position). Defaults reproduce the paper's advance-choosable recommended setting: minimum coverage 50\

Usage

plan_screening(
  ranked,
  target_recall = .DEFAULT_TARGET_RECALL,
  safe_min_cover = .DEFAULT_SAFE_MIN_COVER,
  safe_run_length = .DEFAULT_SAFE_RUN_LENGTH,
  spot_check_n = .DEFAULT_SPOT_CHECK_N,
  spot_check_labels = NULL,
  seed = 1L
)

Arguments

ranked	A screenllm_ranking object (output of rank_records()).
target_recall	Target recall (default 0.95).
safe_min_cover	Minimum-coverage fraction (default 0.50).
safe_run_length	Consecutive-negatives run length (default 50).
spot_check_n	Number of records in the SAFE spot-check (default 200).
spot_check_labels	Optional named vector of accept/reject decisions for the spot-check records (names = record ids, values in c("Accept", "Reject")). If NULL, the plan uses a placeholder estimate and reports the stop-point conservatively.
seed	Random seed for the spot-check draw.

Details

Because SAFE's spot-check gate depends on a random sample, the returned plan is only deterministic when seed is set.

Value

A screenllm_plan object.

Examples

# A minimal example. In practice, `ranked` comes from `rank_records()`.
ranked <- data.frame(
  id = paste0("r", 1:100),
  universal_best_score = sort(runif(100, 0, 100), decreasing = TRUE),
  rank = 1:100
)
plan <- plan_screening(ranked, safe_run_length = 10, spot_check_n = 20)
plan

screenllm documentation built on Sept. 24, 2026, 5:11 p.m.