Skip to content

Reproducibility with pinned releases

PlasticDB publishes numbered dataset releases (e.g. 2026.50), each with a DOI, a frozen copy of the data and the reference databases the analyses searched. The live database moves on; a release does not.

Pin one

import plasticdb

client = plasticdb.Client(release="2026.50")  # or PLASTICDB_RELEASE=2026.50
proteins = client.proteins.list(plastic="PET")  # answered from that release
plasticdb proteins list --plastic PET --release 2026.50 -o pet.tsv
# or: export PLASTICDB_RELEASE=2026.50

release= is sent as ?release= on every read. The server answers from the release's snapshot and says so in the X-PlasticDB-Release and X-PlasticDB-Release-Source headers. An unknown version raises UnknownReleaseError (a NotFoundError). List what exists with client.releases.list() or plasticdb releases list.

A past release holds only published records: merged and withdrawn ones are not in it, so a pinned get() on such an accession is a NotFoundError.

Check what answered

client.proteins.list(plastic="PET").total
resp = client.last_response  # the most recent answer
resp.release, resp.release_source, resp.pinned  # "2026.50", "snapshot", True
resp.unavailable_fields  # fields this release does not carry, if any

release_source is snapshot for a past release and live for the live database (which also serves the current release).

Record it with your results

prov = client.provenance()
prov.to_dict()
# release, release_source, pinned, base_url, sdk_version, server_version, data_license

plasticdb provenance prints the same as JSON. Jobs carry their own provenance: the release, the SHA-256 of the reference database searched and the tool versions.

Cite it

print(client.cite())  # a pinned client cites its release; an unpinned one the current release

cite() returns a Citation (dataset, release, doi, paper, paper_doi, license, license_url); str() of it is the text to paste. If the server cannot be reached the citation still names the paper. On the command line: plasticdb cite --release 2026.50 --format text|bibtex|json. The data is CC BY 4.0.

Cache

client = plasticdb.Client(release="2026.50", cache_dir="~/.cache/plasticdb")

With cache_dir, answers from a past release's snapshot are kept on disk indefinitely (a release is immutable) and reused without a request. Live answers are never cached, and neither are answers of an unpinned client. A pinned table download (downloads.proteins() …) is kept with the server's ETag: using the copy again costs one conditional request that answers 304 without a body (and if the server cannot be reached, the copy is used). The download's X-PlasticDB-Source-SHA256, the release Parquet artefact(s) it was rendered from as listed in MANIFEST.json, is client.last_response.source_sha256. Release artefacts (below) are verified and always cacheable. On the command line use --cache-dir or PLASTICDB_CACHE_DIR.

Download the release itself

client.downloads.artefacts()  # files the release published
client.downloads.release_file("parquet/proteins.parquet", "data/")  # verified against SHA-256
client.downloads.manifest()  # MANIFEST.json: every file, hash, size, licence
client.downloads.structure(1234, "structures/")  # one structure of the release (gzipped PDB)

Each artefact is checked against the SHA-256 the release published and the one the server sends with it (X-PlasticDB-SHA256, also its ETag); a mismatch with either raises ChecksumError and keeps nothing. A cached artefact is verified locally and needs no request. On the command line, plasticdb download dataset --release 2026.50 -o data/ fetches and verifies every artefact.

What cannot be pinned

Some endpoints are computed from the live database. A pinned client gets a LiveOnlyError (HTTP 409) from them rather than a silently live answer:

  • Search: client.search(...), .grouped(), .autocomplete()
  • Statistics: client.stats.*
  • The change feed: client.changes()
  • Structures and protein FASTA of single records: proteins.fasta/structure, variants.structure. For a pinned structure use downloads.structure(); for pinned sequences, a protein list's to_fasta() (below) or variants.fasta(), which is pinnable.
  • Lineages: proteins.lineage(), proteins.engineered_parents()
  • Name lists and taxonomy: microorganisms.names/lineage_levels/taxonomy, plastics.names
  • Paper footprints and citation exports: papers.footprint(), papers.export()
  • Live bulk files: downloads.dataset() (ZIP/JSON) and downloads.search(); for a release use downloads.release_file()

Use a second, unpinned plasticdb.Client() for these, and say so in your methods.

A pinned protein list's to_fasta() does work: it downloads that release's whole proteins.fasta (kept in cache_dir) and keeps the listed records.

Filters and options a release cannot answer (for example any filter on a past release's table downloads) raise UnsupportedFilterError (HTTP 422); it is also a ValidationError.

Jobs on a release

A pinned client, or release= on the call, runs analyses against that release's archived DIAMOND databases and HMM library. See Jobs.