Reproducible analyses with a pinned release
Victor Gambarini
2026-11-19
Source:vignettes/reproducible.Rmd
reproducible.RmdWhy 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.
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/baac008Each 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: offEvery 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:
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