Skip to contents

Introduction

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 AAStringSet objects, named by accession, with the record’s columns in mcols();
  • 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").

library(plasticdb)
#> 
#> Attaching package: 'plasticdb'
#> The following object is masked from 'package:utils':
#> 
#>     cite

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 dokdonensis

Nested 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] 468

One 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 PB6CC8

Biostrings::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…             0

Search, 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] 3835

Reproducible 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