Skip to content

Models

Every record the API returns is a pydantic model; fields the SDK does not know are kept (model_extra). The full list is in plasticdb.models.

models

Typed response models. Every model keeps fields it does not declare.

AnnotatedTaxon

Bases: PlasticDBModel

One row of an annotate_list result: your columns, then PlasticDB's.

The fields are the downloaded table's own column names (row["Genus"]).

BindingAssay

Bases: PlasticDBModel

A binding (adsorption) assay of a protein on a plastic, with its measurements.

Change

Bases: PlasticDBModel

One record that changed: status is updated, merged or removed.

Construct

Bases: PlasticDBModel

An expressed construct: the sequence a paper actually assayed (tags, fusions, frames).

CurrentRelease

Bases: PlasticDBModel

GET /releases/current. Every release field is None before the first release.

Bases: PlasticDBModel

Per-plastic evidence summary for one record: counts by outcome.

EngineeringLineage

Bases: PlasticDBModel

A wild-type protein with every engineered variant derived from it.

Experiment

Bases: PlasticDBModel

One assay behind an interaction: its method, conditions and observations.

ExperimentRecord

Bases: PlasticDBModel

One experiment as a flat row; interaction_id points at its interaction.

GenomeComparison

Bases: PlasticDBModel

The genome x plastic matrix of a compare_genomes job (rows() / to_pandas()).

table

The genomes as a table: one row per genome.

GenomeComparisonRow

Bases: PlasticDBModel

One genome of a comparison: hit counts per plastic, raw and normalised.

As a table row, counts and normalised become counts.<plastic> / normalised.<plastic> columns.

GroupedSearch

Bases: PlasticDBModel

/search/grouped: the top hits per entity type.

HitEvidence

Bases: PlasticDBModel

Evidence counts, by outcome, for one plastic on a hit's protein or variant.

Interaction

Bases: PlasticDBModel

One actor tested on one plastic in one paper, with its outcome (result).

experiment_rows

experiment_rows() -> list[dict[str, Any]]

One row per experiment, prefixed experiment., with this interaction's columns.

observation_rows

observation_rows() -> list[dict[str, Any]]

One row per observation (experiment.* and observation.* columns).

InteractionRecord

Bases: PlasticDBModel

