Skip to content

Resources

Each is an attribute of Client: client.proteins, client.variants, and so on.

Releases

Releases(client: Client)

Bases: Resource

Dataset releases: the named, citable versions of the data.

current

current() -> CurrentRelease

The release the server is serving now. version is None before the first.

get

get(version: str) -> Release

One release with its artefacts.

An unknown version raises UnknownReleaseError (a NotFoundError).

list

list(*, page_size: int = 50, limit: int | None = None) -> Collection[Release]

Every completed release, newest first.

status

status() -> ReleaseStatus

Whether a release is being cut right now.

Proteins

Proteins(client: Client)

Bases: Resource

Wild-type proteins and engineered variants (/proteins).

get

get(accession: str | int, *, view: Literal['full', 'summary'] = 'summary', include_sequenceless: bool = False, follow_merges: bool = False) -> Protein | Variant

One protein by accession (PB…, any case) or numeric id.

An engineered variant's accession returns the Variant (the server redirects there). A merged accession raises MergedError naming the survivor; with follow_merges=True the survivor is returned instead, with a MergedRecordWarning. A withdrawn record raises GoneError. The default view="summary" (the server's, since 2.89.0) leaves out the per-record evidence lists (interactions, indirect_interactions, variants, kinetics, properties) and gives their sizes in counts; page them with interactions, variants, kinetics and properties. view="full" embeds them (up to 12.5 MB for a well-studied enzyme).

list

list(*, page_size: int | None = None, limit: int | None = None, **filters: Unpack[ProteinListFilters]) -> ProteinCollection[ProteinSummary]

Proteins matching the filters (wild types and variants; kind= narrows).

Like every entity list, only records with a positive result are listed unless polarity= or include_negative=True says otherwise. include_sequence=True adds each item's sequence (a variant's own); .to_fasta() / .to_biopython() then need no second download.

interactions

interactions(accession: str, *, evidence_level: EvidenceLevel | None = None, include_sequenceless: bool = False, page_size: int | None = None, limit: int | None = None, kind: EvidenceLevel | None = None) -> InteractionCollection[Interaction]

The protein's evidence: direct (assayed on it), indirect (via its organism).

evidence_level is all (default), direct or indirect. kind= is the deprecated pre-0.1.0 name of the same argument: it emits a DeprecationWarning and is sent to the server as evidence_level (never both).

kinetics

kinetics(accession: str, *, page_size: int | None = None, limit: int | None = None) -> Collection[Kinetics]

Kinetic parameters measured on the protein and its variants.

properties

properties(accession: str, *, page_size: int | None = None, limit: int | None = None) -> Collection[Properties]

Stability and activity properties (optimal pH/temperature, Tm, half-life).

variants

variants(accession: str, *, include_sequenceless: bool = False, page_size: int | None = None, limit: int | None = None) -> Collection[VariantSummary]

The engineered variants of one wild-type protein, with their sequences.

fasta

fasta(ref: str | int) -> str

One protein's FASTA record, with the server's annotated header (pinnable).

With a pinned release the record comes from that snapshot; a ref not in it is a plain NotFoundError (no merge redirect). A variant's accession gives the variant's record (fasta).

structure

structure(ref: str | int, path: str | PathLike[str] | None = None) -> str | Path

The primary structure's PDB coordinates (live only).

Returns the text, or writes it to path (a file or a directory) and returns the path. A variant's accession gives the variant's structure. For a pinned release use client.downloads.structure().

lineage

lineage(accession: str) -> EngineeringLineage

A wild-type protein with every variant engineered from it (live only).

engineered_parents

engineered_parents(*, updated_since: str | None = None, page_size: int | None = None, limit: int | None = None) -> Collection[ProteinSummary]

Wild-type proteins that have engineered variants (live only).

Variants

Variants(client: Client)

Bases: Resource

Engineered variants: records, FASTA and lists answer a pinned release too.

get

get(ref: str | int, *, include_sequenceless: bool = False, follow_merges: bool = False) -> Variant

One variant by accession or numeric id.

Merges behave as in get; a withdrawn variant (also one whose parent protein was withdrawn) raises GoneError. On a past release the record comes from its snapshot: a variant the release did not contain is a NotFoundError (merges are not followed there), include_sequenceless=True raises UnsupportedFilterError, and the fields it cannot fill are in client.last_response.unavailable_fields.

list

