Skip to contents

R client for the PlasticDB API: microorganisms and proteins linked to plastic biodegradation, and the evidence behind them. It mirrors the Python client, plasticdb-py, and targets Bioconductor.

Pre-release (0.99.x). Every public data endpoint, release pinning, provenance and citation, and analysis jobs (with an API key).

Install

Documentation: https://victorgambarini.github.io/plasticdb/ (the Python client’s is at https://victorgambarini.github.io/plasticdb-py/).

# install.packages("pak")
pak::pak("VictorGambarini/plasticdb")
# or: remotes::install_github("VictorGambarini/plasticdb")

A Bioconductor release is planned; then BiocManager::install("plasticdb") will do.

Quick start

library(plasticdb)

# Proteins with positive evidence on PET: a tibble, one flat row per protein
pet <- proteins_list(plastic = "PET", kind = "wild_type")
provenance(pet)$total       # the server's total
pet$source_microorganism.name

# ...and their sequences, as a Biostrings::AAStringSet named by accession
seqs <- proteins_sequences(plastic = "PET", kind = "wild_type")

# One record, with its evidence
petase <- proteins_get("PBFCTW")
petase$name

# The evidence spine: interaction -> experiment -> observation
obs <- evidence_interactions("PBFCTW", level = "observation")

# Engineered variants (with sequences), organisms, plastics, papers
as_aastringset(proteins_variants("PBFCTW"))
microorganisms_list(genus = "Pseudomonas", plastic = "PET")
plastics_get(16, protein_limit = 10)
papers_list(protein = "PBFCTW", min_year = 2020)

# Search, pathways, statistics, the change feed
search_hits("cutinase", limit = 20)
pathways_graph(16)$edges
stats_summary()
feed <- changes(since = Sys.Date() - 7)

# Files
downloads_proteins(tempdir(), format = "fasta", plastic = "PET")
downloads_dataset(tempdir(), max_wait = 300)

Jobs

With an API key (PLASTICDB_API_KEY, created at https://v2.plasticdb.org/profile/api-keys), run PlasticDB’s analyses on the server. Inputs are file paths (plain or gzip), FASTA text or Biostrings sets:

job <- annotate_genome("genome.faa.gz", release = "2026.50")
job <- wait_job(job, timeout = 3600)
hits <- job_results(job)          # every hit, paged: a tibble
job_provenance(job)$reference_sha256
job_download(job, "results/")     # the TSV with its provenance lines

compare_genomes(list(K12 = "k12.faa", O157 = "o157.faa"))
annotate_list(read.csv("taxa.csv"), genus_column = 1, species_column = 2)
pathway_analysis(Biostrings::readAAStringSet("prot.faa"), target_plastic = "PLA")
hmm_screen("prot.faa", target_polymers = c("PET", "PLA"))
tree <- job_results(wait_job(build_tree(plastic = "PET", genus = "Pseudomonas")))
tree$newick; tree$matrix          # tree$phylo with ape installed
search_sequence("MNFPRASRLMQAAVLGGLMAVSAAATAQTNPYARGPNPT")$hits

link <- job_share(job, expires_in_days = 30)
job_results(job_shared(link$url)) # anyone with the link; no key needed

Each submission carries an Idempotency-Key (pass idempotency_key = to choose it), reused on every retry, so a retried or re-run submission returns the first job (job_replayed()) instead of a duplicate.

Function names follow the Python client: client.proteins.list() is proteins_list(), client.evidence.interactions() is evidence_interactions(), and so on. The one exception is client.search(), which is search_hits() here so as not to mask base::search().

Lists, filters and tables

List functions fetch every page (500 records a request) unless limit = caps them. Filters are the API’s own query parameters, passed by name, with the same meaning everywhere: plastic, include_subtypes, microorganism, polarity, include_negative, evidence_method, min_year/max_year, updated_since, sort_by/sort_order… An unknown name is a plasticdb_argument_error that lists the valid ones; an unknown value is a server 422 (plasticdb_validation). Entity lists default to records with a positive result, as on the website.

Tables are tibbles: nested objects become parent.child columns, lists of values become list columns, and per-plastic evidence becomes plastics_positive / plastics_negative / plastics_inconclusive. Single records (*_get()) are lists with the API’s nesting.

Configuration and reproducibility

Every function takes client = plasticdb_client(). Its settings come from the argument, else an R option, else an environment variable:

Argument Option Environment variable Default
api_key PLASTICDB_API_KEY none (reads are anonymous)
release plasticdb.release PLASTICDB_RELEASE none (live database)
base_url plasticdb.base_url PLASTICDB_BASE_URL https://v2.plasticdb.org/api/v1
cache plasticdb.cache PLASTICDB_CACHE_DIR TRUE (tools::R_user_dir("plasticdb", "cache"))
timeout, max_retries, max_retry_wait plasticdb.timeout, … 30 s, 3, 60 s

So options(plasticdb.release = "2026.50") pins a whole script, and plasticdb_client(release = "2026.30") one call. A pinned read sends ?release= and is answered from that release’s snapshot; provenance(x) says what answered (release, source, URL, cache, total) and provenance() adds the server and package versions. Answers from a past release are cached in a BiocFileCache and reused; live answers are never cached. Rate-limited requests (429) wait for Retry-After; 5xx answers and connection errors are retried with backoff.

Errors

Errors are classed conditions (rlang::abort()), mirroring the Python exceptions: plasticdb_not_found, plasticdb_gone, plasticdb_merged (field merged_into), plasticdb_engineered_variant, plasticdb_authentication, plasticdb_api_key_required, plasticdb_job_failed, plasticdb_job_timeout, plasticdb_results_expired, plasticdb_idempotency_key_reused, plasticdb_payload_too_large, plasticdb_validation, plasticdb_rate_limit (retry_after), plasticdb_server_error, plasticdb_checksum and the release errors (plasticdb_release_unknown, plasticdb_release_live_only, plasticdb_release_unsupported_filter, …). All are plasticdb_error. See ?"plasticdb-conditions".

tryCatch(proteins_get("PBGQPC"), plasticdb_merged = function(e) e$merged_into)
proteins_get("PBGQPC", follow_merges = TRUE)   # the survivor, with a warning

Citation and licence

The code is MIT-licensed. The PlasticDB data is licensed CC BY 4.0: cite the dataset release you used, plus the PlasticDB paper. cite() returns both as a bibentry (toBibtex(cite()) for BibTeX):

Gambarini V, Pantos O, Kingsbury JM, Weaver L, Handley KM, Lear G (2022). PlasticDB: a database of microorganisms and proteins linked to plastic biodegradation. Database, 2022:baac008. https://doi.org/10.1093/database/baac008

citation("plasticdb") cites this package.

Provenance of the code

Assisted-by: Claude (Anthropic). Most of this package’s code, tests and documentation were written with the Claude Code assistant, directed and reviewed by the maintainer, who is responsible for it. Commits it helped write carry a Co-Authored-By: Claude trailer. No third-party code is copied into the package; all of it is distributed under the package’s MIT licence.

Development

roxygen2::roxygenise()
testthat::test_local()            # offline: httptest2 fixtures
rcmdcheck::rcmdcheck(args = "--as-cran")
BiocCheck::BiocCheck(`new-package` = TRUE)

Rscript tools/capture-fixtures.R re-captures the test fixtures from the live anonymous API; Rscript tools/make-job-fixtures.R rewrites the synthetic job fixtures (jobs need an API key) from the Python client’s. tests/testthat/contract/sdk-v1.json is the server’s SDK contract (/api/v1/openapi.sdk.json); test-contract.R checks every call the package makes against it.