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.
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.
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 anddownload()'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 ¶
steps() -> ResultTable[PathwayStep]
A pathway analysis: one row per pathway step, present and the best hit.
taxa ¶
taxa() -> ResultTable[AnnotatedTaxon]
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.
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"]).