job_get()fetches a job (yours, or one submitted without an account) by id, or refreshes aplasticdb_job: its status, summary and provenance, not its hits.job_status()returns just the status:"waiting","running","done"or"error".wait_job()polls until the job finishes and returns it: everypoll_intervalseconds, backing off by half each time up tomax_poll_interval; a 429 waits for the server'sRetry-After. Pasttimeoutseconds it signalsplasticdb_job_timeout(the job keeps running: callwait_job()again, orjob_get()later). A failed job signalsplasticdb_job_failed(fieldjob, the server's reason as the message) unlesserror = FALSE.job_results()returns the results by job type: forannotate_gene,annotate_genome,compare_genomes(source_labelnames the genome) andhmm_screen, every stored hit as a tibble, paged from the server 500 at a time (the results file and page also hide hits under 70 % reference coverage by default; this does not). Anhmm_screenhit is a profile match, not an alignment:pident,length,qcovandscovare alwaysNA(never 0), jobs run before server 2.90.0 included, so identity and coverage filters do not apply to them (testis.na()or skip them).subject_seq_idis the profile name andprofile_accessionits accession;evalueandbitscoreare the full-sequence values,domain_score(double),domain_c_evalueanddomain_i_evaluethose of the best domain,hmm_from/hmm_to(its span on the profile) andenv_from/env_to(its envelope on your sequence; 1-based, inclusive) areinteger. All of these areNAon DIAMOND hits and on HMM jobs run before 2.90.0. The HMM TSV fromjob_download()has 8 more columns aftercalibration_status: read it by header name. Forpathway_analysisone row per pathway step (present, the best hit); forannotate_listyour table's rows with PlasticDB's columns added; forbuild_treeaplasticdb_tree:newick(the cladogram as Newick text),matrix(organism x plastic,TRUEwhere it acts on the plastic) andphylo(anape::phylowhen ape is installed andphylo = TRUE, elseNULL).job_comparison()is acompare_genomesjob's genome x plastic matrix for a view of the hits (with no thresholds, the job's default view).job_download()saves the server's results file: a TSV with#provenance lines, or a ZIP forcompare_genomes(per-genome hit tables, the matrix andprovenance.json). Hit tables apply the job's default view unless you pass thresholds (0turns one off) orall_hits = TRUE. Result files are deleted under the server's retention policy; then it signalsplasticdb_results_expired(the record and hits stay readable).job_share()creates a read-only link to the job's results. Its token is in the answer once only: keep$url. It is sent with anIdempotency-Key, so a retry returns the same link.job_shares()lists the job's links (never their tokens),job_unshare()revokes one at once. These three are for the job's owner (an API key); a job opened from a link is read-only (plasticdb_permission_denied).job_shared()opens a job someone shared, from its link or token (no API key needed); the other functions then read it through the link.jobs_list()lists your jobs, newest first.job_provenance()is what the job ran against, to report with its results: the datasetreleaseandrelease_source("snapshot"for a past release's archived databases,"live"for the live one; the job's own, whichever client reads it),reference_sha256(the DIAMOND database or HMM library searched),tool_versions,app_versionand the server's full provenancerecord.job_replayed()isTRUEwhen the submission's idempotency key returned an existing job.
Usage
job_get(job, client = plasticdb_client())
job_status(job, client = plasticdb_client())
wait_job(
job,
timeout = NULL,
poll_interval = 2,
max_poll_interval = 30,
error = TRUE,
client = plasticdb_client()
)
job_results(job, limit = Inf, phylo = TRUE, client = plasticdb_client())
job_comparison(
job,
scov = NULL,
qcov = NULL,
bitscore = NULL,
all_hits = FALSE,
client = plasticdb_client()
)
job_download(
job,
path = ".",
scov = NULL,
qcov = NULL,
bitscore = NULL,
all_hits = FALSE,
client = plasticdb_client()
)
job_share(
job,
expires_in_days = NULL,
idempotency_key = NULL,
client = plasticdb_client()
)
job_shares(job, client = plasticdb_client())
job_unshare(job, share, client = plasticdb_client())
job_shared(token_or_url, client = plasticdb_client())
jobs_list(limit = Inf, client = plasticdb_client())
job_provenance(job, client = plasticdb_client())
job_replayed(job)Arguments
- job
A
plasticdb_job, or a job id.- client
- timeout
Seconds to wait before signalling
plasticdb_job_timeout;NULLwaits as long as it takes.- poll_interval, max_poll_interval
The first and the longest wait between polls, in seconds.
- error
Signal
plasticdb_job_failedfor a failed job; withFALSEit is returned.- limit
The most hits (or jobs) to return.
- phylo
For a tree, also parse it with
ape::read.tree().- scov, qcov, bitscore
Hit thresholds for the view (
0turns one off;NULLkeeps the job's default).- all_hits
Count or write every hit, with no view.
- path
A file, or a directory to save the server's file name in.
- expires_in_days
Days the link lasts (1-365);
NULLfor as long as the job.- idempotency_key
As for
submit_job().A share (a row of
job_shares(), orjob_share()'s answer) or its numeric id.- token_or_url
A share link, or its token.
Value
job_get(), wait_job() and job_shared() a plasticdb_job;
job_status() a string; job_results() a tibble with provenance (or a
plasticdb_tree); job_comparison() a list with the genomes tibble;
job_download() the path written; job_share() a list (token,
url, ...); job_shares() and jobs_list() tibbles;
job_unshare() TRUE, invisibly; job_provenance() a list;
job_replayed() TRUE or FALSE.
See also
jobs to submit one.
Examples
## A job opened from a share link needs no API key; an unknown link
## is a classed error:
res <- tryCatch(job_shared("https://v2.plasticdb.org/jobs/shared/no-such"),
plasticdb_not_found = function(e) conditionMessage(e))
res
# \donttest{
## Your own jobs need an API key; this uses your most recent finished job.
if (nzchar(Sys.getenv("PLASTICDB_API_KEY"))) {
client <- plasticdb_client()
recent <- jobs_list(limit = 5, client = client)
recent <- recent[recent$status == "done", ]
if (nrow(recent)) {
job <- wait_job(recent$id[[1]], timeout = 3600, client = client)
hits <- job_results(job, client = client)
job_provenance(job)$reference_sha256
job_download(job, tempdir(), client = client)
link <- job_share(job, expires_in_days = 30, client = client)
shared <- job_shared(link$url)
job_results(shared)
}
}
# }