Skip to content

Jobs

Jobs

Jobs(client: Client)

Bases: Resource

Run PlasticDB's analyses: needs an API key (Client(api_key=) / $PLASTICDB_API_KEY).

A pinned client (or release= on the call) runs the job against that release's archived reference databases; a job type or option a release cannot answer raises UnsupportedFilterError. Submissions are rate-limited (30 an hour). Each submission is sent with an Idempotency-Key (a new UUID, or the idempotency_key= you pass), so it is retried on a timeout or a 5xx: if an attempt did reach the server, the retry gets that job back (job.replayed) instead of a duplicate. Reuse a key (within 24 hours) to recover a submission whose answer you lost; a key sent with a different request raises IdempotencyKeyReusedError.

get

get(job_id: str) -> Job

A job by id (yours, or one submitted without an account).

shared

shared(token_or_url: str) -> Job

A job someone shared with you, from its link or token (no API key needed).

submit

submit(job_type: str, input: Any = None, *, release: str | None = None, idempotency_key: str | None = None, **params: Any) -> Job

Submit a job by its server name (annotate_genome, hmm_screen, build_tree…).

input is what the job reads (see the typed helpers, which document each job type's parameters); build_tree takes filters instead. Returns the Job at once; call .wait() for the results. idempotency_key (any 1-255 printable ASCII characters; default a new UUID) identifies this submission: resending it returns the same job.

annotate_gene

annotate_gene(fasta: Any, *, release: str | None = None, idempotency_key: str | None = None, blast_type: BlastType | None = None, organism_type: OrganismType | None = None, evalue: float | None = None, pident: int | None = None, include_variants: bool | None = None, min_qcov: float | None = None, min_scov: float | None = None, min_bitscore: float | None = None) -> Job

Search a few genes/proteins against PlasticDB's proteins (DIAMOND).

fasta is a path (gzip or plain), FASTA text, bytes, a file object, a Bio.SeqRecord or a list of them. blast_type="blastx" for nucleotide input. evalue (default 1e-5) and pident (30) bound the search; include_variants also searches engineered variants; min_qcov / min_scov (default 70) / min_bitscore set the default view of the results file and page (every hit is stored). organism_type turns on signal-peptide prediction (gram-, gram+, arch, euk). idempotency_key: see submit.

annotate_genome

annotate_genome(fasta: Any, *, release: str | None = None, idempotency_key: str | None = None, blast_type: BlastType | None = None, organism_type: OrganismType | None = None, evalue: float | None = None, pident: int | None = None, include_variants: bool | None = None, min_qcov: float | None = None, min_scov: float | None = None, min_bitscore: float | None = None) -> Job

Annotate a whole genome's proteins (or, with blastx, its contigs).

Same inputs and parameters as annotate_gene.

compare_genomes

compare_genomes(genomes: Any, *, labels: Sequence[str] | None = None, release: str | None = None, idempotency_key: str | None = None, blast_type: BlastType | None = None, organism_type: OrganismType | None = None, evalue: float | None = None, pident: int | None = None, include_variants: bool | None = None, min_qcov: float | None = None, min_scov: float | None = None, min_bitscore: float | None = None) -> Job

Search two or more genomes (up to the server's limit, 20) and compare them.

genomes is a list of genome inputs (each as for annotate_gene) or a {label: genome} mapping. A genome's label names its rows in the results: labels=, the mapping key, else the file name. Results: job.hits() (source_label is the genome) and job.comparison().

annotate_list

annotate_list(table: Any, *, release: str | None = None, idempotency_key: str | None = None, genus_column: int | None = None, species_column: int | None = None, field_separator: Literal['tab', 'comma', 'space'] | None = None) -> Job

Match a table of taxa (genus, species) against PlasticDB's organisms.

table is a path, text, bytes, or a list of rows (sent tab-separated). genus_column / species_column are 1-based and default to 7 and 8 (the server's layout), so pass them for any other table. field_separator is tab (default), comma or space; the job records all three. Results: job.taxa().

pathway_analysis

pathway_analysis(fasta: Any, *, release: str | None = None, idempotency_key: str | None = None, target_plastic: str | None = None, blast_type: BlastType | None = None, evalue: float | None = None, pident: int | None = None, min_step_identity: float | None = None, max_step_evalue: float | None = None, min_reference_coverage: float | None = None, min_query_coverage: float | None = None) -> Job

Map proteins onto a plastic's degradation pathway: which steps they cover.

target_plastic names the plastic whose pathway is mapped (default PET; the job records it in result_metadata). The min_step_* / max_step_evalue / min_*_coverage thresholds decide when a hit calls a step present (defaults 40 %, 1e-10, 70 %, 50 %). Results: job.steps().

hmm_screen

hmm_screen(fasta: Any, *, release: str | None = None, idempotency_key: str | None = None, target_polymers: Sequence[str] | None = None, threshold_mode: ThresholdMode | None = None, evalue: float | None = None) -> Job

Screen proteins against PlasticDB's polymer-specific HMM profiles (hmmsearch).

threshold_mode="gathering" (default) uses each profile's calibrated cut-off and ignores evalue; "evalue" uses evalue only. target_polymers (e.g. ["PET", "PLA"]) limits the polymer summary. Results: job.hits() and info.result_metadata["polymer_hits"].

build_tree

build_tree(*, release: str | None = None, idempotency_key: str | None = None, **filters: Any) -> Job

A taxonomy tree (NCBI-taxonomy cladogram) of organisms, by filter or id list.

Filters are /microorganisms's (plastic="PET", genus=, class_=, polarity=, …) or microorganism_ids=[...]. A pinned client (or release=) builds it from that release. Results: job.tree() (Newick + organism x plastic matrix).

search_sequence

search_sequence(sequence: Any, *, release: str | None = None, blast_type: BlastType | None = None, evalue: float | None = None, pident: int | None = None, include_variants: bool | None = None) -> SequenceSearchResult

Search one sequence now (synchronous, no job): DIAMOND hits with provenance.

sequence is residues, one-record FASTA text or a Bio.SeqRecord. The server gives it 15 seconds (past that, ServerError with reason == "timeout"); for more sequences use annotate_gene. While the reference database is unavailable it raises ServiceUnavailableError (retry_after).

list

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

Your jobs, newest first (a lazy collection; to_pandas() for an overview).

Items are JobInfo; client.jobs.get(item.id) gives the Job to wait on or download.

Job

Job(client: Client, info: JobInfo, *, token: str | None = None, response: APIResponse | None = None)

A submitted job. status is the last one fetched; refresh asks again.

wait() polls until the job is done (or raises JobFailedError on error); then results() gives the typed results and download(path) the server's results file.

status property

status: str

waiting, running, done or error (as last fetched).

info property

info: JobInfo

Everything the server said about the job, as last fetched.

shared property

shared: bool

True for a job opened from a share link (read-only).

release property

release: str | None

The dataset release the job ran (or runs) against.

replayed property

replayed: bool

True when the submission's Idempotency-Key returned an existing job.

A retried submission whose first attempt reached the server gets that job back (in its current state) instead of a duplicate.

provenance property

provenance: JobProvenance

The release, reference database checksum and tool versions the job used.

refresh

refresh() -> Job

Fetch the job again (status, summary, provenance; not the hits). Returns self.

wait

wait(timeout: float | None = None, *, poll_interval: float = DEFAULT_POLL_INTERVAL, max_poll_interval: float = DEFAULT_MAX_POLL_INTERVAL, raise_on_error: bool = True) -> Job

Poll until the job finishes; return self.

Polls every poll_interval seconds, backing off by half each time up to max_poll_interval; a 429 waits for the server's Retry-After. timeout (seconds, default none) raises JobTimeoutError; the job keeps running and you can wait() again. A failed job raises JobFailedError unless raise_on_error=False.

results

results() -> ResultTable[Any] | TaxonomyTree

The results, typed by job type.

  • annotate_gene / annotate_genome / compare_genomes / hmm_screen: hits (every stored hit, paged from the server; the website's and download()'s default view also hides hits under 70 % subject coverage).
  • pathway_analysis: steps.
  • annotate_list: taxa.
  • build_tree: tree.

hits

hits(*, limit: int | None = None) -> ResultTable[JobHit]

Every hit (or the first limit), in the server's order (best first per query).

Fetched page by page from GET /jobs/{id}/results (500 a request), so a genome with tens of thousands of hits never arrives as one response.

iter_hits

iter_hits(*, page_size: int | None = None, limit: int | None = None) -> Collection[JobHit]

The hits as a lazy, paged collection (iterate it, or to_pandas()).

steps

A pathway analysis: one row per pathway step, present and the best hit.

taxa

An annotate_list job: your table's rows with PlasticDB's columns added.

Read from the results file (its # provenance lines are skipped); the job's summary is info.result_metadata["taxa"].

tree

tree() -> TaxonomyTree

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

comparison

comparison(*, scov: float | None = None, qcov: float | None = None, bitscore: float | None = None, all_hits: bool = False) -> GenomeComparison

A compare_genomes job's genome x plastic matrix for a view of the hits.

With no arguments, the job's default view (hits covering at least 70 % of the reference); all_hits=True counts every hit; 0 turns one threshold off.

download

download(path: PathLike = '.', *, scov: float | None = None, qcov: float | None = None, bitscore: float | None = None, all_hits: bool = False) -> Path

Stream the results file to path (a file, or a directory to use the server's name).

A TSV with # provenance lines for most job types; a ZIP for compare_genomes (per-genome hit tables, the comparison matrix and provenance.json). Hit tables apply the job's default view unless you pass thresholds (0 turns one off) or all_hits=True. Returns the path written.

share

share(*, expires_in_days: int | None = None, idempotency_key: str | None = None) -> JobShareCreated

Create a read-only link to this job's results (owner only; needs the API key).

The token is in the answer once; keep .url. expires_in_days (1-365) defaults to a link that lasts as long as the job. The request is sent with an Idempotency-Key (idempotency_key, or a new one), so a retry returns the same link rather than a second one.

shares

shares() -> list[JobShare]

The job's share links, newest first (never their tokens).

unshare

unshare(share: JobShare | int) -> None

Revoke a share link at once (its next request is a 404).

JobProvenance dataclass

JobProvenance(job_id: str, job_type: str, release: str | None, release_source: str | None, reference_sha256: str | None, tool_versions: dict[str, str] | None, app_version: str | None = None, record: dict[str, Any] = dict())

What a job ran against: report this with its results.

release is the dataset release the job ran against (release_source snapshot for a past release's archived databases, live for the current one), as the job record and its X-PlasticDB-Release headers say; reference_sha256 the SHA-256 of the DIAMOND database or HMM library searched, tool_versions e.g. {"diamond": "2.1.9"}. record is the server's full provenance record (result_metadata["provenance"]).