list(*, page_size: int | None = None, limit: int | None = None, **filters: Unpack[VariantListFilters]) -> ProteinCollection[ProteinSummary]

Engineered variants matching the filters (/proteins?kind=engineered).

of

of(parent: str, *, page_size: int | None = None, limit: int | None = None) -> Collection[VariantSummary]

The variants of one parent protein, with sequences (same as proteins.variants).

fasta

fasta(ref: str | int) -> str

One variant's FASTA record with the server's annotated header (pinnable).

structure

structure(ref: str | int, path: str | PathLike[str] | None = None) -> str | Path

The variant's structure coordinates (live only); see structure.

Microorganisms

Microorganisms(client: Client)

Bases: Resource

Microorganisms with evidence of acting on plastics.

get

get(ref: str | int, *, evidence_scope: EvidenceScope = 'organism_or_enzyme', follow_merges: bool = False) -> Microorganism

One microorganism by NCBI tax-id or PlasticDB accession.

evidence_scope="whole_organism" keeps only assays on the organism itself, "enzyme_only" only the evidence of enzymes purified from it (interactions empty, indirect_interactions kept). A merged organism raises MergedError (or, with follow_merges=True, returns the survivor), a withdrawn one GoneError, as in get.

list

list(*, page_size: int | None = None, limit: int | None = None, **filters: Unpack[MicroorganismListFilters]) -> Collection[MicroorganismSummary]

Microorganisms matching the filters (positive evidence unless polarity= says).

names

names() -> list[NamedRef]

Every microorganism's {id, name} (live only).

lineage_levels

lineage_levels(*, domain: str | None = None, kingdom: str | None = None, phylum: str | None = None, class_: str | None = None, order: str | None = None, family: str | None = None) -> dict[str, list[str]]

The taxon names at each rank, narrowed by the ranks given (live only).

taxonomy

taxonomy(rank: str, name: str) -> TaxonomyGroup

Aggregate statistics for one taxon, e.g. taxonomy("genus", "Pseudomonas").

A renamed taxon is followed to its current name (live only).

Plastics

Plastics(client: Client)

Bases: Resource

The plastic vocabulary, with the organisms and proteins acting on each.

get

get(plastic_id: int, *, microorganism_limit: int = 25, microorganism_offset: int = 0, microorganism_sort_by: Literal['papers', 'result', 'name'] = 'papers', microorganism_sort_order: SortOrder = 'desc', microorganism_polarity: Polarity = 'positive', protein_limit: int = 25, protein_offset: int = 0, protein_sort_by: Literal['papers', 'result', 'plasticdb_id', 'accession', 'name', 'id'] = 'id', protein_sort_order: SortOrder = 'desc', protein_polarity: Polarity = 'positive', evidence_scope: RowEvidenceScope = 'organism_or_enzyme') -> Plastic

One plastic with one page each of its microorganisms and proteins.

For every organism or protein acting on a plastic, page through microorganisms.list(plastic_id=…) / proteins.list(plastic=…) instead.

list

list(*, page_size: int | None = None, limit: int | None = None, **filters: Unpack[PlasticListFilters]) -> Collection[PlasticSummary]

Plastics matching the filters (has_evidence=True: only those with evidence).

names

names() -> list[NamedRef]

Every plastic's {id, name} (live only).

Papers

Papers(client: Client)

Bases: Resource

The literature behind the evidence.

get

get(paper_id: int) -> Paper

One paper with the organisms, proteins and variants it reports.

list

list(*, page_size: int | None = None, limit: int | None = None, **filters: Unpack[PaperListFilters]) -> Collection[PaperSummary]

Papers matching the filters. polarity has no default here (every paper).

footprint

footprint(paper_id: int) -> PaperFootprint

Every record one paper contributed (live only).

export

export(paper_id: int | None = None, *, format: CitationFormat = 'bibtex', path: str | PathLike[str] | None = None, **filters: Unpack[PaperExportFilters]) -> str | Path

Citations as BibTeX or RIS: one paper, or every paper matching the filters (live only).

Returns the text, or writes it to path and returns the path.

Evidence

Evidence(client: Any)

Bases: Resource

The evidence behind the catalogue.

Evidence is organised interaction -> experiment -> observation (see Interaction). Three namespaces list it flat, across the whole database: evidence.interactions, evidence.experiments and evidence.observations (each .list(**filters) and .get(id); records link by interaction_id / experiment_id). evidence.interactions(protein) is the per-protein call with the children nested; .to_pandas(level="observation") of it gives one row per measured value. The material tables describe what was assayed: constructs (sequences as expressed), preparations (host, purification, tags) and binding assays.