One interaction as a flat row (the release table's columns), without its children.

actor_type says which of the actor columns are set (a microorganism strain, a protein or an engineered variant). Experiments and observations are listed separately (client.evidence.experiments, .observations).

JobHit

Bases: PlasticDBModel

One hit of a search job (annotate, compare genomes, HMM screen).

For compare_genomes source_label names the genome. For hmm_screen the subject is a profile (subject_seq_id is its NAME, profile_accession its ACC) and calibration_status says whether its cut-off separates the polymer classes.

HMM hits are not alignments: pident, length, qcov and scov are always None (never 0), old jobs included, so identity or coverage filters do not apply to them. evalue and bitscore are the full-sequence values; domain_score is the best domain's bit score, hmm_from/hmm_to its span on the profile and env_from/env_to its envelope on the submitted sequence (1-based, inclusive). The HMM fields are None on DIAMOND hits and on HMM jobs run before server 2.90.0. evidence summarises, per plastic, the evidence on the protein (or variant) the hit landed on; as a table row it becomes plastics_positive / _negative / _inconclusive.

protein_plastics property

protein_plastics: dict[str, list[str]]

The hit protein's own per-plastic outcome lists (its degradation_links).

JobHitOrganism

Bases: PlasticDBModel

The organism a hit protein was isolated from.

JobHitProtein

Bases: PlasticDBModel

The PlasticDB protein a hit landed on.

JobHitVariant

Bases: PlasticDBModel

The engineered variant a hit landed on.

JobInfo

Bases: PlasticDBModel

A job as the API describes it (JobRead, or JobDetail with its hits).

release / release_source / reference_sha256 / tool_versions are the provenance to report with the results; result_metadata holds the job type's own summary (polymer_hits, step_table, taxa, …) and the full provenance record under provenance.

JobShare

Bases: PlasticDBModel

A share link as its owner sees it later (never the token).

JobShareCreated

Bases: JobShare

A new share link. token is shown once only: keep url now.

url is the results page anyone with the link can open; pass it (or the token) to client.jobs.shared() to read the job without a key.

Kinetics

Bases: PlasticDBModel

Enzyme kinetics: kcat, Km, kcat/Km and Vmax as reported and normalised.

Microorganism

Bases: MicroorganismSummary

One microorganism with its evidence (GET /microorganisms/{ref}).

lineage_ranks

lineage_ranks() -> dict[str, str]

lineage (rank:name; …) as {rank: name}; a repeated rank keeps its first.

MicroorganismSummary

Bases: PlasticDBModel

A /microorganisms list item (MicroorganismListItem).

NamedRef

Bases: PlasticDBModel

An {id, name} option (/plastics/names, /microorganisms/names).

Observation

Bases: PlasticDBModel

One measured value of an experiment.

ObservationRecord

Bases: PlasticDBModel

One measured value as a flat row; product_compound_ids is a list.

Paper

Bases: PaperSummary

One paper (GET /papers/{id}) with the organisms, proteins and variants it reports.

PaperFootprint

Bases: PlasticDBModel

Everything one paper contributed (GET /papers/{id}/footprint).

PaperRef

Bases: PlasticDBModel

A paper as embedded in other records (PaperRead).

PaperSummary

Bases: PlasticDBModel

A /papers list item.

Pathway

Bases: PlasticDBModel

A curated degradation pathway: ordered reaction steps from polymer to metabolites.

PathwayGraph

Bases: PlasticDBModel

Cytoscape-style {nodes, edges}: each element's attributes are under data.

to_networkx

to_networkx() -> Any

A networkx.DiGraph (needs networkx); compartments become node attributes.

PathwayStep

Bases: PlasticDBModel

One step of a pathway analysis: whether your proteins cover it, and the best hit.

Plastic

Bases: PlasticSummary

One plastic (GET /plastics/{id}), with one page of its organisms and proteins.

The embedded microorganisms and proteins are paged by the server (microorganism_limit / protein_limit); the *_count fields are the totals.

PlasticDBModel

Bases: BaseModel

Base for response models. Unknown fields are kept: the API only ever adds them.

to_row

to_row() -> dict[str, Any]

One flat table row: nested objects become parent.child columns.

Lists of plain values stay lists; lists of objects are kept as lists of dicts unless the model summarises them (for example a protein's degradation_links become plastics_positive / plastics_negative).

PlasticRef

Bases: PlasticDBModel

A plastic as embedded in other records: id, name and abbreviation.

PlasticSummary

Bases: PlasticDBModel

A /plastics list item, with how many organisms and proteins act on it.

Preparation

Bases: PlasticDBModel

The prepared material an assay used: host, purification, tags, modifications.

Properties

Bases: PlasticDBModel

Enzyme properties: optimal pH and temperature, Tm, half-life, specific activity.

Protein

Bases: ProteinSummary

One protein (GET /proteins/{accession}), in the summary or full view.

view says which. The summary (the default) leaves interactions, indirect_interactions, variants, kinetics and properties empty and gives their sizes in counts; view="full" fills the lists (counts is then empty).

to_fasta

to_fasta() -> str

This protein as one FASTA record (>accession name); empty without a sequence.

ProteinSummary

Bases: PlasticDBModel

A /proteins list item (ProteinListItem): a wild type or an engineered variant.

List items carry no sequence unless the list asked for include_sequence=True (to_fasta() does that itself).

seq_id property

seq_id: str

The record's id in the server's FASTA downloads.

Release

Bases: PlasticDBModel

One dataset release (GET /releases item, GET /releases/{version}).

ReleaseArtefacts

Bases: PlasticDBModel

The immutable, checksummed files a release published.

ReleaseStatus

Bases: PlasticDBModel

GET /releases/status: whether a release is being cut right now.

SearchHit

Bases: PlasticDBModel

One search result. route_key is what the record's get() takes.

SequenceHit

Bases: PlasticDBModel

One DIAMOND hit of a synchronous sequence search (BLAST outfmt 6 columns).

SequenceSearchResult

Bases: PlasticDBModel

A synchronous sequence search: the hits, and what they were searched against.

Stats

Bases: PlasticDBModel

Headline counts of the public data (GET /stats).

Structure

Bases: PlasticDBModel

A structure record (experimental PDB entry or predicted model).

Bases: PlasticDBModel

A structure attached to a construct (/constructs/{id}/structures).

TaxonomyGroup

Bases: PlasticDBModel

Aggregate statistics for one taxon (/microorganisms/taxonomy/{rank}/{name}).

TaxonomyTree

Bases: PlasticDBModel

A build_tree result: a Newick cladogram and the organism x plastic matrix.

data maps each organism name to {plastic: "yes" | "no"} over columns. to_pandas() gives it as a table; to_biopython() parses the Newick with Bio.Phylo (needs plasticdb[bio]).

rows

rows() -> list[dict[str, Any]]

One row per organism: organism then one True/False column per plastic.

to_biopython

to_biopython() -> Any

The tree as a Bio.Phylo tree.

Variant

Bases: VariantSummary

One engineered variant with its evidence (GET /variants/{ref}).

VariantSummary

Bases: PlasticDBModel

An engineered variant as listed under its parent (ProteinVariantRead).

Unlike a ProteinSummary, it carries its sequence.