Quick start: PlasticDB from R
Victor Gambarini
2026-11-19
Source:vignettes/plasticdb.Rmd
plasticdb.RmdIntroduction
PlasticDB is a curated database of microorganisms and proteins linked to plastic biodegradation, and of the evidence behind each link: every interaction (one organism or protein tested on one plastic in one paper), the experiments that tested it, and the observations each measured. The plasticdb package reads it from R:
- catalogue tables (proteins, microorganisms, plastics, papers, evidence) as tibbles, one flat row per record;
- protein sequences as Biostrings
AAStringSetobjects, named by accession, with the record’s columns inmcols(); - files (tables, FASTA, the whole dataset, a release’s archived reference databases) on disk, with pinned and release files cached by BiocFileCache.
Reads need no account. The data is licensed CC BY 4.0: see Citing the data.
Installation
if (!requireNamespace("BiocManager", quietly = TRUE)) {
install.packages("BiocManager")
}
BiocManager::install("plasticdb")Until it is in Bioconductor, install it from GitHub:
BiocManager::install("VictorGambarini/plasticdb").
Proteins
proteins_list() takes the API’s own filters as named
arguments: here, the wild-type proteins with positive evidence on PET.
limit caps how many records are fetched; leave it out to
get every page.
pet <- proteins_list(plastic = "PET", kind = "wild_type", limit = 3)
pet[, c("accession", "name", "source_microorganism.name")]
#> # A tibble: 3 × 3
#> accession name source_microorganism.name
#> <chr> <chr> <chr>
#> 1 PB8CAZ E4 Altericroceibacterium indicum
#> 2 PBTEJE SdPETase Saccharopolyspora dendranthemae
#> 3 PB394E PET93 Maribacter dokdonensisNested objects become parent.child columns and
per-plastic evidence becomes list columns:
pet$plastics_positive[[1]]
#> [1] "PET"Every result records what answered it. Without a pinned release the live database answers, and the server’s total tells how many records match:
prov <- provenance(pet)
prov[c("release", "release_source", "pinned", "total")]
#> $release
#> NULL
#>
#> $release_source
#> [1] "live"
#>
#> $pinned
#> [1] FALSE
#>
#> $total
#> [1] 468One record keeps the API’s nesting:
petase <- proteins_get("PBFCTW")
petase$name
#> [1] "PETase"
nchar(petase$sequence)
#> [1] 290
petase$source_microorganism$name
#> [1] "Pseudideonella sakaiensis"Sequences
proteins_sequences() takes the same filters and returns
an AAStringSet:
phb <- proteins_sequences(plastic = "PHB", kind = "wild_type",
min_year = 2025)
phb
#> AAStringSet object of length 3:
#> width seq names
#> [1] 418 MDSTAPPVGRPLPATVISLAATL...NVFVTTSLTETSPGHWEHTPGAC PB9N84
#> [2] 300 MIKPATMEFVSLSNGETIAYQEV...GHSPFIDCLDVFIKHVEDWLEQK PB22RP
#> [3] 212 MFVKKRSLQILIALALVIGSMAF...LLTSSQVKGYIKEGLNGGGQNTN PBXKHG
S4Vectors::mcols(phb)[, c("name", "source_microorganism.name")]
#> DataFrame with 3 rows and 2 columns
#> name source_microorganism.name
#> <character> <character>
#> PB9N84 PHBD Nocardiopsis dassonv..
#> PB22RP BtPhaZ Bacillus thuringiensis
#> PBXKHG TGL (triacylglycerol.. Bacillus sp. (in: fi..Tables that carry a sequence column, such as a protein’s
engineered variants, convert with as_aastringset():
variants <- proteins_variants("PBFCTW", limit = 2)
as_aastringset(variants)
#> AAStringSet object of length 2:
#> width seq names
#> [1] 290 MNFPRASRLMQAAVLGGLMAVSA...YSTFACENPNSTAVSDFRTANCS PBVPYT
#> [2] 290 MNFPRASRLMQAAVLGGLMAVSA...YSTFACENPNSTAVSDFRTANCS PB6CC8Biostrings::writeXStringSet(phb, "phb.fasta") writes a
FASTA file.
The evidence
evidence_interactions() (the same as
proteins_interactions()) returns a protein’s interactions.
level = "observation" gives one row per measured value,
repeating the interaction’s and experiment’s columns:
obs <- evidence_interactions("PBFCTW", level = "observation", limit = 3)
dim(obs)
#> [1] 10 57
head(grep("^(experiment|observation)\\.", names(obs), value = TRUE))
#> [1] "experiment.id" "experiment.method"
#> [3] "experiment.temperature" "experiment.temperature_unit"
#> [5] "experiment.ph" "experiment.buffer"Organisms, plastics and papers work the same way:
microorganisms_list(genus = "Pseudomonas", limit = 2)[, c("name", "tax_id")]
#> # A tibble: 2 × 2
#> name tax_id
#> <chr> <int>
#> 1 Pseudomonas abyssi 170540
#> 2 Pseudomonas aeruginosa 287
plastics_list(limit = 2)[, c("name", "full_name", "protein_count")]
#> # A tibble: 2 × 3
#> name full_name protein_count
#> <chr> <chr> <int>
#> 1 (PCL)2-b-PEG-b-(PCL)2 Four-arm star block copolymer — PEG core … 2
#> 2 ABS Acrylonitrile-butadiene-styrene (SAN matr… 0Search, pathways and statistics
search_hits("cutinase", limit = 3)[, c("entity_type", "route_key", "name")]
#> # A tibble: 3 × 3
#> entity_type route_key name
#> <chr> <chr> <chr>
#> 1 paper 1260 Ueda, H., Tabata, J., Seshime, Y., Masaki, K., Sameshim…
#> 2 paper 107 Liu, Y., Liu, C., Liu, H., Zeng, Q., Tian, X., Long, L.…
#> 3 paper 118 Liu, F., Tao, Y., Ding, Y., Cui, T., Liang, X., & Li, Q…
g <- pathways_graph(16)
head(g$edges[, c("source", "target", "label")], 3)
#> # A tibble: 3 × 3
#> source target label
#> <chr> <chr> <chr>
#> 1 compound-1@extracellular compound-3@extracellular PETase
#> 2 compound-1@extracellular compound-2@extracellular PETase
#> 3 compound-1@extracellular compound-4@extracellular PETase
stats_summary()$proteins
#> [1] 3835Reproducible analyses: pin a release
PlasticDB publishes numbered dataset releases, each with a DOI and a
frozen copy of the data. The live database moves on; a release does not.
Pin one for a whole script with an option (or
PLASTICDB_RELEASE), or for one call with a client:
options(plasticdb.release = "2026.50")
pet <- proteins_list(plastic = "PET")
provenance(pet)$release_source # "snapshot": answered from the release
client <- plasticdb_client(release = "2026.50")
proteins_list(plastic = "PET", client = client)Answers from a past release never change, so they are cached on disk
(tools::R_user_dir("plasticdb", "cache"), or
plasticdb_client(cache =)) and reused without a request;
live answers are never cached. Searches and a few other live-only calls
cannot be answered from a past release and signal
plasticdb_release_live_only. Releases are listed by
releases_list(). The vignette Reproducible analyses
with a pinned release
(vignette("reproducible", package = "plasticdb")) walks
through a whole pinned analysis.
Analysis jobs
With an API key, the package also runs PlasticDB’s analyses on the
server: annotate_gene(), annotate_genome() and
compare_genomes() search your sequences against PlasticDB’s
proteins with DIAMOND, annotate_list() matches a table of
taxa, pathway_analysis() maps proteins onto a plastic’s
degradation pathway, hmm_screen() screens them against
polymer-specific HMM profiles and build_tree() draws a
taxonomy tree. Inputs are file paths, FASTA text or
Biostrings sets; wait_job() waits for a job
and job_results() returns its results as a tibble. See
?jobs.
Errors
Errors are classed conditions, so they can be handled precisely. A merged accession names its survivor:
res <- tryCatch(proteins_get("PBGQPC"),
plasticdb_merged = function(e) e$merged_into)
res
#> [1] "PBMW9H"follow_merges = TRUE returns the survivor instead, with
a warning. See ?"plasticdb-conditions" for every class.
Citing the data
The PlasticDB data is licensed CC BY 4.0.
cite() returns the dataset release and the PlasticDB paper
as a bibentry (a pinned client cites its release):
cite()
#> PlasticDB (2026). "PlasticDB (live database; no dataset release
#> named)." Accessed 2026-11-19. Data licence: CC BY 4.0
#> (https://creativecommons.org/licenses/by/4.0/).,
#> <https://v2.plasticdb.org/>.
#>
#> 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.
#> doi:10.1093/database/baac008
#> <https://doi.org/10.1093/database/baac008>.toBibtex(cite()) gives BibTeX. To cite this package, use
citation("plasticdb").
Session information
sessionInfo()
#> R version 4.6.2 (2026-10-29)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 LTS
#>
#> Matrix products: default
#> BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so; LAPACK version 3.12.0
#>
#> locale:
#> [1] LC_CTYPE=C.UTF-8 LC_NUMERIC=C LC_TIME=C.UTF-8
#> [4] LC_COLLATE=C.UTF-8 LC_MONETARY=C.UTF-8 LC_MESSAGES=C.UTF-8
#> [7] LC_PAPER=C.UTF-8 LC_NAME=C LC_ADDRESS=C
#> [10] LC_TELEPHONE=C LC_MEASUREMENT=C.UTF-8 LC_IDENTIFICATION=C
#>
#> time zone: UTC
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats graphics grDevices utils datasets methods base
#>
#> other attached packages:
#> [1] plasticdb_0.99.6 BiocStyle_2.40.0
#>
#> loaded via a namespace (and not attached):
#> [1] jsonlite_2.0.0 compiler_4.6.2 BiocManager_1.30.27
#> [4] httptest2_1.2.2 crayon_1.5.3 brio_1.1.5
#> [7] Biostrings_2.80.2 jquerylib_0.1.4 Seqinfo_1.2.0
#> [10] IRanges_2.46.0 systemfonts_1.3.3 textshaping_1.0.5
#> [13] yaml_2.3.12 fastmap_1.2.0 XVector_0.52.0
#> [16] R6_2.6.1 generics_0.1.4 httr2_1.3.0
#> [19] knitr_1.52 BiocGenerics_0.58.1 tibble_3.3.1
#> [22] bookdown_0.48 desc_1.4.3 bslib_0.12.0
#> [25] pillar_1.11.1 rlang_1.3.0 utf8_1.2.6
#> [28] testthat_3.3.2 cachem_1.1.0 xfun_0.62
#> [31] fs_2.1.0 sass_0.4.10 otel_0.3.0
#> [34] cli_3.6.6 pkgdown_2.2.1 magrittr_2.0.5
#> [37] digest_0.6.39 lifecycle_1.0.5 S4Vectors_0.50.3
#> [40] vctrs_0.7.3 evaluate_1.0.5 glue_1.8.1
#> [43] ragg_1.5.2 stats4_4.6.2 rmarkdown_2.32
#> [46] tools_4.6.2 pkgconfig_2.0.3 htmltools_0.5.9