Skip to contents

Applies the metacleaner decision rules to search results. This is the classification step used inside [clean_reference()]; call it directly only if you produced the hit tables yourself (for example with [search_sequences()]).

Usage

classify_queries(
  query_ids,
  reference_hits,
  contaminant_hits = NULL,
  taxonomy,
  level = "genus",
  require = NULL,
  rescue = TRUE,
  verbose = TRUE
)

Arguments

query_ids

Character vector of all query IDs.

reference_hits

Data frame of hits against the reference database, with at least columns `query`, `subject`, `identity`, `coverage`, `score` and `pass` (as returned by [search_sequences()]).

contaminant_hits

Optional data frame of hits against the contaminant database (same columns), or `NULL`.

taxonomy

Where to find taxonomy; see [clean_reference()].

level

Rank at which query and hit taxonomy must agree. Default `"genus"`.

require

Optional named character vector of length one, e.g. `c(class = "Magnoliopsida")`: every qualifying hit must belong to this taxon.

rescue

Keep queries without a qualifying reference hit when their best hit agrees with their taxonomy at `level` (see rule 2). Default `TRUE`, as in metacleaner 1.x.

verbose

Print progress messages.

Value

A list with elements `status` (one row per query: `id`, `flagged`, `reason`, `database`, `top_hit`, `identity`, `coverage`, `n_hits`, `hit_taxa`) and `lineages` (the lineage table used).

Decision rules

Each query is checked in this order; the first rule that applies gives the reason it is flagged. 1. **matches contaminant database**: the query has a qualifying hit (at `identity` and `coverage`) in the contaminant database. 2. **no match in reference database**: the query has no qualifying hit in the reference database. If `rescue = TRUE` and the query's best non-qualifying hit belongs to the same taxon as the query at `level`, the query is kept and that hit is used in the checks below. 3. **hit outside required <rank>**: (only if `require` is set) at least one qualifying hit is not in the required taxon, or its taxonomy is unknown. 4. **no taxonomy for query**: the query's own taxonomy at `level` is unknown. 5. **matches multiple <level>**: the qualifying hits belong to more than one taxon at `level` (a hit with unknown taxonomy counts as a separate taxon). 6. **matches different <level>**: all qualifying hits belong to one taxon that differs from the query's.

Queries not flagged by any rule are kept.

Examples

hits <- data.frame(query = c("q1", "q2", "q2"), subject = c("r1", "r2", "r3"),
                   identity = 100, coverage = 100, score = 1, pass = TRUE)
tax <- data.frame(id = c("q1", "q2", "r1", "r2", "r3"), taxid = NA,
                  domain = "Eukaryota", phylum = NA, class = NA, order = NA,
                  family = NA, genus = c("Malus", "Malus", "Malus", "Malus", "Pyrus"),
                  species = NA)
res <- classify_queries(c("q1", "q2", "q3"), hits, taxonomy = tax, verbose = FALSE)
res$status[, c("id", "flagged", "reason")]
#>   id flagged                         reason
#> 1 q1   FALSE                           <NA>
#> 2 q2    TRUE         matches multiple genus
#> 3 q3    TRUE no match in reference database