Evaluate a proteolytic digest

evaluate_digest() combines digest_protein() and score_peptides() into a single call and returns a named list containing the peptide table, the score table, and the resolved input parameters. Use it when you want a full digest object for one protein and one enzyme without manually wiring the two lower-level functions together.

Usage

evaluate_digest(
  sequence,
  enzyme = "trypsin",
  missed_cleavages = 1L,
  include_cleavage_efficiency = FALSE,
  proteome = NULL,
  weights = NULL,
  ...
)

Arguments

sequence: Protein input. Accepts the same forms as digest_protein(): a character sequence, named character vector, Biostrings::AAString, Biostrings::AAStringSet, or a FASTA file path. If NULL or empty, raises an error. Multi-record inputs must have unique protein identifiers.
enzyme: Enzyme name passed to digest_protein(). Defaults to "trypsin".
missed_cleavages: Maximum missed cleavages passed to digest_protein(). Defaults to 1L.
include_cleavage_efficiency: Logical flag passed to digest_protein(). When TRUE, the returned peptide table gains a cleavage_efficiency column. This does not affect the score components.
proteome: Optional proteome digest tibble passed to score_peptides() for peptide uniqueness scoring. When NULL (default), no uniqueness scoring is performed.
weights: Optional scoring weight vector passed to score_peptides(). When NULL (default), uses pepVet's default scoring weights. When scoring a non-tryptic digest directly, evaluate_digest() forwards the selected enzyme so enzyme-aware S_count denominators stay aligned with the digest.
...: Additional scoring arguments passed to score_peptides(), such as gravy_range and length_range. This makes workflow presets from pepvet_preset() directly compatible with evaluate_digest() through do.call() or argument splicing.

Value

A named list with three elements:

scores: A tibble from score_peptides() with one row per protein, plus the informational columns n_high_efficiency_sites and n_low_efficiency_sites.
peptides: A tibble from digest_protein() with one row per peptide.
params: A list recording the resolved enzyme name, missed_cleavages count, protein_ids found in the input, the resolved preset_used label, GRAVY and length ranges, active weights, proteome-aware mode, and pI mode.

Details

evaluate_digest() preserves pepVet's scoring metadata so the returned object can be interpreted honestly outside the immediate scoring call. In particular, params$preset_used records whether the resolved scoring configuration matches one of pepVet's named presets or should be treated as "custom". params also stores the resolved GRAVY and length ranges, active weights, proteome-aware mode, and pI mode. The cleavage-efficiency counts summarize annotated trypsin-family cleavage sites only; unsupported enzymes receive NA in these informational fields. For uniquely named multi-record input, score rows, peptide groups, and params$protein_ids follow the supplied record order. Reordering input records changes that presentation order but not the named per-protein results.

Limitations

Cleavage efficiency annotations only work for trypsin-family enzymes. Unsupported enzymes receive NA counts. The scoring model is rule-based; see score_peptides() for scope details.

Examples

bsa_path <- system.file("extdata", "P02769.fasta", package = "pepVet")
result <- evaluate_digest(bsa_path, enzyme = "trypsin")
result$scores
#> # A tibble: 1 × 12
#>   protein_id        S_length S_coverage S_count S_hydro S_charge composite_score
#>   <chr>                <dbl>      <dbl>   <dbl>   <dbl>    <dbl>           <dbl>
#> 1 sp|P02769|ALBU_B…    0.688      0.997       1   0.769    0.778           0.885
#> # ℹ 5 more variables: verdict <chr>, median_peptide_length <dbl>,
#> #   preset_used <chr>, n_high_efficiency_sites <int>,
#> #   n_low_efficiency_sites <int>
result$params$enzyme
#> [1] "trypsin"
result$params$preset_used
#> [1] "standard"