| 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 |
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.
as_aastringset(x, ...)as_aastringset(x, ...)
x |
A tibble with a |
... |
Unused. |
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.
An Biostrings::AAStringSet with metadata columns.
variants <- tibble::tibble(id = 1:2, accession = c("PB0001", NA), variant_name = c("A", "B"), sequence = c("MKV", "MKL")) as_aastringset(variants)variants <- tibble::tibble(id = 1:2, accession = c("PB0001", NA), variant_name = c("A", "B"), sequence = c("MKV", "MKL")) as_aastringset(variants)
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.
changes(since, entity_type = NULL, limit = Inf, client = plasticdb_client())changes(since, entity_type = NULL, limit = Inf, client = plasticdb_client())
since |
A time (POSIXct, Date or ISO 8601 string). |
entity_type |
|
limit |
The most records to return ( |
client |
A tibble; its provenance also carries since and as_of.
feed <- changes(since = Sys.Date() - 7, limit = 10) table(feed$status) provenance(feed)$as_offeed <- changes(since = Sys.Date() - 7, limit = 10) table(feed$status) provenance(feed)$as_of
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).
cite(client = plasticdb_client())cite(client = plasticdb_client())
client |
To cite this R package itself, use citation("plasticdb").
A bibentry with two entries: the dataset and the paper.
ref <- cite() ref toBibtex(ref)ref <- cite() ref toBibtex(ref)
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.
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() )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() )
path |
A file, or an existing directory to save the file in. |
format |
The file format. |
... |
Filters, as for the matching |
client |
|
max_wait |
Seconds to keep waiting while the dataset ZIP is built. |
q |
The search text. |
release |
A release version, or |
file |
An artefact's path within the release, e.g.
|
structure_id |
A structure's numeric id. |
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.
The path written (downloads_artefacts(): a tibble;
downloads_manifest(): a list).
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)))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)))
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.
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())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())
protein |
A protein accession. |
evidence_level |
|
level |
One row per |
include_sequenceless |
Include records without a sequence. |
limit |
The most records to return ( |
kind |
Deprecated: the old name of |
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. |
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.
A tibble with provenance, or a plasticdb_record list.
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)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)
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.
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)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)
job |
A |
client |
|
timeout |
Seconds to wait before signalling |
poll_interval, max_poll_interval
|
The first and the longest wait between polls, in seconds. |
error |
Signal |
limit |
The most hits (or jobs) to return. |
phylo |
For a tree, also parse it with |
scov, qcov, bitscore
|
Hit thresholds for the view ( |
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); |
idempotency_key |
As for |
share |
A share (a row of |
token_or_url |
A share link, or its token. |
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.
jobs to submit one.
## 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) } }## 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) } }
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.
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() )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() )
type |
A job type: |
input |
What the job reads: a FASTA input, a list of genomes
( |
... |
For |
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 |
fasta |
A FASTA input (see Details). |
blast_type |
|
organism_type |
Signal-peptide prediction for the hits:
|
evalue |
E-value threshold (default 1e-5). For |
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 ( |
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 |
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 |
|
target_plastic |
The plastic whose degradation pathway is mapped
(default |
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.
|
threshold_mode |
|
sequence |
One sequence: residues, one-record FASTA text, or a Biostrings sequence (or a set of one). |
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.
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).
wait_job(), job_results(), job_download(), job_share(),
jobs_list(), job_provenance()
## 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 }## 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 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).
last_response()last_response()
A list, or NULL before the first request.
last_response()last_response()
Microorganisms with evidence of acting on plastics.
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())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())
... |
Filters (see Details), named as the API names them. |
limit |
The most records to return ( |
client |
|
ref |
An NCBI tax-id or a PlasticDB accession. |
evidence_scope |
|
follow_merges |
Return the survivor of a merged accession. |
domain, kingdom, phylum, class, order, family
|
Taxa to narrow the levels. |
rank, name
|
A rank ( |
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.
A tibble with provenance, or a plasticdb_record list.
microorganisms_list(genus = "Pseudomonas", plastic = "PET", limit = 3) microorganisms_get(1547922)$name microorganisms_taxonomy("genus", "Ideonella")$paper_totalmicroorganisms_list(genus = "Pseudomonas", plastic = "PET", limit = 3) microorganisms_get(1547922)$name microorganisms_taxonomy("genus", "Ideonella")$paper_total
The literature behind the evidence.
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() )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() )
... |
Filters (see Details), named as the API names them. |
limit |
The most records to return ( |
client |
|
paper_id |
A paper's numeric id ( |
format |
|
path |
A file or directory to write the export to, or |
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.
A tibble with provenance, a plasticdb_record list, or text.
papers_list(protein = "PBFCTW", min_year = 2024, limit = 3)[, c("year", "title")] papers_get(1262)$title cat(papers_export(1262))papers_list(protein = "PBFCTW", min_year = 2024, limit = 3)[, c("year", "title")] papers_get(1262)$title cat(papers_export(1262))
Curated degradation pathways: ordered reaction steps from a polymer to its metabolites.
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())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())
limit |
The most records to return ( |
client |
|
pathway_id |
A pathway's id (in |
plastic_id |
A plastic's id (16 is PET). |
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).
A tibble with provenance, a plasticdb_record list, or (for the
graph) a list of two tibbles.
g <- pathways_graph(16) g$edges[, c("source", "target", "label")] pathways_list()g <- pathways_graph(16) g$edges[, c("source", "target", "label")] pathways_list()
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.
plasticdb_client( api_key = NULL, release = NULL, base_url = NULL, cache = NULL, timeout = NULL, max_retries = NULL, max_retry_wait = NULL )plasticdb_client( api_key = NULL, release = NULL, base_url = NULL, cache = NULL, timeout = NULL, max_retries = NULL, max_retry_wait = NULL )
api_key |
An API key, needed only for jobs. Never stored in an option. |
release |
A dataset release version (e.g. |
base_url |
The API root. |
cache |
|
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. |
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.
A plasticdb_client object (a list) to pass as client =.
provenance(), cite(), releases_list()
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)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)
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.
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.
Not a function: this page documents the condition classes.
## 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## 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
The plastic vocabulary, with the organisms and proteins acting on each.
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())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())
... |
Filters (see Details), named as the API names them. |
limit |
The most records to return ( |
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 |
|
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).
A tibble with provenance, or a plasticdb_record list.
plastics_list(has_evidence = TRUE, limit = 5)[, c("id", "name")] pet <- plastics_get(16, microorganism_limit = 2, protein_limit = 2) pet$full_nameplastics_list(has_evidence = TRUE, limit = 5)[, c("id", "name")] pet <- plastics_get(16, microorganism_limit = 2, protein_limit = 2) pet$full_name
Wild-type proteins and engineered variants linked to plastic degradation, with the evidence behind each link.
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() )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() )
... |
Filters (see Details), named as the API names them. |
limit |
The most records to return ( |
client |
|
accession, ref
|
A protein accession or numeric id. |
view |
|
include_sequenceless |
Include records without a sequence. |
follow_merges |
Return the survivor of a merged accession. |
evidence_level |
|
level |
One row per |
kind |
Deprecated: the old name of |
path |
For |
updated_since |
Only records changed since this time. |
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.
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.
variants_list(), evidence_interactions(), as_aastringset()
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)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)
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.
provenance(x = NULL, client = plasticdb_client())provenance(x = NULL, client = plasticdb_client())
x |
A result from this package, or |
client |
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.
A named list.
tbl <- tibble::tibble(id = 1L) attr(tbl, "plasticdb") <- list(release = "2026.50", release_source = "snapshot", pinned = TRUE) provenance(tbl)$releasetbl <- tibble::tibble(id = 1L) attr(tbl, "plasticdb") <- list(release = "2026.50", release_source = "snapshot", pinned = TRUE) provenance(tbl)$release
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.
releases_current(client = plasticdb_client()) releases_get(version, client = plasticdb_client()) releases_list(limit = Inf, client = plasticdb_client()) releases_status(client = plasticdb_client())releases_current(client = plasticdb_client()) releases_get(version, client = plasticdb_client()) releases_list(limit = Inf, client = plasticdb_client()) releases_status(client = plasticdb_client())
client |
|
version |
A release version. |
limit |
The most records to return ( |
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.
A plasticdb_record list, or (releases_list()) a tibble.
current <- releases_current() current$version # NULL before the first release current$licensecurrent <- releases_current() current$version # NULL before the first release current$license
Search every record type at once (live only: a past release cannot be
searched, so a pinned client gets plasticdb_release_live_only).
search_hits(q, limit = Inf, client = plasticdb_client()) search_grouped(q, limit = 10, client = plasticdb_client()) search_autocomplete(q, client = plasticdb_client())search_hits(q, limit = Inf, client = plasticdb_client()) search_grouped(q, limit = 10, client = plasticdb_client()) search_autocomplete(q, client = plasticdb_client())
q |
The search text. |
limit |
For |
client |
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.
A tibble with provenance, or (search_grouped()) a list.
search_hits("cutinase", limit = 5)[, c("entity_type", "route_key", "name")] search_grouped("PETase", limit = 1)$groupssearch_hits("cutinase", limit = 5)[, c("entity_type", "route_key", "name")] search_grouped("PETase", limit = 1)$groups
The server's application version
server_version(client = plasticdb_client())server_version(client = plasticdb_client())
client |
A string, or NULL when the server cannot be reached.
server_version()server_version()
Summary statistics of the live database (live only).
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())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())
evidence_scope |
|
client |
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.
A plasticdb_record list, or a named list of tibbles.
stats_summary()$proteins stats_by_country()$microorganismsstats_summary()$proteins stats_by_country()$microorganisms
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).
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())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())
... |
Filters (see Details), named as the API names them. |
limit |
The most records to return ( |
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 |
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.
As for proteins: tibbles with provenance, plasticdb_record
lists, an Biostrings::AAStringSet, or text.
variants_of("PBFCTW", limit = 3)[, c("accession", "variant_name")] variants_get("PBDTZX")$variant_name variants_sequences(plastic = "PET", limit = 5)variants_of("PBFCTW", limit = 3)[, c("accession", "variant_name")] variants_get("PBDTZX")$variant_name variants_sequences(plastic = "PET", limit = 5)