| Title: | Validate Biological Identifiers and Inputs |
|---|---|
| Description: | A gate for biological inputs. Validate gene symbols, ontology terms, variant formats, and database identifiers through one small API, using offline pattern and cache checks or live remote checks. Results are designed to match the companion Python package for the same inputs. |
| Authors: | Samuel Bharti [aut, cre] |
| Maintainer: | Samuel Bharti <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-07-14 08:52:40 UTC |
| Source: | https://github.com/samuelbharti/biobouncer |
A checkmate-style assertion. Throws an error when any element of x is not a
valid identifier for source_db, otherwise returns x invisibly.
assert_valid_id( x, source_db, how = "pattern", species = NULL, version = NULL, .var.name = checkmate::vname(x), add = NULL )assert_valid_id( x, source_db, how = "pattern", species = NULL, version = NULL, .var.name = checkmate::vname(x), add = NULL )
x |
A vector of identifiers. Coerced to character. |
source_db |
Source key, for example |
how |
Checking mode: |
species |
Optional species context, echoed in the result. A name such as
|
version |
Snapshot version. In |
.var.name |
Name for |
add |
A checkmate |
x invisibly on success.
check_valid_id(), test_valid_id().
assert_valid_id(c("MONDO:0005148", "MONDO:0018076"), "mondo")assert_valid_id(c("MONDO:0005148", "MONDO:0018076"), "mondo")
The directory where downloaded snapshots are stored. Set the environment
variable BIOBOUNCER_CACHE_DIR to override the default.
biobouncer_cache_dir()biobouncer_cache_dir()
A path to the cache directory.
biobouncer_cache_dir()biobouncer_cache_dir()
Dispatches on the source's cache$builder: obo fetches the ontology
release, hgnc_tsv fetches the HGNC complete set. Identifiers that match the
source pattern are written to the cache directory as a snapshot, and a
retired-id map, when the builder produces one, to the matching
<version>.retired.tsv sidecar. An OBO version defaults to the ontology's own
data-version; an HGNC version defaults to the source's default_version.
biobouncer_pull(source_db, version = NULL, quiet = FALSE)biobouncer_pull(source_db, version = NULL, quiet = FALSE)
source_db |
Source key, for example |
version |
Snapshot version label. Defaults to the builder's own version. |
quiet |
Suppress progress messages. |
The path to the written snapshot, invisibly.
biobouncer_snapshots(), check_id().
Reports snapshots available for cache mode, both downloaded ones in the
cache directory and the small bundled samples.
biobouncer_snapshots()biobouncer_snapshots()
A tibble with columns source, version,
n_ids, and location ("cache" or "bundled").
biobouncer_snapshots()biobouncer_snapshots()
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.
check_id( x, source_db, how = "pattern", species = NULL, version = NULL, refresh = FALSE, on_error = "raise" )check_id( x, source_db, how = "pattern", species = NULL, version = NULL, refresh = FALSE, on_error = "raise" )
x |
A vector of identifiers. Coerced to character. |
source_db |
Source key, for example |
how |
Checking mode: |
species |
Optional species context, echoed in the result. A name such as
|
version |
Snapshot version. In |
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. |
A tibble with one row per element of x and the
columns input, valid, normalized, suggestion, source_db,
version, species, how, and error.
is_valid_id(), sources(), source_info(), biobouncer_snapshots().
check_id(c("MONDO:0005148", "mondo:5148"), source_db = "mondo") check_id("MONDO:0005148", source_db = "mondo", how = "cache", version = "sample")check_id(c("MONDO:0005148", "mondo:5148"), source_db = "mondo") check_id("MONDO:0005148", source_db = "mondo", how = "cache", version = "sample")
A checkmate-style check function. Returns TRUE when every element of x is
a valid identifier for source_db, otherwise a message describing the
failure. A missing element (NA) is not a failure. Pairs with
assert_valid_id() and test_valid_id().
check_valid_id(x, source_db, how = "pattern", species = NULL, version = NULL)check_valid_id(x, source_db, how = "pattern", species = NULL, version = NULL)
x |
A vector of identifiers. Coerced to character. |
source_db |
Source key, for example |
how |
Checking mode: |
species |
Optional species context, echoed in the result. A name such as
|
version |
Snapshot version. In |
TRUE if all elements are valid, otherwise a message string.
assert_valid_id(), test_valid_id(), is_valid_id().
check_valid_id(c("MONDO:0005148", "MONDO:0018076"), "mondo") check_valid_id("mondo:5148", "mondo")check_valid_id(c("MONDO:0005148", "MONDO:0018076"), "mondo") check_valid_id("mondo:5148", "mondo")
Returns a function of one argument that reports, element by element, whether
each value is a valid identifier for source_db. The predicate is the shape
that data-frame validation packages expect, so it drops straight into
assertr::assert(), a validate::validator() rule, or a pointblank
col_vals_expr() step, or into base Filter() and vapply(). It is the R
counterpart of the pandera check in the Python package.
id_predicate(source_db, how = "pattern", species = NULL, version = NULL)id_predicate(source_db, how = "pattern", species = NULL, version = NULL)
source_db |
Source key, for example |
how |
Checking mode: |
species |
Optional species context, echoed in the result. A name such as
|
version |
Snapshot version. In |
A function of one argument that returns a logical vector the same
length as its input. A missing cell (NA) passes, so it is never dropped by
a filter or flagged by a data-frame rule; only a malformed or non-existent
id is FALSE.
is_valid_id(), check_valid_id().
is_mondo <- id_predicate("mondo") ids <- c("MONDO:0005148", "mondo:5148", "MONDO:0018076") is_mondo(ids) ids[is_mondo(ids)] # With assertr, if it is installed: # library(assertr) # df |> assert(id_predicate("mondo"), term) # With validate, if it is installed: # rules <- validate::validator(is_mondo := id_predicate("mondo")(term)) # validate::confront(df, rules) # With pointblank, if it is installed: # library(pointblank) # create_agent(df) |> # col_vals_expr(~ is_valid_id(term, "mondo")) |> # interrogate()is_mondo <- id_predicate("mondo") ids <- c("MONDO:0005148", "mondo:5148", "MONDO:0018076") is_mondo(ids) ids[is_mondo(ids)] # With assertr, if it is installed: # library(assertr) # df |> assert(id_predicate("mondo"), term) # With validate, if it is installed: # rules <- validate::validator(is_mondo := id_predicate("mondo")(term)) # validate::confront(df, rules) # With pointblank, if it is installed: # library(pointblank) # create_agent(df) |> # col_vals_expr(~ is_valid_id(term, "mondo")) |> # interrogate()
A convenience wrapper over check_id() that returns only the verdict.
is_valid_id( x, source_db, how = "pattern", species = NULL, version = NULL, refresh = FALSE )is_valid_id( x, source_db, how = "pattern", species = NULL, version = NULL, refresh = FALSE )
x |
A vector of identifiers. Coerced to character. |
source_db |
Source key, for example |
how |
Checking mode: |
species |
Optional species context, echoed in the result. A name such as
|
version |
Snapshot version. In |
refresh |
In remote checks, skip any cached response and refetch. Ignored by the offline modes. |
A logical vector, one element per element of x.
is_valid_id(c("MONDO:0005148", "mondo:5148"), source_db = "mondo")is_valid_id(c("MONDO:0005148", "mondo:5148"), source_db = "mondo")
Returns x with every fixable value substituted by its suggestion: an invalid
value that maps to a successor or a well-formed alternative. Valid values,
invalid values with no suggestion, and missing values are returned unchanged,
so the result is the same length and order as x. It is designed to drop into
dplyr::mutate().
repair_id( x, source_db, how = "pattern", species = NULL, version = NULL, refresh = FALSE, on_error = "raise" )repair_id( x, source_db, how = "pattern", species = NULL, version = NULL, refresh = FALSE, on_error = "raise" )
x |
A vector of identifiers. Coerced to character. |
source_db |
Source key, for example |
how |
Checking mode: |
species |
Optional species context, echoed in the result. A name such as
|
version |
Snapshot version. In |
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. |
A character vector the same length as x.
repair_id(c("MONDO:0005148", "mondo:5148"), "mondo")repair_id(c("MONDO:0005148", "mondo:5148"), "mondo")
report_id() runs check_id() over a column and returns its result table
with the extra class biobouncer_report, so it prints with a one-line summary of
how many values are valid, repairable, invalid, or missing. It is the
recommended entry point for inspecting and cleaning a column. Use repair_id()
inside dplyr::mutate() to substitute the fixable values. For enforcing
validity inside a framework, reach for the adapters such as id_predicate().
report_id( x, source_db, how = "pattern", species = NULL, version = NULL, refresh = FALSE, on_error = "raise" ) ## S3 method for class 'biobouncer_report' summary(object, ...) ## S3 method for class 'biobouncer_report' print(x, ...)report_id( x, source_db, how = "pattern", species = NULL, version = NULL, refresh = FALSE, on_error = "raise" ) ## S3 method for class 'biobouncer_report' summary(object, ...) ## S3 method for class 'biobouncer_report' print(x, ...)
x |
A |
source_db |
Source key, for example |
how |
Checking mode: |
species |
Optional species context, echoed in the result. A name such as
|
version |
Snapshot version. In |
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. |
object |
A |
... |
Ignored. |
A tibble, as returned by check_id(), with the extra
class biobouncer_report. Calling summary() on it returns a one-row tibble of
counts.
report_id(c("MONDO:0005148", "mondo:5148"), "mondo")report_id(c("MONDO:0005148", "mondo:5148"), "mondo")
Answers "what does a valid id look like and how can I check it?" for each source.
source_info()source_info()
A tibble with one row per source and the columns
key, name, example (a valid identifier for the source), modes (the
checking modes it supports), species_aware, and version_aware.
source_info()source_info()
List available source databases
sources()sources()
A character vector of source keys, sorted.
source_info() for a table with more detail.
sources()sources()
Returns a rule function for use with shinyvalidate::InputValidator's
add_rule(). The rule returns NULL for a valid input and a message
otherwise. This adapter does not depend on shinyvalidate; it only produces a
rule the package can consume.
sv_biobouncer( source_db, how = "pattern", species = NULL, version = NULL, message = NULL )sv_biobouncer( source_db, how = "pattern", species = NULL, version = NULL, message = NULL )
source_db |
Source key, for example |
how |
Checking mode: |
species |
Optional species context, echoed in the result. A name such as
|
version |
Snapshot version. In |
message |
Optional custom message for an invalid input. |
A function of one argument suitable for add_rule().
rule <- sv_biobouncer("mondo") rule("MONDO:0005148") rule("mondo:5148")rule <- sv_biobouncer("mondo") rule("MONDO:0005148") rule("mondo:5148")
synthesize_ids() builds a small "messy column" for a source: a mix of
well-formed ids, repairable ids (a wrong-case or unpadded form that suggests a
valid one), hard-invalid ids, and missing cells. Every value is labeled by
running the checker, so the labels are always correct and match what the Python
synthesize() produces for the same source. It works in pattern mode (the
shape) for any source and in cache mode (the snapshot) for a source that ships
one. It is useful for exercising a validation pipeline (feed the column to
report_id(), repair_id(), or an adapter) without hand-writing test data. The
generation is deterministic and offline.
synthesize_ids( source_db, how = "pattern", version = NULL, n_valid = 2, n_repairable = 1, n_invalid = 1, missing = 1, seed = 0 )synthesize_ids( source_db, how = "pattern", version = NULL, n_valid = 2, n_repairable = 1, n_invalid = 1, missing = 1, seed = 0 )
source_db |
Source key, for example |
how |
Checking mode to label against: |
version |
In cache mode, the snapshot version. Defaults to |
n_valid |
How many well-formed or in-snapshot ids to include. A source with no numeric part yields just the example. |
n_repairable |
How many repairable ids (a wrong-case or unpadded form that
suggests a valid id, or in cache mode a retired id that maps to a successor).
|
n_invalid |
How many hard-invalid ids (neither valid nor suggestible). |
missing |
How many missing cells ( |
seed |
Shifts the numeric variants, for a different but still deterministic column (pattern mode). |
A tibble with the columns input, category
("valid", "repairable", "invalid", or "missing"), and the valid,
normalized, and suggestion the checker returned for that input. Categories
a source cannot produce are simply absent.
synthesize_ids("mondo")synthesize_ids("mondo")
A checkmate-style test. Returns a single TRUE when every element of x is
valid for source_db, otherwise FALSE.
test_valid_id(x, source_db, how = "pattern", species = NULL, version = NULL)test_valid_id(x, source_db, how = "pattern", species = NULL, version = NULL)
x |
A vector of identifiers. Coerced to character. |
source_db |
Source key, for example |
how |
Checking mode: |
species |
Optional species context, echoed in the result. A name such as
|
version |
Snapshot version. In |
A single logical.
check_valid_id(), assert_valid_id().
test_valid_id(c("MONDO:0005148", "MONDO:0018076"), "mondo") test_valid_id("mondo:5148", "mondo")test_valid_id(c("MONDO:0005148", "MONDO:0018076"), "mondo") test_valid_id("mondo:5148", "mondo")