Evaluation follows explicit Boolean layers: markers OR into components, components AND into enzyme systems, systems OR into reactions, reactions AND into routes, and routes OR into GIFTs. Incomplete calls report the route with the fewest unsupported reactions rather than a raw percentage of genes.
Usage
evaluate_gifts(
annotation_table,
namespace = NULL,
db = NULL,
gene_id = NULL,
max_genes = 5000
)Arguments
- annotation_table
A data frame with `namespace` and `accession` columns and an optional `gene_id` column, or a character vector of marker accessions.
- namespace
Namespace for a character-vector input. If omitted, KO, EC, Pfam, TIGRFAM, NCBIfam and CAZy accessions are inferred where possible.
- db
Optional open gifter database connection.
- gene_id
Which column names genes when `annotation_table` has no `gene_id` column. `NULL`, the default, proposes the first column that is neither `namespace` nor `accession` and adopts it only with approval. A column name adopts that column, `TRUE` approves the proposal in advance, and `FALSE` numbers the markers rather than naming genes. Ignored when a `gene_id` column is already present, unless a column is named explicitly.
- max_genes
Number of distinct gene identifiers above which the input is questioned as a possible collection of genomes. `Inf` evaluates any table as a single genome without asking.
Value
A `gifter_genome` list. Its `gifts` member is the call summary; the remaining tibbles retain the full evidence chain.
Input guardrails
Two input mistakes yield a well-formed result that answers a question the user never asked, and neither is visible in the calls themselves.
An unlabelled column taken for gene identifiers mislabels the whole evidence chain while leaving every call intact, so a table without a `gene_id` column is not guessed at: the first other column is proposed for approval, and without an answer the call fails rather than choosing.
Markers pooled from several genomes complete routes that no single genome encodes, so an input carrying more than `max_genes` distinct gene identifiers is questioned before it is evaluated as one genome. A collection of genomes belongs in `evaluate_gifts_community()`, which evaluates each genome separately.
Examples
markers <- data.frame(
gene_id = paste0("gene_", 1:9),
namespace = "KO",
accession = c(
"K00764", "K01945", "K00601", "K01952", "K01933",
"K01587", "K01756", "K00602", "K01939"
)
)
result <- evaluate_gifts(markers)
result$gifts[, c("gift_id", "complete", "best_route")]
#> # A tibble: 163 × 3
#> gift_id complete best_route
#> <chr> <lgl> <chr>
#> 1 acetate_interconversion FALSE ACETATE_PTA_ACKA
#> 2 acetoin_formation FALSE ACETOIN_ALS_BUDA
#> 3 acetyl_coa_to_isocitrate FALSE TCA1_CS_ACN
#> 4 adenylate_biosynthesis TRUE AMP_ADENYLOSUCCINATE
#> 5 alanine_biosynthesis FALSE ALA_DEHYDROGENASE
#> 6 allantoin_degradation FALSE ALLANTOIN_ALLANTOICASE
#> 7 ammonium_assimilation FALSE AMMONIUM_GDH_NAD
#> 8 anthranilate_degradation_catechol FALSE ANTHRANILATE_TO_CATECHOL
#> 9 arabinose_degradation FALSE ARA_ISOMERASE
#> 10 arabinose_uptake_abc FALSE ARA_UPTAKE_ABC
#> # ℹ 153 more rows
# A table whose gene column is named something else: approve it explicitly
# rather than leaving the choice to column order.
locus_markers <- data.frame(
locus_tag = paste0("b", 1:2),
namespace = "KO",
accession = c("K01198", "K01805")
)
evaluate_gifts(locus_markers, gene_id = "locus_tag")$observed_markers$gene_id
#> [1] "b1" "b2"