Skip to contents
  • job_get() fetches a job (yours, or one submitted without an account) by id, or refreshes a plasticdb_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: every poll_interval seconds, backing off by half each time up to max_poll_interval; a 429 waits for the server's Retry-After. Past timeout seconds it signals plasticdb_job_timeout (the job keeps running: call wait_job() again, or job_get() later). A failed job signals plasticdb_job_failed (field job, the server's reason as the message) unless error = FALSE.

  • job_results() returns the results by job type: for annotate_gene, annotate_genome, compare_genomes (source_label names the genome) and hmm_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). An hmm_screen hit is a profile match, not an alignment: pident, length, qcov and scov are always NA (never 0), jobs run before server 2.90.0 included, so identity and coverage filters do not apply to them (test is.na() or skip them). subject_seq_id is the profile name and profile_accession its accession; evalue and bitscore are the full-sequence values, domain_score (double), domain_c_evalue and domain_i_evalue those of the best domain, hmm_from/hmm_to (its span on the profile) and env_from/env_to (its envelope on your sequence; 1-based, inclusive) are integer. All of these are NA on DIAMOND hits and on HMM jobs run before 2.90.0. The HMM TSV from job_download() has 8 more columns after calibration_status: read it by header name. For pathway_analysis one row per pathway step (present, the best hit); for annotate_list your table's rows with PlasticDB's columns added; for build_tree a plasticdb_tree: newick (the cladogram as Newick text), matrix (organism x plastic, TRUE where it acts on the plastic) and phylo (an ape::phylo when ape is installed and phylo = TRUE, else NULL).

  • job_comparison() is a compare_genomes job'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 for compare_genomes (per-genome hit tables, the matrix and provenance.json). Hit tables apply the job's default view unless you pass thresholds (0 turns one off) or all_hits = TRUE. Result files are deleted under the server's retention policy; then it signals plasticdb_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 an Idempotency-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 dataset release and release_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_version and the server's full provenance record. job_replayed() is TRUE when 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

A plasticdb_client().

timeout

Seconds to wait before signalling plasticdb_job_timeout; NULL waits as long as it takes.

poll_interval, max_poll_interval

The first and the longest wait between polls, in seconds.

error

Signal plasticdb_job_failed for a failed job; with FALSE it 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 (0 turns one off; NULL keeps 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); NULL for as long as the job.

idempotency_key

As for submit_job().

share

A share (a row of job_shares(), or job_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)
    }
}
# }