kinetics

kinetics(protein: str, *, page_size: int | None = None, limit: int | None = None) -> Collection[Kinetics]

Kinetic parameters of a protein and its variants.

properties

properties(protein: str, *, page_size: int | None = None, limit: int | None = None) -> Collection[Properties]

Stability and activity properties of a protein and its variants.

binding_assays

binding_assays(*, page_size: int | None = None, limit: int | None = None, **filters: Unpack[BindingAssayFilters]) -> Collection[BindingAssay]

Binding (adsorption) assays, filtered by protein, paper or plastic.

constructs

constructs(*, page_size: int | None = None, limit: int | None = None, **filters: Unpack[MaterialFilters]) -> Collection[Construct]

Expressed constructs (they carry sequences: .to_fasta() works).

construct_structures

construct_structures(construct_id: int) -> list[StructureLink]

The structures linked to one construct.

preparations

preparations(*, page_size: int | None = None, limit: int | None = None, **filters: Unpack[MaterialFilters]) -> Collection[Preparation]

Prepared materials (expression host, purification, tags, modifications).

experiment_preparations

experiment_preparations(experiment_id: int) -> list[Preparation]

The preparations one experiment assayed.

InteractionRecords

InteractionRecords(client: Client)

Bases: _Records[InteractionRecord]

client.evidence.interactions: every public interaction as a flat record.

.list(**filters) pages GET /interactions (ordered by id; 500 a page at most); .get(id) reads one. Called with a protein accession, client.evidence.interactions("PBFCTW") is the older per-protein call (interactions: nested experiments and observations).

list

list(*, page_size: int | None = None, limit: int | None = None, **filters: Unpack[EvidenceListFilters]) -> Collection[InteractionRecord]

Interactions matching the filters, as flat records (pinnable).

ExperimentRecords

ExperimentRecords(client: Client)

Bases: _Records[ExperimentRecord]

client.evidence.experiments: .list(**filters) and .get(id).

list

list(*, page_size: int | None = None, limit: int | None = None, **filters: Unpack[ExperimentListFilters]) -> Collection[ExperimentRecord]

Experiments matching the filters (interaction_id narrows to one interaction).

ObservationRecords

ObservationRecords(client: Client)

Bases: _Records[ObservationRecord]

client.evidence.observations: .list(**filters) and .get(id).

list

list(*, page_size: int | None = None, limit: int | None = None, **filters: Unpack[ObservationListFilters]) -> Collection[ObservationRecord]

Measured values matching the filters (interaction_id, experiment_id).

Search

Search(client: Client)

Bases: Resource

Full-text search across every record type (live only).

client.search("PETase") returns ranked hits. A past release cannot be searched: a pinned client gets LiveOnlyError.

grouped

grouped(q: str, *, limit: int = 10) -> GroupedSearch

The top limit hits (at most 100) for each record type.

autocomplete

autocomplete(q: str) -> dict[str, list[SearchHit]]

Name suggestions per record type, as the site's search box shows them.

Pathways

Pathways(client: Client)

Bases: Resource

Curated degradation pathways.

get

get(pathway_id: int) -> Pathway

One pathway with its ordered reaction steps.

for_plastic

for_plastic(plastic_id: int) -> list[Pathway]

Every pathway that degrades one plastic.

graph

graph(plastic_id: int, *, pathway_id: int | None = None) -> PathwayGraph

A plastic's pathways as a graph of compounds and reactions.

StatsResource

StatsResource(client: Client)

Bases: Resource

Summary statistics of the live database (live only).

summary

summary(*, evidence_scope: EvidenceScope = 'organism_or_enzyme') -> Stats

Headline counts: proteins, microorganisms, plastics, papers, pathways.

evidence_scope decides which organisms count (enzyme_only: those credited only through an enzyme).

protein_activity

protein_activity() -> ProteinActivityStats

How many proteins degrade, fail to degrade, or are untested.

charts

charts(*, evidence_scope: RowEvidenceScope = 'organism_or_enzyme') -> dict[str, Any]

The data behind the site's statistics charts (no enzyme_only: see the API docs).

by_country

by_country() -> dict[str, Any]

Record counts by the corresponding author's country.