Skip to contents

Check biological identifiers

Source: R/check_id.R
check_id.Rd

Validate a vector of identifiers against a source. pattern mode checks that each identifier is well-formed. cache mode also checks that it exists in a pinned local snapshot (see biobouncer_snapshots()). remote mode checks live existence against the source API. existence mode uses a snapshot when one is available for version, otherwise falls back to remote, and for a source with no resolver falls back to pattern.

Usage

check_id(
  x,
  source_db,
  how = "pattern",
  species = NULL,
  version = NULL,
  refresh = FALSE,
  on_error = "raise"
)

Arguments

x

A vector of identifiers. Coerced to character.

source_db

Source key, for example "mondo". See sources().

how

Checking mode: "pattern" (offline, shape only), "cache" (offline existence against a snapshot), "remote" (live existence against the source API), or "existence" (cache when a snapshot is available for version, otherwise remote, or pattern for a source with no resolver).

species

Optional species context, echoed in the result. A name such as "homo_sapiens" or an NCBI taxon id such as 9606. When given, an id of a different species is invalid: Ensembl is checked from its id prefix (in pattern and remote modes), and UniProt from the entry's organism in remote mode. A species outside the source map is not checked.

version

Snapshot version. In cache mode it selects the snapshot and defaults to the latest installed one when omitted; it selects the snapshot for existence mode; ignored in pattern and remote modes.

refresh

In remote checks, skip any cached response and refetch. Ignored by the offline modes.

on_error

How a per-id remote failure is handled. "raise" (the default) lets the failure unwind the whole call. "indeterminate" leaves just that id NA with the reason in its error column and checks the rest of the batch, so one unreachable id does not lose the others. Ignored by the offline modes.

Value

A tibble with one row per element of x and the columns input, valid, normalized, suggestion, source_db, version, species, how, and error.

See also

is_valid_id(), sources(), source_info(), biobouncer_snapshots().

Examples

check_id(c("MONDO:0005148", "mondo:5148"), source_db = "mondo")
#> # A tibble: 2 × 9
#>   input        valid normalized suggestion source_db version species how   error
#>   <chr>        <lgl> <chr>      <chr>      <chr>     <chr>   <chr>   <chr> <chr>
#> 1 MONDO:00051… TRUE  MONDO:000… NA         mondo     NA      NA      patt… NA   
#> 2 mondo:5148   FALSE NA         MONDO:000… mondo     NA      NA      patt… NA   
check_id("MONDO:0005148", source_db = "mondo", how = "cache", version = "sample")
#> # A tibble: 1 × 9
#>   input        valid normalized suggestion source_db version species how   error
#>   <chr>        <lgl> <chr>      <chr>      <chr>     <chr>   <chr>   <chr> <chr>
#> 1 MONDO:00051… TRUE  MONDO:000… NA         mondo     sample  NA      cache NA