Score digested peptides for pre-acquisition review

score_peptides() summarizes a pepVet digest tibble into per-protein scoring components and a weighted composite score. The scoring model is designed for digest planning and enzyme comparison, not for post-search peptide detectability prediction.

Usage

score_peptides(
  digest_result,
  proteome = NULL,
  weights = NULL,
  gravy_range = c(-1, 0.6),
  length_range = c(7L, 25L),
  enzyme = "trypsin",
  include_pI = FALSE
)

Arguments

digest_result

A digest tibble produced by digest_protein() or an equivalent table containing the columns protein_id, peptide, start, end, length, and missed_cleavages. If NULL or missing required columns, raises an error.

proteome

Optional digest tibble representing the comparison proteome used for peptide uniqueness scoring. When NULL (default), S_unique is excluded and protein-only default weights are used.

weights

Optional numeric weight vector. In protein-only mode the default weights are c(S_length = 0.200, S_coverage = 0.348, S_count = 0.226, S_hydro = 0.138, S_charge = 0.088). In proteome-aware mode the weights are c(S_length = 0.160, S_coverage = 0.279, S_count = 0.181, S_hydro = 0.110, S_charge = 0.070, S_unique = 0.200). The weight vectors are documented expert priors chosen for pepVet, not coefficients fitted to experimental outcomes. Coverage and peptide count receive the largest combined weight in the default protein-only vector.

gravy_range

Numeric vector of length 2 defining the inclusive GRAVY range used by S_hydro. Defaults to c(-1.0, 0.6). If NULL, raises an error.

length_range

Integer vector of length 2 defining the inclusive valid peptide length range used by S_length, S_coverage, S_count, S_hydro, S_charge, and S_unique. Defaults to c(7L, 25L). If NULL, raises an error.

enzyme

Cleavage rule name used to choose the fallback expected peptide length when the digest contains fewer than three peptides. Defaults to "trypsin". If NULL, raises an error.

include_pI

Logical flag indicating whether to append a pI list column containing peptide-level pI values for valid peptides. Defaults to FALSE. If NULL, raises an error.

Value

A tibble with one row per protein_id and the component score columns S_length, S_coverage, S_count, S_hydro, S_charge, optional S_unique, plus composite_score, verdict, and median_peptide_length, and preset_used. The median_peptide_length column records the digest-level denominator used in the enzyme-aware S_count calculation. The preset_used column records the named preset whose resolved scoring configuration exactly matches the current call, or "custom" otherwise. When include_pI = TRUE, the output also includes a pI list column with one named numeric vector per protein, storing valid-peptide pI values keyed by peptide sequence.

Details

Valid peptides are defined as peptides with lengths between 7 and 25 residues inclusive by default, but this window can be changed with length_range. Coverage is computed from valid peptide coordinates with overlapping intervals reduced before coverage is summed. S_hydro uses the inclusive gravy_range; mixed sequences average known hydrophobicity values, and sequences with no known values score zero. S_unique is only computed when a proteome digest is supplied. S_charge measures the fraction of valid peptides that contain at least one non-terminal basic residue to capture extra charge-state richness rather than baseline ionizability. A zero S_count means that the enzyme produced no cleavage sites or no usable peptides. In that case pepVet applies a hard failure: composite_score is set to zero and the verdict is Poor, regardless of the other component values. This is the documented exception to the weighted-sum equation. Composite verdicts are classified as Good for scores >= 0.65, Moderate for scores >= 0.4, and Poor otherwise.

Limitations

pepVet is a rule-based digest-ranking model, not a peptide detectability predictor. The verdict thresholds are heuristic, the default and preset weights are expert priors rather than empirically fit coefficients, and the scoring windows assume conventional C18 reversed-phase LC with ESI. pepVet does not model PTMs, chemical labels, chromatographic gradients, or instrument-specific fragmentation behavior. Composite scores are interpretable rankings with no physical unit; they are not calibrated probabilities. Cross-workflow comparisons are only meaningful when the resolved scoring configuration matches, which is why preset_used is recorded in the output.

Examples

digest_result <- digest_protein("MKWVTFISLLFLFSSAYSR")
score_peptides(digest_result)
#> # A tibble: 1 × 10
#>   protein_id S_length S_coverage S_count S_hydro S_charge composite_score
#>   <chr>         <dbl>      <dbl>   <dbl>   <dbl>    <dbl>           <dbl>
#> 1 sequence_1    0.667          1       1       0      0.5           0.751
#> # ℹ 3 more variables: verdict <chr>, median_peptide_length <dbl>,
#> #   preset_used <chr>

target_and_background <- digest_protein(
  c(target = "AAAAAAARAAAAAAAK", background = "AAAAAAARGGGGGGGK")
)
score_peptides(
  target_and_background[target_and_background$protein_id == "target", ],
  proteome = target_and_background
)
#> # A tibble: 1 × 11
#>   protein_id S_length S_coverage S_count S_hydro S_charge S_unique
#>   <chr>         <dbl>      <dbl>   <dbl>   <dbl>    <dbl>    <dbl>
#> 1 target            1          1       1       0    0.333    0.667
#> # ℹ 4 more variables: composite_score <dbl>, verdict <chr>,
#> #   median_peptide_length <dbl>, preset_used <chr>