Quick start: PlasticDB from R

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 sequence                                          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 sequence                                          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=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: Etc/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.41.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.81.9    jquerylib_0.1.4      Seqinfo_1.3.2       
#> [10] IRanges_2.47.5       yaml_2.3.12          fastmap_1.2.0       
#> [13] XVector_0.53.0       R6_2.6.1             generics_0.1.4      
#> [16] httr2_1.3.0          knitr_1.52           BiocGenerics_0.59.13
#> [19] tibble_3.3.1         maketools_1.3.2      bslib_0.12.0        
#> [22] pillar_1.11.1        rlang_1.3.0          utf8_1.2.6          
#> [25] testthat_3.3.2       cachem_1.1.0         xfun_0.62           
#> [28] sass_0.4.10          sys_3.4.3            otel_0.3.0          
#> [31] cli_3.6.6            magrittr_2.0.5       digest_0.6.39       
#> [34] lifecycle_1.0.5      S4Vectors_0.51.10    vctrs_0.7.3         
#> [37] evaluate_1.0.5       glue_1.8.1           buildtools_1.0.0    
#> [40] stats4_4.6.2         rmarkdown_2.32       tools_4.6.2         
#> [43] pkgconfig_2.0.3      htmltools_0.5.9