Package 'plasticdb'

Title: Client for the PlasticDB Plastic Biodegradation Database
Description: Query PlasticDB (<https://v2.plasticdb.org>), a curated database of microorganisms and proteins linked to plastic biodegradation, and the evidence behind each link (interactions, experiments and observations). Catalogue tables are returned as tibbles and protein sequences as 'Biostrings' AAStringSet objects. Reads can be pinned to a named, citable dataset release; answers from a pinned release are cached on disk with 'BiocFileCache'. Jobs run PlasticDB's analyses on the server (DIAMOND annotation of genes, genomes and genome sets, taxa-table matching, pathway mapping, HMM screens and taxonomy trees) from files, FASTA text or 'Biostrings' sets. The data is licensed CC BY 4.0: cite() returns the citation for the release used.
Authors: Victor Gambarini [aut, cre] (ORCID: <https://orcid.org/0000-0002-5639-6820>)
Maintainer: Victor Gambarini <[email protected]>
License: MIT + file LICENSE
Version: 0.99.6
Built: 2026-11-19 08:53:27 UTC
Source: https://github.com/BiocStaging/plasticdb

Help Index


Protein sequences as an AAStringSet

Description

as_aastringset() turns a table or record that carries sequences (a protein or variant record, proteins_variants(), evidence_constructs()) into a Biostrings::AAStringSet. Names are the accessions (⁠PlasticDB_<id>⁠ for the few records without one, as in the server's FASTA files); every other column goes into mcols(). Records without a sequence are dropped.

Usage

as_aastringset(x, ...)

Arguments

x

A tibble with a sequence column, or a record list from proteins_get() or variants_get().

...

Unused.

Details

Protein lists carry no sequence unless asked (proteins_list(include_sequence = TRUE) adds a sequence column, which as_aastringset() accepts). proteins_sequences() and variants_sequences() ask for it, live or pinned, so they need one list call; against a server that does not return it they fall back to the FASTA download with the same filters.

Value

An Biostrings::AAStringSet with metadata columns.

Examples

variants <- tibble::tibble(id = 1:2, accession = c("PB0001", NA),
    variant_name = c("A", "B"), sequence = c("MKV", "MKL"))
as_aastringset(variants)

The change feed

Description

Records updated, merged or removed at or after since (live only). Each row has entity_type, id, accession, status ("updated", "merged" or "removed"), merged_into (a merge's survivor) and updated_at. To keep a local copy in sync, store provenance(feed)$as_of and pass it as the next since.

Usage

changes(since, entity_type = NULL, limit = Inf, client = plasticdb_client())

Arguments

since

A time (POSIXct, Date or ISO 8601 string).

entity_type

NULL for every type, or one of "protein", "protein_variant", "microorganism", "plastic", "paper".

limit

The most records to return (Inf for all of them).

client

A plasticdb_client().

Value

A tibble; its provenance also carries since and as_of.

Examples

feed <- changes(since = Sys.Date() - 7, limit = 10)
table(feed$status)
provenance(feed)$as_of

How to cite PlasticDB

Description

The citation for the data a client reads: the dataset release (with its DOI) and the PlasticDB paper, as a utils::bibentry() (so print(), format(style = "text") and toBibtex() all work). The data is licensed CC BY 4.0, which the citation states. A pinned client cites its release; an unpinned one the current release. If the server cannot be reached the citation still names the paper (with a warning).

Usage

cite(client = plasticdb_client())

Arguments

client

A plasticdb_client().

Details

To cite this R package itself, use citation("plasticdb").

Value

A bibentry with two entries: the dataset and the paper.

Examples

ref <- cite()
ref
toBibtex(ref)

Download files

Description

Filtered tables, the whole dataset, and a release's checksummed artefacts. Every function writes to path (a file, or an existing directory to save the server's file name in) and returns the path written.

Usage

downloads_proteins(
  path,
  format = c("csv", "json", "fasta"),
  ...,
  client = plasticdb_client()
)

downloads_microorganisms(
  path,
  format = c("csv", "json"),
  ...,
  client = plasticdb_client()
)

downloads_plastics(
  path,
  format = c("csv", "json"),
  ...,
  client = plasticdb_client()
)

downloads_papers(
  path,
  format = c("csv", "json"),
  ...,
  client = plasticdb_client()
)

downloads_protein_variants(
  path,
  format = c("csv", "json"),
  ...,
  client = plasticdb_client()
)

downloads_dataset(
  path,
  format = c("zip", "json"),
  max_wait = 0,
  client = plasticdb_client()
)

downloads_search(
  path,
  q,
  format = c("json", "zip"),
  client = plasticdb_client()
)

downloads_artefacts(release = NULL, client = plasticdb_client())

downloads_release_file(file, path, release = NULL, client = plasticdb_client())

downloads_manifest(release = NULL, client = plasticdb_client())

downloads_structure(
  structure_id,
  path,
  release = NULL,
  client = plasticdb_client()
)

Arguments

path

A file, or an existing directory to save the file in.

format

The file format.

...

Filters, as for the matching ⁠*_list()⁠ function.

client

A plasticdb_client().

max_wait

Seconds to keep waiting while the dataset ZIP is built.

q

The search text.

release

A release version, or NULL for the pinned or current one.

file

An artefact's path within the release, e.g. "parquet/proteins.parquet".

structure_id

A structure's numeric id.

Details

  • downloads_proteins(), downloads_microorganisms(), downloads_plastics(), downloads_papers() and downloads_protein_variants() save one table as CSV or JSON (proteins also as FASTA), filtered as the matching ⁠*_list()⁠ function. A pinned client downloads that release's table as published (any filter is then plasticdb_release_unsupported_filter); the file is kept in the BiocFileCache, so a second call is a local copy.

  • downloads_dataset() saves every public record: a ZIP of CSVs with a README and licence, or one JSON (live only). The ZIP is built on demand; while it is being built the server answers 503 with Retry-After (plasticdb_service_unavailable, field retry_after); max_wait (seconds) keeps waiting that long for it.

  • downloads_search() saves every record matching a search (live only).

  • downloads_artefacts() lists the files a release published (Parquet tables, reference databases, MANIFEST.json); downloads_release_file() saves one, checked against the SHA-256 the release published (a mismatch is plasticdb_checksum and nothing is kept); downloads_manifest() returns the parsed MANIFEST.json; and downloads_structure() saves one structure's coordinates as published by a release (gzipped PDB). Release artefacts are immutable, so they are always cached. release defaults to the client's pinned release, else the current one.

Value

The path written (downloads_artefacts(): a tibble; downloads_manifest(): a list).

Examples

path <- downloads_plastics(tempdir())
head(utils::read.csv(path)[, c("id", "name")])

downloads_proteins(tempdir(), format = "fasta", plastic = "PET")
downloads_dataset(tempdir(), max_wait = 300)
## Release artefacts exist once a dataset release is published:
client <- plasticdb_client(release = "2026.50")
tryCatch({
    downloads_artefacts(client = client)
    downloads_release_file("parquet/proteins.parquet", tempdir(),
        client = client)
}, plasticdb_error = function(e) message(conditionMessage(e)))

The evidence behind the catalogue

Description

Evidence is organised interaction -> experiment -> observation: one actor (an organism or a protein) tested on one plastic in one paper, the experiments that tested it, and the values each measured. Interactions are listed per protein; evidence_interactions(level = "observation") gives one row per measured value. The material tables describe what was assayed: constructs (sequences as expressed), preparations (host, purification, tags) and binding (adsorption) assays.

Usage

evidence_interactions(
  protein,
  evidence_level = c("all", "direct", "indirect"),
  level = c("interaction", "experiment", "observation"),
  include_sequenceless = FALSE,
  limit = Inf,
  kind = NULL,
  client = plasticdb_client()
)

evidence_kinetics(protein, limit = Inf, client = plasticdb_client())

evidence_properties(protein, limit = Inf, client = plasticdb_client())

evidence_binding_assays(..., limit = Inf, client = plasticdb_client())

evidence_binding_assay(assay_id, client = plasticdb_client())

evidence_constructs(..., limit = Inf, client = plasticdb_client())

evidence_construct(construct_id, client = plasticdb_client())

evidence_construct_structures(construct_id, client = plasticdb_client())

evidence_preparations(..., limit = Inf, client = plasticdb_client())

evidence_preparation(preparation_id, client = plasticdb_client())

evidence_experiment_preparations(experiment_id, client = plasticdb_client())

interactions_list(..., limit = Inf, client = plasticdb_client())

interactions_get(interaction_id, client = plasticdb_client())

experiments_list(..., limit = Inf, client = plasticdb_client())

experiments_get(experiment_id, client = plasticdb_client())

observations_list(..., limit = Inf, client = plasticdb_client())

observations_get(observation_id, client = plasticdb_client())

Arguments

protein

A protein accession.

evidence_level

"all" (the default), "direct" (assayed on the protein itself) or "indirect" (credited through its engineered variants) interactions.

level

One row per "interaction", "experiment" or "observation". Deeper levels repeat the interaction's columns and add ⁠experiment.*⁠ (and ⁠observation.*⁠) columns.

include_sequenceless

Include records without a sequence.

limit

The most records to return (Inf for all of them).

kind

Deprecated: the old name of evidence_level. It is sent as evidence_level, never alongside it; different values in both signal plasticdb_argument_error.

client

A plasticdb_client().

...

Filters (see Details), named as the API names them.

assay_id, construct_id, preparation_id, experiment_id, interaction_id

A record's id.

observation_id

A record's id.

Details

  • evidence_interactions(), evidence_kinetics() and evidence_properties() are the same as proteins_interactions(), proteins_kinetics() and proteins_properties().

  • evidence_binding_assays(), evidence_constructs() and evidence_preparations() list the material tables, filtered by protein, protein_id, protein_variant_id, paper_id or doi (and, for binding assays, plastic, plastic_id and include_subtypes). Constructs carry sequences: as_aastringset() works on them.

  • evidence_binding_assay(), evidence_construct() and evidence_preparation() return one record by id; evidence_construct_structures() the structures linked to a construct and evidence_experiment_preparations() the preparations one experiment assayed.

  • interactions_list(), experiments_list() and observations_list() list the spine as flat tables of every public record (the columns of the release tables of the same name; an interaction adds actor_type and the actors' accessions, product_compound_ids is a list column), and interactions_get(), experiments_get() and observations_get() return one by id. They need no protein: filter with plastic (and include_subtypes), plastic_id, microorganism (the evidence that credits the organism, its enzymes' assays included), protein (an accession), evidence_level ("all", "direct" or "indirect"; "direct" and "indirect" need protein or microorganism), paper_id, doi, polarity, evidence_method, substrate_form, measurement_type and has_quantitative. Experiments also take interaction_id, and observations interaction_id and experiment_id. On interactions the experiment and observation filters ask one of its experiments to match them all. These lists answer a pinned release too. Records are visible exactly as in a release: staged, withdrawn or merged records are never listed.

Value

A tibble with provenance, or a plasticdb_record list.

Examples

obs <- evidence_interactions("PBFCTW", level = "observation", limit = 2)
dim(obs)

interactions_list(plastic = "PET", evidence_level = "direct",
    protein = "PBFCTW", limit = 5)
constructs <- evidence_constructs(protein = "PBFCTW", limit = 2)
as_aastringset(constructs)

Follow, read and share a job

Description

  • job_get() fetches a job (yours, or one submitted without an account) by id, or refreshes a plasticdb_job: its status, summary and provenance, not its hits. job_status() returns just the status: "waiting", "running", "done" or "error".

  • wait_job() polls until the job finishes and returns it: every poll_interval seconds, backing off by half each time up to max_poll_interval; a 429 waits for the server's Retry-After. Past timeout seconds it signals plasticdb_job_timeout (the job keeps running: call wait_job() again, or job_get() later). A failed job signals plasticdb_job_failed (field job, the server's reason as the message) unless error = FALSE.

  • job_results() returns the results by job type: for annotate_gene, annotate_genome, compare_genomes (source_label names the genome) and hmm_screen, every stored hit as a tibble, paged from the server 500 at a time (the results file and page also hide hits under 70 % reference coverage by default; this does not). An hmm_screen hit is a profile match, not an alignment: pident, length, qcov and scov are always NA (never 0), jobs run before server 2.90.0 included, so identity and coverage filters do not apply to them (test is.na() or skip them). subject_seq_id is the profile name and profile_accession its accession; evalue and bitscore are the full-sequence values, domain_score (double), domain_c_evalue and domain_i_evalue those of the best domain, hmm_from/hmm_to (its span on the profile) and env_from/env_to (its envelope on your sequence; 1-based, inclusive) are integer. All of these are NA on DIAMOND hits and on HMM jobs run before 2.90.0. The HMM TSV from job_download() has 8 more columns after calibration_status: read it by header name. For pathway_analysis one row per pathway step (present, the best hit); for annotate_list your table's rows with PlasticDB's columns added; for build_tree a plasticdb_tree: newick (the cladogram as Newick text), matrix (organism x plastic, TRUE where it acts on the plastic) and phylo (an ape::phylo when ape is installed and phylo = TRUE, else NULL).

  • job_comparison() is a compare_genomes job's genome x plastic matrix for a view of the hits (with no thresholds, the job's default view).

  • job_download() saves the server's results file: a TSV with ⁠#⁠ provenance lines, or a ZIP for compare_genomes (per-genome hit tables, the matrix and provenance.json). Hit tables apply the job's default view unless you pass thresholds (0 turns one off) or all_hits = TRUE. Result files are deleted under the server's retention policy; then it signals plasticdb_results_expired (the record and hits stay readable).

  • job_share() creates a read-only link to the job's results. Its token is in the answer once only: keep ⁠$url⁠. It is sent with an Idempotency-Key, so a retry returns the same link. job_shares() lists the job's links (never their tokens), job_unshare() revokes one at once. These three are for the job's owner (an API key); a job opened from a link is read-only (plasticdb_permission_denied).

  • job_shared() opens a job someone shared, from its link or token (no API key needed); the other functions then read it through the link.

  • jobs_list() lists your jobs, newest first.

  • job_provenance() is what the job ran against, to report with its results: the dataset release and release_source ("snapshot" for a past release's archived databases, "live" for the live one; the job's own, whichever client reads it), reference_sha256 (the DIAMOND database or HMM library searched), tool_versions, app_version and the server's full provenance record. job_replayed() is TRUE when the submission's idempotency key returned an existing job.

Usage

job_get(job, client = plasticdb_client())

job_status(job, client = plasticdb_client())

wait_job(
  job,
  timeout = NULL,
  poll_interval = 2,
  max_poll_interval = 30,
  error = TRUE,
  client = plasticdb_client()
)

job_results(job, limit = Inf, phylo = TRUE, client = plasticdb_client())

job_comparison(
  job,
  scov = NULL,
  qcov = NULL,
  bitscore = NULL,
  all_hits = FALSE,
  client = plasticdb_client()
)

job_download(
  job,
  path = ".",
  scov = NULL,
  qcov = NULL,
  bitscore = NULL,
  all_hits = FALSE,
  client = plasticdb_client()
)

job_share(
  job,
  expires_in_days = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

job_shares(job, client = plasticdb_client())

job_unshare(job, share, client = plasticdb_client())

job_shared(token_or_url, client = plasticdb_client())

jobs_list(limit = Inf, client = plasticdb_client())

job_provenance(job, client = plasticdb_client())

job_replayed(job)

Arguments

job

A plasticdb_job, or a job id.

client

A plasticdb_client().

timeout

Seconds to wait before signalling plasticdb_job_timeout; NULL waits as long as it takes.

poll_interval, max_poll_interval

The first and the longest wait between polls, in seconds.

error

Signal plasticdb_job_failed for a failed job; with FALSE it is returned.

limit

The most hits (or jobs) to return.

phylo

For a tree, also parse it with ape::read.tree().

scov, qcov, bitscore

Hit thresholds for the view (0 turns one off; NULL keeps the job's default).

all_hits

Count or write every hit, with no view.

path

A file, or a directory to save the server's file name in.

expires_in_days

Days the link lasts (1-365); NULL for as long as the job.

idempotency_key

As for submit_job().

share

A share (a row of job_shares(), or job_share()'s answer) or its numeric id.

token_or_url

A share link, or its token.

Value

job_get(), wait_job() and job_shared() a plasticdb_job; job_status() a string; job_results() a tibble with provenance (or a plasticdb_tree); job_comparison() a list with the genomes tibble; job_download() the path written; job_share() a list (token, url, ...); job_shares() and jobs_list() tibbles; job_unshare() TRUE, invisibly; job_provenance() a list; job_replayed() TRUE or FALSE.

See Also

jobs to submit one.

Examples

## A job opened from a share link needs no API key; an unknown link
## is a classed error:
res <- tryCatch(job_shared("https://v2.plasticdb.org/jobs/shared/no-such"),
    plasticdb_not_found = function(e) conditionMessage(e))
res

## Your own jobs need an API key; this uses your most recent finished job.
if (nzchar(Sys.getenv("PLASTICDB_API_KEY"))) {
    client <- plasticdb_client()
    recent <- jobs_list(limit = 5, client = client)
    recent <- recent[recent$status == "done", ]
    if (nrow(recent)) {
        job <- wait_job(recent$id[[1]], timeout = 3600, client = client)
        hits <- job_results(job, client = client)
        job_provenance(job)$reference_sha256
        job_download(job, tempdir(), client = client)
        link <- job_share(job, expires_in_days = 30, client = client)
        shared <- job_shared(link$url)
        job_results(shared)
    }
}

Run PlasticDB's analyses (jobs)

Description

Jobs run PlasticDB's analyses on the server: DIAMOND searches of genes, genomes and genome sets against PlasticDB's proteins, the matching of a table of taxa, pathway mapping, HMM screens and taxonomy trees. They need an API key (plasticdb_client(api_key = ) or PLASTICDB_API_KEY; without one the functions signal plasticdb_api_key_required before anything is sent). Reading a shared job (job_shared()) needs none.

Usage

submit_job(
  type,
  input = NULL,
  ...,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

annotate_gene(
  fasta,
  blast_type = NULL,
  organism_type = NULL,
  evalue = NULL,
  pident = NULL,
  include_variants = NULL,
  min_qcov = NULL,
  min_scov = NULL,
  min_bitscore = NULL,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

annotate_genome(
  fasta,
  blast_type = NULL,
  organism_type = NULL,
  evalue = NULL,
  pident = NULL,
  include_variants = NULL,
  min_qcov = NULL,
  min_scov = NULL,
  min_bitscore = NULL,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

compare_genomes(
  genomes,
  labels = NULL,
  blast_type = NULL,
  organism_type = NULL,
  evalue = NULL,
  pident = NULL,
  include_variants = NULL,
  min_qcov = NULL,
  min_scov = NULL,
  min_bitscore = NULL,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

annotate_list(
  table,
  genus_column = NULL,
  species_column = NULL,
  field_separator = NULL,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

pathway_analysis(
  fasta,
  target_plastic = NULL,
  blast_type = NULL,
  evalue = NULL,
  pident = NULL,
  min_step_identity = NULL,
  max_step_evalue = NULL,
  min_reference_coverage = NULL,
  min_query_coverage = NULL,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

hmm_screen(
  fasta,
  target_polymers = NULL,
  threshold_mode = NULL,
  evalue = NULL,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

build_tree(
  ...,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

search_sequence(
  sequence,
  blast_type = NULL,
  evalue = NULL,
  pident = NULL,
  include_variants = NULL,
  release = NULL,
  client = plasticdb_client()
)

Arguments

type

A job type: "annotate_gene", "annotate_genome", "compare_genomes", "annotate_list", "pathway_analysis", "hmm_screen" or "build_tree" (dashes may stand for underscores).

input

What the job reads: a FASTA input, a list of genomes (compare_genomes) or a taxa table (annotate_list); see Details. build_tree takes filters in ... instead.

...

For submit_job(), the job type's parameters (as named for its helper; labels for compare_genomes); for build_tree(), filters.

release

A release version to run against, instead of the client's.

idempotency_key

Identifies this submission (any 1-255 printable ASCII characters; default a new UUID): resending it returns the same job.

client

A plasticdb_client() with an API key.

fasta

A FASTA input (see Details).

blast_type

"blastp" (protein input, the default) or "blastx" (nucleotide input).

organism_type

Signal-peptide prediction for the hits: "no_signalp" (default), "gram-", "gram+", "arch" or "euk".

evalue

E-value threshold (default 1e-5). For hmm_screen() it applies only with threshold_mode = "evalue".

pident

Minimum percent identity (default 30).

include_variants

Also search engineered variants.

min_qcov, min_scov, min_bitscore

The default view of the results file and page: hide hits covering less than this % of the query / reference (min_scov defaults to 70), or under this bitscore. Every hit is stored; job_results() returns them all.

genomes

Two or more genome inputs (up to 20), as a list or a character vector of paths. Names label the genomes in the results.

labels

The genomes' labels, instead of their names. Otherwise a genome is labelled by its file name, else ⁠genome_<n>⁠.

table

A taxa table: a path, text or data frame.

genus_column, species_column

1-based columns holding the genus and species. They default to 7 and 8 (the server's layout), so pass them for any other table.

field_separator

"tab" (default), "comma" or "space".

target_plastic

The plastic whose degradation pathway is mapped (default "PET").

min_step_identity, max_step_evalue

When a hit calls a pathway step present: its minimum % identity (default 40) and maximum e-value (default 1e-10).

min_reference_coverage, min_query_coverage

And the minimum % of the reference enzyme (default 70) and of your protein (default 50) the alignment must cover.

target_polymers

Polymers to limit the HMM polymer summary to, e.g. c("PET", "PLA").

threshold_mode

"gathering" (default: each profile's calibrated cut-off) or "evalue" (evalue only).

sequence

One sequence: residues, one-record FASTA text, or a Biostrings sequence (or a set of one).

Details

submit_job() submits a job by its server name and returns a plasticdb_job at once; the typed helpers (annotate_gene(), annotate_genome(), compare_genomes(), annotate_list(), pathway_analysis(), hmm_screen(), build_tree()) name and document each job type's parameters. Then wait_job() polls until it finishes and job_results() returns its results. search_sequence() is synchronous: it searches one sequence now and returns the hits.

Inputs. A FASTA input is a file path (plain or gzip), FASTA text (a string starting with >, or a character vector of lines), a single line of residues, raw bytes, or a Biostrings::AAStringSet / Biostrings::DNAStringSet (use blast_type = "blastx" for nucleotide input). A taxa table is a path, text or a data frame (sent tab-separated, with its column names as the header row). Text and sets are written to temporary files; every upload is named after its contents (.gz exactly when it is gzip), as the server expects.

Releases. A pinned client (or ⁠release =⁠) runs the job against that release's archived reference databases; a job type or option the release cannot answer signals plasticdb_release_unsupported_filter.

Retries and idempotency. Each submission is sent with an Idempotency-Key header: idempotency_key, or a new UUID for each call, and the same key on every retry of that call. The server keeps a key for 24 hours per user and answers a repeat with the job the first request created (job_replayed() is then TRUE), so with an API key a submission is retried like a read: on a timeout, a dropped connection or a 5xx. Pass your own key when a script may be re-run after a crash: the re-run gets the first job back instead of a duplicate. When the retries run out, the error names the key to resubmit with (field idempotency_key). The same key with a different request signals plasticdb_idempotency_key_reused.

Limits. Submissions are rate-limited (30 an hour); a 429 is waited out when Retry-After is within max_retry_wait. A file over the size limit, or more than 20 genomes, is plasticdb_payload_too_large.

Value

A plasticdb_job: the job as the server describes it (a list: id, job_type, status, release, ...). search_sequence() returns a list with the hits (a tibble) and what they were searched against (release, release_source, reference_sha256, diamond_version).

See Also

wait_job(), job_results(), job_download(), job_share(), jobs_list(), job_provenance()

Examples

## Arguments are checked before anything is sent:
res <- tryCatch(submit_job("no_such_job", ">q\nMKVLAAGIVALLLAAGCSS"),
    plasticdb_argument_error = function(e) conditionMessage(e))
res

## Jobs need an API key (https://v2.plasticdb.org/profile/api-keys).
if (nzchar(Sys.getenv("PLASTICDB_API_KEY"))) {
    client <- plasticdb_client()
    genome <- tempfile(fileext = ".faa")
    seq <- paste0("MNFPRASRLMQAAVLGGLMAVSAAATAQ",
        "TNPYARGPNPTAASLEASAGPF")
    writeLines(c(">p1", seq), genome)
    job <- annotate_genome(genome, client = client)
    job <- wait_job(job, client = client)
    hits <- job_results(job, client = client)
    cmp <- compare_genomes(list(A = genome, B = genome), client = client)
    tree <- job_results(wait_job(build_tree(plastic = "PET", genus =
        "Pseudomonas", client = client), client = client), client = client)
    search_sequence("MNFPRASRLMQAAVLGGLMAVSAAATAQTNPYARGPNPTAASLEASAGPF",
        client = client)$hits
}

The most recent answer from the API

Description

The status, headers, URL and release of the last request this session made, for checking what answered (release, release_source, which is "snapshot" for a past release and "live" for the live database, unavailable_fields, the fields a release does not carry, etag, sha256 (a release artefact's own SHA-256), source_sha256 (the release Parquet files a pinned download was rendered from) and replayed (a submission's Idempotency-Key returned an existing job).

Usage

last_response()

Value

A list, or NULL before the first request.

See Also

provenance()

Examples

last_response()

Microorganisms

Description

Microorganisms with evidence of acting on plastics.

Usage

microorganisms_list(..., limit = Inf, client = plasticdb_client())

microorganisms_get(
  ref,
  evidence_scope = c("organism_or_enzyme", "whole_organism", "enzyme_only"),
  follow_merges = FALSE,
  client = plasticdb_client()
)

microorganisms_names(client = plasticdb_client())

microorganisms_lineage_levels(
  domain = NULL,
  kingdom = NULL,
  phylum = NULL,
  class = NULL,
  order = NULL,
  family = NULL,
  client = plasticdb_client()
)

microorganisms_taxonomy(rank, name, client = plasticdb_client())

Arguments

...

Filters (see Details), named as the API names them.

limit

The most records to return (Inf for all of them).

client

A plasticdb_client().

ref

An NCBI tax-id or a PlasticDB accession.

evidence_scope

"organism_or_enzyme" (default), "whole_organism" or "enzyme_only".

follow_merges

Return the survivor of a merged accession.

domain, kingdom, phylum, class, order, family

Taxa to narrow the levels.

rank, name

A rank ("genus") and a taxon name ("Pseudomonas").

Details

  • microorganisms_list() lists organisms matching the filters in ... (positive evidence unless ⁠polarity =⁠ says otherwise). Taxonomic ranks are filters too: genus = "Pseudomonas", class = "Bacilli" (or class_, as in the Python client).

  • microorganisms_get() returns one organism by NCBI tax-id or PlasticDB accession. evidence_scope = "whole_organism" keeps only assays on the organism itself, "enzyme_only" only the evidence of enzymes purified from it (interactions empty, indirect_interactions kept). A merged organism signals plasticdb_merged (kind "microorganism"; with follow_merges = TRUE the survivor is returned), a withdrawn one plasticdb_gone, as in proteins_get().

  • microorganisms_names() is every organism's id and name, microorganisms_lineage_levels() the taxon names at each rank (narrowed by the ranks given), and microorganisms_taxonomy() aggregate statistics for one taxon (a renamed taxon is followed). These three are live only.

Value

A tibble with provenance, or a plasticdb_record list.

Examples

microorganisms_list(genus = "Pseudomonas", plastic = "PET", limit = 3)

microorganisms_get(1547922)$name
microorganisms_taxonomy("genus", "Ideonella")$paper_total

Papers

Description

The literature behind the evidence.

Usage

papers_list(..., limit = Inf, client = plasticdb_client())

papers_get(paper_id, client = plasticdb_client())

papers_footprint(paper_id, client = plasticdb_client())

papers_export(
  paper_id = NULL,
  ...,
  format = c("bibtex", "ris"),
  path = NULL,
  client = plasticdb_client()
)

Arguments

...

Filters (see Details), named as the API names them.

limit

The most records to return (Inf for all of them).

client

A plasticdb_client().

paper_id

A paper's numeric id (NULL in papers_export() exports every paper matching the filters).

format

"bibtex" or "ris".

path

A file or directory to write the export to, or NULL to return the text.

Details

  • papers_list() lists papers matching the filters in ... (polarity has no default here: every paper).

  • papers_get() returns one paper with the organisms, proteins and variants it reports.

  • papers_footprint() is every record one paper contributed (live only).

  • papers_export() returns citations as BibTeX or RIS: one paper, or every paper matching the filters (live only). With path it writes them to a file and returns the path.

Value

A tibble with provenance, a plasticdb_record list, or text.

Examples

papers_list(protein = "PBFCTW", min_year = 2024, limit = 3)[, c("year",
    "title")]

papers_get(1262)$title
cat(papers_export(1262))

Degradation pathways

Description

Curated degradation pathways: ordered reaction steps from a polymer to its metabolites.

Usage

pathways_list(limit = Inf, client = plasticdb_client())

pathways_get(pathway_id, client = plasticdb_client())

pathways_for_plastic(plastic_id, client = plasticdb_client())

pathways_graph(plastic_id, pathway_id = NULL, client = plasticdb_client())

Arguments

limit

The most records to return (Inf for all of them).

client

A plasticdb_client().

pathway_id

A pathway's id (in pathways_graph(), NULL for all of the plastic's pathways).

plastic_id

A plastic's id (16 is PET).

Details

  • pathways_list() lists every pathway; pathways_get() returns one with its steps; pathways_for_plastic() every pathway that degrades one plastic.

  • pathways_graph() returns a plastic's pathways as a graph of compounds and reactions: a list of nodes and edges tibbles (each element's attributes, flattened), ready for igraph::graph_from_data_frame(g$edges, vertices = g$nodes).

Value

A tibble with provenance, a plasticdb_record list, or (for the graph) a list of two tibbles.

Examples

g <- pathways_graph(16)
g$edges[, c("source", "target", "label")]

pathways_list()

Connect to PlasticDB

Description

plasticdb_client() describes how to reach the API: which server, which dataset release to pin every read to, the API key, and where pinned answers are cached. Every function in the package takes client = plasticdb_client() as its last argument, so in most scripts you never call it yourself: set the options or environment variables once and every call follows them.

Usage

plasticdb_client(
  api_key = NULL,
  release = NULL,
  base_url = NULL,
  cache = NULL,
  timeout = NULL,
  max_retries = NULL,
  max_retry_wait = NULL
)

Arguments

api_key

An API key, needed only for jobs. Never stored in an option.

release

A dataset release version (e.g. "2026.50") to pin every read to, or NULL for the live database.

base_url

The API root.

cache

TRUE, FALSE, or a cache directory.

timeout

Request timeout in seconds.

max_retries

How many times a request is retried.

max_retry_wait

The longest wait (seconds) honoured before a retry.

Details

Each setting is resolved, first match wins, from the argument, then the R option, then the environment variable, then the default:

  • api_key: PLASTICDB_API_KEY; default none (reads are anonymous).

  • release: option plasticdb.release, PLASTICDB_RELEASE; default none (the live database).

  • base_url: option plasticdb.base_url, PLASTICDB_BASE_URL; default ⁠https://v2.plasticdb.org/api/v1⁠.

  • cache: option plasticdb.cache, PLASTICDB_CACHE_DIR; default TRUE.

  • timeout, max_retries, max_retry_wait: options plasticdb.timeout, plasticdb.max_retries, plasticdb.max_retry_wait; defaults 30 seconds, 3 and 60 seconds.

A pinned client sends ⁠?release=⁠ on every read; the server answers from that release's snapshot. Answers from a past release are immutable, so they are kept in a BiocFileCache::BiocFileCache() and reused without a request. Live answers (including the current release, which the live database serves) are never cached. cache = TRUE uses tools::R_user_dir("plasticdb", "cache"), a string names another directory, and FALSE turns caching off.

Rate-limited requests (429) are retried after the server's Retry-After when that is within max_retry_wait; requests are also retried with backoff on 5xx answers and connection errors.

Value

A plasticdb_client object (a list) to pass as ⁠client =⁠.

See Also

provenance(), cite(), releases_list()

Examples

client <- plasticdb_client(release = "2026.50", cache = FALSE)
client

## Or pin every call in a script:
old <- options(plasticdb.release = "2026.50")
plasticdb_client()$release
options(old)

Errors and warnings raised by plasticdb

Description

Every error this package raises from the API is a condition of class plasticdb_error, signalled with rlang::abort(), so it can be caught by class with tryCatch() or rlang::try_fetch(). The classes mirror the exceptions of the Python client, and a condition carries every class it belongs to: an unknown release is both a plasticdb_release_unknown and a plasticdb_not_found, and a merged record is a plasticdb_merged and a plasticdb_gone.

Details

Every condition has the fields status (the HTTP status), detail (the server's message), reason (the server's machine-readable reason, when it sent one: withdrawn, expired, archive_unavailable, timeout, ...), response_body and url. The classes, most general first (extra fields in brackets):

  • plasticdb_error: any of the below.

  • plasticdb_connection_error: the server could not be reached; plasticdb_timeout: a request timed out (also a connection error).

  • plasticdb_unexpected_response: an answer this package does not understand.

  • plasticdb_bad_request (400), plasticdb_authentication (401: no, invalid or expired API key), plasticdb_permission_denied (403), plasticdb_not_found (404), plasticdb_conflict (409), plasticdb_gone (410: a withdrawn record, with reason "withdrawn" and its accession; a variant is withdrawn with its parent protein), plasticdb_payload_too_large (413: a file over the size limit, or more than 20 genomes).

  • plasticdb_api_key_required: a job function was called without an API key; also plasticdb_authentication, signalled before anything is sent.

  • plasticdb_merged: the accession was merged (the server answers 301); also plasticdb_gone (merged_into, location, and kind, what the survivor is: "wild_type", "engineered" or "microorganism").

  • plasticdb_engineered_variant: a per-protein call given a variant's accession; also plasticdb_not_found (accession, location, and merged_into when the variant was merged too).

  • plasticdb_results_expired: a job's result files were deleted under the retention policy (410 expired); also plasticdb_gone (results_expired_at). Its record and hits stay readable.

  • plasticdb_validation (422): a parameter was invalid (errors, each with its loc, msg and type).

  • plasticdb_idempotency_key_reused: a submission's idempotency_key was used before for a different request; also plasticdb_validation.

  • plasticdb_rate_limit (429) beyond the retry budget (retry_after).

  • plasticdb_server_error (5xx; a sequence search past the server's 15 seconds is a 504 with reason "timeout"); plasticdb_service_unavailable (503, also a server error; retry_after, and reason: archive_unavailable while the dataset ZIP is built, index_unavailable or binary_unavailable for the sequence search).

  • plasticdb_job_error: a problem with a job (job); plasticdb_job_failed: it finished with status error (the message is the server's reason); plasticdb_job_timeout: wait_job() ran out of time (the job keeps running on the server). Both are job errors.

  • plasticdb_checksum: a download did not match its published SHA-256 (expected, actual).

  • plasticdb_release_error: a problem with the requested release (release, current_release, reason). Its subclasses: plasticdb_release_not_available, the release cannot answer at all, with plasticdb_release_unknown (404 unknown, also not found), plasticdb_release_no_artefacts (404 no_artefacts, also not found) and plasticdb_release_not_mounted (503 not_mounted, also service unavailable); and plasticdb_release_unsupported, the release cannot answer this call, with plasticdb_release_live_only (409 live_only, also a conflict) and plasticdb_release_unsupported_filter (422 release_unsupported, also validation; parameters).

A function given an argument it does not take (an unknown filter, say) signals plasticdb_argument_error before anything is sent.

Warnings: plasticdb_merged_warning when follow_merges = TRUE returns a merge survivor, and plasticdb_release_changed when the release changed while a list was being paged.

Value

Not a function: this page documents the condition classes.

Examples

## An unknown filter is refused before any request is sent:
res <- tryCatch(proteins_list(no_such_filter = 1),
    plasticdb_argument_error = function(e) conditionMessage(e))
cat(res)
res

Plastics

Description

The plastic vocabulary, with the organisms and proteins acting on each.

Usage

plastics_list(..., limit = Inf, client = plasticdb_client())

plastics_get(
  plastic_id,
  microorganism_limit = 25,
  microorganism_offset = 0,
  microorganism_sort_by = c("papers", "result", "name"),
  microorganism_sort_order = c("desc", "asc"),
  microorganism_polarity = c("positive", "negative", "inconclusive"),
  protein_limit = 25,
  protein_offset = 0,
  protein_sort_by = c("id", "papers", "result", "plasticdb_id", "accession", "name"),
  protein_sort_order = c("desc", "asc"),
  protein_polarity = c("positive", "negative", "inconclusive"),
  evidence_scope = c("organism_or_enzyme", "whole_organism"),
  client = plasticdb_client()
)

plastics_names(client = plasticdb_client())

Arguments

...

Filters (see Details), named as the API names them.

limit

The most records to return (Inf for all of them).

client

A plasticdb_client().

plastic_id

A plastic's numeric id (16 is PET).

microorganism_limit, microorganism_offset

The page of organisms embedded in the record.

microorganism_sort_by, microorganism_sort_order

How it is sorted.

microorganism_polarity

Which outcome it lists.

protein_limit, protein_offset

The page of proteins embedded in the record.

protein_sort_by, protein_sort_order

How it is sorted.

protein_polarity

Which outcome it lists.

evidence_scope

"organism_or_enzyme" or "whole_organism".

Details

  • plastics_list() lists plastics matching the filters in ... (has_evidence = TRUE: only those with evidence).

  • plastics_get() returns one plastic with one page each of its microorganisms and proteins. For every organism or protein acting on a plastic use microorganisms_list(plastic_id = ) or proteins_list(plastic = ) instead.

  • plastics_names() is every plastic's id and name (live only).

Value

A tibble with provenance, or a plasticdb_record list.

Examples

plastics_list(has_evidence = TRUE, limit = 5)[, c("id", "name")]

pet <- plastics_get(16, microorganism_limit = 2, protein_limit = 2)
pet$full_name

Proteins

Description

Wild-type proteins and engineered variants linked to plastic degradation, with the evidence behind each link.

Usage

proteins_list(..., limit = Inf, client = plasticdb_client())

proteins_get(
  accession,
  view = c("summary", "full"),
  include_sequenceless = FALSE,
  follow_merges = FALSE,
  client = plasticdb_client()
)

proteins_interactions(
  accession,
  evidence_level = c("all", "direct", "indirect"),
  level = c("interaction", "experiment", "observation"),
  include_sequenceless = FALSE,
  limit = Inf,
  kind = NULL,
  client = plasticdb_client()
)

proteins_kinetics(accession, limit = Inf, client = plasticdb_client())

proteins_properties(accession, limit = Inf, client = plasticdb_client())

proteins_variants(
  accession,
  include_sequenceless = FALSE,
  limit = Inf,
  client = plasticdb_client()
)

proteins_sequences(..., limit = Inf, client = plasticdb_client())

proteins_fasta(ref, client = plasticdb_client())

proteins_structure(ref, path = NULL, client = plasticdb_client())

proteins_lineage(accession, client = plasticdb_client())

proteins_engineered_parents(
  updated_since = NULL,
  limit = Inf,
  client = plasticdb_client()
)

Arguments

...

Filters (see Details), named as the API names them.

limit

The most records to return (Inf for all of them).

client

A plasticdb_client().

accession, ref

A protein accession or numeric id.

view

"summary" (the default, as on the server since 2.89.0) or "full". The summary carries the record's own fields and counts (how many interactions, variants, kinetics and properties it has) but not those lists, and is much smaller for well-studied enzymes; "full" embeds interactions, variants, kinetics and properties. Use proteins_interactions(), proteins_variants(), proteins_kinetics() and proteins_properties() to read the lists as tibbles.

include_sequenceless

Include records without a sequence.

follow_merges

Return the survivor of a merged accession.

evidence_level

"all" (the default), "direct" (assayed on the protein itself) or "indirect" (credited through its engineered variants) interactions.

level

One row per "interaction", "experiment" or "observation". Deeper levels repeat the interaction's columns and add ⁠experiment.*⁠ (and ⁠observation.*⁠) columns.

kind

Deprecated: the old name of evidence_level. It is sent as evidence_level, never alongside it; different values in both signal plasticdb_argument_error.

path

For proteins_structure(), a file or directory to write to.

updated_since

Only records changed since this time.

Details

  • proteins_list() lists proteins matching the filters in ... (wild types and variants; ⁠kind =⁠ narrows). Like every entity list, only records with a positive result are listed unless ⁠polarity =⁠ or include_negative = TRUE says otherwise.

  • proteins_get() returns one protein by accession (PB..., any case) or numeric id, by default as the "summary" view (with counts); view = "full" embeds its interactions, variants, kinetics and properties. An engineered variant's accession returns the variant, as variants_get() does. A merged accession signals plasticdb_merged naming the survivor (merged_into); with follow_merges = TRUE the survivor is returned instead, with a plasticdb_merged_warning. A withdrawn record signals plasticdb_gone (reason "withdrawn"). The per-protein tables of a merged accession signal plasticdb_merged too (its location is the survivor's table); given a variant's accession they signal plasticdb_engineered_variant, since variants have none (its record carries them: variants_get()).

  • proteins_interactions() is the protein's evidence spine: "direct" (assayed on it) or "indirect" (via its organism) interactions, as one row per interaction, experiment or observation (level).

  • proteins_kinetics() and proteins_properties() are the kinetic parameters and stability/activity properties of a protein and its variants; proteins_variants() its engineered variants, with sequences.

  • proteins_sequences() lists proteins and returns their sequences as an Biostrings::AAStringSet (names are accessions, the list columns are in mcols()).

  • proteins_fasta() and proteins_structure() are one protein's FASTA record and primary structure (PDB text, or a file with path); proteins_lineage() a wild type with every variant engineered from it; proteins_engineered_parents() the wild types that have variants. A variant's accession gives the variant's FASTA record or structure. proteins_fasta() answers a pinned release too (a merged accession's redirect is live only; a snapshot answers 404 for a ref it does not hold). The structure, lineage and engineered-parents calls are live only: a pinned client gets plasticdb_release_live_only (for a pinned structure use downloads_structure()).

proteins_list(include_sequence = TRUE) adds each record's sequence column (a variant's own); proteins_sequences() uses it, so it needs no second download.

Filters are the API's own query parameters, with the same meaning on every function: plastic, include_subtypes, microorganism, polarity, include_negative, evidence_method, min_year, max_year, updated_since, sort_by, sort_order and so on. An unknown name signals plasticdb_argument_error naming the valid ones; an unknown value is a server 422 (plasticdb_validation).

Tables have one flat row per record: nested objects become parent.child columns (source_microorganism.name, paper.doi), lists of plain values become list columns, and per-plastic evidence becomes plastics_positive, plastics_negative and plastics_inconclusive.

Value

Lists return a tibble::tibble() with the provenance (release, source, URL, total) in attr(x, "plasticdb"), see provenance(). Single records return a plasticdb_record list with the API's nesting. proteins_sequences() returns an Biostrings::AAStringSet, proteins_fasta() a string.

See Also

variants_list(), evidence_interactions(), as_aastringset()

Examples

pet <- proteins_list(plastic = "PET", kind = "wild_type", limit = 5)
pet[, c("accession", "name", "source_microorganism.name")]
provenance(pet)$total

petase <- proteins_get("PBFCTW")
petase$name
petase$counts
proteins_interactions("PBFCTW", level = "observation", limit = 3)
proteins_sequences(plastic = "PHB", kind = "wild_type", min_year = 2025)

Where results came from

Description

Record this alongside an analysis: the dataset release that answered, its source ("snapshot" for a past release, "live" for the live database, which also serves the current release), whether the client was pinned, the server and package versions, and the data licence.

Usage

provenance(x = NULL, client = plasticdb_client())

Arguments

x

A result from this package, or NULL for the client's.

client

A plasticdb_client().

Details

Given a result (a tibble, record or AAStringSet from this package), provenance() returns what answered that call, including the request URL, whether it came from the cache, and the server's total for a list. Without one it describes the client, making a request first when this session has made none, so the release is known.

Value

A named list.

See Also

cite(), last_response()

Examples

tbl <- tibble::tibble(id = 1L)
attr(tbl, "plasticdb") <- list(release = "2026.50",
    release_source = "snapshot", pinned = TRUE)
provenance(tbl)$release

Dataset releases

Description

Releases are the named, citable versions of the data (e.g. "2026.50"), each with a DOI, a frozen copy of the data and the reference databases the analyses searched. Release metadata describes every release, so these calls are never pinned.

Usage

releases_current(client = plasticdb_client())

releases_get(version, client = plasticdb_client())

releases_list(limit = Inf, client = plasticdb_client())

releases_status(client = plasticdb_client())

Arguments

client

A plasticdb_client().

version

A release version.

limit

The most records to return (Inf for all of them).

Details

  • releases_current(): the release the server is serving now (version is NULL before the first one).

  • releases_get(): one release with its artefacts. An unknown version signals plasticdb_release_unknown (also a plasticdb_not_found).

  • releases_list(): every completed release, newest first.

  • releases_status(): whether a release is being cut right now.

Value

A plasticdb_record list, or (releases_list()) a tibble.

Examples

current <- releases_current()
current$version  # NULL before the first release
current$license

Full-text search

Description

Search every record type at once (live only: a past release cannot be searched, so a pinned client gets plasticdb_release_live_only).

Usage

search_hits(q, limit = Inf, client = plasticdb_client())

search_grouped(q, limit = 10, client = plasticdb_client())

search_autocomplete(q, client = plasticdb_client())

Arguments

q

The search text.

limit

For search_hits(), the most hits to return; for search_grouped(), the hits per record type.

client

A plasticdb_client().

Details

  • search_hits() returns ranked hits, one row each, with entity_type (protein, microorganism, plastic, paper, ...), route_key (a string: the accession or id to pass to the matching ⁠*_get()⁠ function; a variant's is its accession, for variants_get()) and rank. (It is not called search(), which would mask base::search().)

  • search_grouped() returns the top limit hits (at most 100) for each record type: a list with the overall total, a groups tibble (each type's total and the query that lists more) and the hits.

  • search_autocomplete() returns name suggestions, as the site's search box shows them.

Value

A tibble with provenance, or (search_grouped()) a list.

Examples

search_hits("cutinase", limit = 5)[, c("entity_type", "route_key", "name")]

search_grouped("PETase", limit = 1)$groups

The server's application version

Description

The server's application version

Usage

server_version(client = plasticdb_client())

Arguments

client

A plasticdb_client().

Value

A string, or NULL when the server cannot be reached.

Examples

server_version()

Database statistics

Description

Summary statistics of the live database (live only).

Usage

stats_summary(
  evidence_scope = c("organism_or_enzyme", "whole_organism", "enzyme_only"),
  client = plasticdb_client()
)

stats_protein_activity(client = plasticdb_client())

stats_charts(
  evidence_scope = c("organism_or_enzyme", "whole_organism"),
  client = plasticdb_client()
)

stats_by_country(client = plasticdb_client())

Arguments

evidence_scope

"organism_or_enzyme" or "whole_organism"; stats_summary() also takes "enzyme_only" (count only the organisms credited through an enzyme).

client

A plasticdb_client().

Details

  • stats_summary(): headline counts (proteins, microorganisms, plastics, papers, pathways).

  • stats_protein_activity(): how many proteins degrade, fail to degrade, or are untested.

  • stats_charts(): the data behind the site's statistics charts, and stats_by_country() record counts by the corresponding author's country; both as a named list of tibbles.

Value

A plasticdb_record list, or a named list of tibbles.

Examples

stats_summary()$proteins

stats_by_country()$microorganisms

Engineered variants

Description

Engineered variants of wild-type proteins: their mutations, engineering method and evidence. Records, FASTA and lists answer a pinned release too; only the structure is live only (a pinned client gets plasticdb_release_live_only).

Usage

variants_list(..., limit = Inf, client = plasticdb_client())

variants_get(
  ref,
  include_sequenceless = FALSE,
  follow_merges = FALSE,
  client = plasticdb_client()
)

variants_of(parent, limit = Inf, client = plasticdb_client())

variants_sequences(..., limit = Inf, client = plasticdb_client())

variants_fasta(ref, client = plasticdb_client())

variants_structure(ref, path = NULL, client = plasticdb_client())

Arguments

...

Filters (see Details), named as the API names them.

limit

The most records to return (Inf for all of them).

client

A plasticdb_client().

ref

A variant accession or numeric id.

include_sequenceless

Include records without a sequence.

follow_merges

Return the survivor of a merged accession.

parent

The parent protein's accession.

path

For proteins_structure(), a file or directory to write to.

Details

  • variants_list() lists variants matching the filters in ... (proteins_list(kind = "engineered"); see proteins for the filters).

  • variants_get() returns one variant by accession or numeric id. Merges behave as in proteins_get(); a withdrawn variant (also one whose parent protein was withdrawn) signals plasticdb_gone. On a past release the record comes from its snapshot: a variant the release did not contain is plasticdb_not_found (merges are not followed there), include_sequenceless = TRUE is plasticdb_release_unsupported_filter, and the fields it cannot fill are in last_response()$unavailable_fields.

  • variants_of() lists the variants of one parent protein, with sequences (the same as proteins_variants()).

  • variants_sequences() returns the listed variants' sequences as an Biostrings::AAStringSet.

  • variants_fasta() and variants_structure() are one variant's FASTA record and structure coordinates.

Value

As for proteins: tibbles with provenance, plasticdb_record lists, an Biostrings::AAStringSet, or text.

Examples

variants_of("PBFCTW", limit = 3)[, c("accession", "variant_name")]

variants_get("PBDTZX")$variant_name
variants_sequences(plastic = "PET", limit = 5)