Skip to contents

Why pin a release

The live PlasticDB database changes every week: papers are curated, records are merged, corrected or withdrawn. An analysis that reads the live database today may give a different answer next month. PlasticDB therefore publishes numbered dataset releases (2026.50, …), each a frozen copy of the data with a DOI. A client pinned to a release sends ?release= on every read, and the server answers from that release’s snapshot, so the script gives the same answer for as long as the release exists.

This vignette walks through a reproducible analysis: choosing a release, pinning a script to it, recording what answered, downloading the release’s checksummed files, running analysis jobs against the release’s archived reference databases, and citing it.

Note. The server has not published its first dataset release yet: releases_list() is empty, and a pinned call to any release signals plasticdb_release_unknown. The code below shows how a pinned analysis will look once releases exist; it uses the version 2026.50 as an example and is not run here.

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

Choose a release

releases_list() lists the published releases, newest first, and releases_current() names the current one (the live database serves it). Until the first release is published both are empty:

releases_list()
#> # A tibble: 0 × 0
releases_current()
#> <plasticdb_record> 
#>   $version: NULL
#>   $released_at: NULL
#>   $doi: NULL
#>   $snapshot_release_label: NULL
#>   $citation: NULL
#>   $license: CC BY 4.0
#>   $license_spdx: CC-BY-4.0
#>   $license_url: https://creativecommons.org/licenses/by/4.0/
#>   $paper_citation: Gambarini V, Pantos O, Kingsbury JM, Weaver L, Handley KM...
#>   $paper_doi: 10.1093/database/baac008

Each release record carries its DOI, the data version it was cut from and the artefacts it published (releases_get("2026.50")). An unknown version is a classed error you can handle:

res <- tryCatch(releases_get("2026.99"),
    plasticdb_release_unknown = function(e) e$reason)
res
#> [1] "unknown"

Pin a script

Pin every call in a script with one option (or the PLASTICDB_RELEASE environment variable), or pin a single client and pass it as client =:

options(plasticdb.release = "2026.50")
pet <- proteins_list(plastic = "PET", kind = "wild_type")
client <- plasticdb_client(release = "2026.50", cache = FALSE)
client
#> <plasticdb_client>
#>   base_url: https://v2.plasticdb.org/api/v1
#>   release:  2026.50
#>   api_key:  none
#>   cache:    off

Every result carries its provenance. A pinned answer comes from the release’s snapshot (release_source is "snapshot"); fields a release does not carry are listed in unavailable_fields:

pet <- proteins_list(plastic = "PET", kind = "wild_type", client = client)
provenance(pet)[c("release", "release_source", "unavailable_fields")]

A few calls cannot be answered from a past release (full-text search, the change feed, statistics, protein structures) and signal plasticdb_release_live_only; a filter the release cannot evaluate signals plasticdb_release_unsupported_filter. Neither silently falls back to the live database.

Answers from a past release never change, so they are kept in a BiocFileCache (by default under tools::R_user_dir("plasticdb", "cache")) and reused without a request. A pinned table download is revalidated with one conditional request (its ETag) and, if the server cannot be reached, the cached copy is used.

Download the release’s files

A release publishes its tables as Parquet files, the reference databases its jobs search, the structure coordinates and a MANIFEST.json, each with a SHA-256. downloads_release_file() checks every file against the checksum the release published and the one the server sends; a mismatch signals plasticdb_checksum and keeps nothing:

files <- downloads_artefacts(client = client)
files[, c("path", "kind", "size")]
path <- downloads_release_file("parquet/proteins.parquet", tempdir(),
    client = client)
manifest <- downloads_manifest(client = client)

Filtered tables come from the release too, as CSV, JSON or FASTA:

fasta <- downloads_proteins(tempdir(), format = "fasta", client = client)

Run analyses against the release

Jobs (?jobs) run PlasticDB’s analyses on the server and need an API key (create one at https://v2.plasticdb.org/profile/api-keys). A pinned client runs them against the release’s archived DIAMOND databases, HMM library and tables, so the hits are reproducible as well:

client <- plasticdb_client(api_key = Sys.getenv("PLASTICDB_API_KEY"),
    release = "2026.50")
job <- annotate_genome("genome.faa.gz", idempotency_key = "genome-42-run-1",
    client = client)
job <- wait_job(job, timeout = 3600, client = client)
hits <- job_results(job, client = client)

Inputs are file paths (plain or gzip), FASTA text, or Biostrings sets:

proteins <- Biostrings::readAAStringSet("proteins.faa")
steps <- job_results(wait_job(pathway_analysis(proteins,
    target_plastic = "PET", client = client), client = client),
    client = client)

The idempotency_key makes the submission safe to repeat: a script re-run after a crash (or a retry after a dropped connection) gets the first job back instead of starting a duplicate.

Record what each job ran against. job_provenance() gives the release, the SHA-256 of the reference database searched and the tool versions; the downloaded results file carries the same as # header lines:

job_provenance(job)[c("release", "release_source", "reference_sha256",
    "tool_versions")]
job_download(job, "results/", client = client)

Cite the release

The data is licensed CC BY 4.0. cite() returns the release’s DOI and the PlasticDB paper as a bibentry; a pinned client cites its release:

cite(client = client)
toBibtex(cite(client = client))

provenance() without a result describes the client: the release, whether it was pinned, and the server and package versions. Keep it with the results, together with the session information below.

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] vctrs_0.7.3         cli_3.6.6           knitr_1.52         
#>  [4] rlang_1.3.0         xfun_0.62           otel_0.3.0         
#>  [7] httptest2_1.2.2     textshaping_1.0.5   jsonlite_2.0.0     
#> [10] glue_1.8.1          htmltools_0.5.9     ragg_1.5.2         
#> [13] sass_0.4.10         brio_1.1.5          rmarkdown_2.32     
#> [16] tibble_3.3.1        evaluate_1.0.5      jquerylib_0.1.4    
#> [19] fastmap_1.2.0       yaml_2.3.12         lifecycle_1.0.5    
#> [22] httr2_1.3.0         bookdown_0.48       BiocManager_1.30.27
#> [25] compiler_4.6.2      fs_2.1.0            pkgconfig_2.0.3    
#> [28] testthat_3.3.2      systemfonts_1.3.3   digest_0.6.39      
#> [31] R6_2.6.1            pillar_1.11.1       magrittr_2.0.5     
#> [34] bslib_0.12.0        tools_4.6.2         pkgdown_2.2.1      
#> [37] cachem_1.1.0        desc_1.4.3