Skip to contents

Jobs run PlasticDB's analyses on the server: DIAMOND searches of genes, genomes and genome sets against PlasticDB's proteins, the matching of a table of taxa, pathway mapping, HMM screens and taxonomy trees. They need an API key (plasticdb_client(api_key = ) or PLASTICDB_API_KEY; without one the functions signal plasticdb_api_key_required before anything is sent). Reading a shared job (job_shared()) needs none.

Usage

submit_job(
  type,
  input = NULL,
  ...,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

annotate_gene(
  fasta,
  blast_type = NULL,
  organism_type = NULL,
  evalue = NULL,
  pident = NULL,
  include_variants = NULL,
  min_qcov = NULL,
  min_scov = NULL,
  min_bitscore = NULL,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

annotate_genome(
  fasta,
  blast_type = NULL,
  organism_type = NULL,
  evalue = NULL,
  pident = NULL,
  include_variants = NULL,
  min_qcov = NULL,
  min_scov = NULL,
  min_bitscore = NULL,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

compare_genomes(
  genomes,
  labels = NULL,
  blast_type = NULL,
  organism_type = NULL,
  evalue = NULL,
  pident = NULL,
  include_variants = NULL,
  min_qcov = NULL,
  min_scov = NULL,
  min_bitscore = NULL,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

annotate_list(
  table,
  genus_column = NULL,
  species_column = NULL,
  field_separator = NULL,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

pathway_analysis(
  fasta,
  target_plastic = NULL,
  blast_type = NULL,
  evalue = NULL,
  pident = NULL,
  min_step_identity = NULL,
  max_step_evalue = NULL,
  min_reference_coverage = NULL,
  min_query_coverage = NULL,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

hmm_screen(
  fasta,
  target_polymers = NULL,
  threshold_mode = NULL,
  evalue = NULL,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

build_tree(
  ...,
  release = NULL,
  idempotency_key = NULL,
  client = plasticdb_client()
)

search_sequence(
  sequence,
  blast_type = NULL,
  evalue = NULL,
  pident = NULL,
  include_variants = NULL,
  release = NULL,
  client = plasticdb_client()
)

Arguments

type

A job type: "annotate_gene", "annotate_genome", "compare_genomes", "annotate_list", "pathway_analysis", "hmm_screen" or "build_tree" (dashes may stand for underscores).

input

What the job reads: a FASTA input, a list of genomes (compare_genomes) or a taxa table (annotate_list); see Details. build_tree takes filters in ... instead.

...

For submit_job(), the job type's parameters (as named for its helper; labels for compare_genomes); for build_tree(), filters.

release

A release version to run against, instead of the client's.

idempotency_key

Identifies this submission (any 1-255 printable ASCII characters; default a new UUID): resending it returns the same job.

client

A plasticdb_client() with an API key.

fasta

A FASTA input (see Details).

blast_type

"blastp" (protein input, the default) or "blastx" (nucleotide input).

organism_type

Signal-peptide prediction for the hits: "no_signalp" (default), "gram-", "gram+", "arch" or "euk".

evalue

E-value threshold (default 1e-5). For hmm_screen() it applies only with threshold_mode = "evalue".

pident

Minimum percent identity (default 30).

include_variants

Also search engineered variants.

min_qcov, min_scov, min_bitscore

The default view of the results file and page: hide hits covering less than this % of the query / reference (min_scov defaults to 70), or under this bitscore. Every hit is stored; job_results() returns them all.

genomes

Two or more genome inputs (up to 20), as a list or a character vector of paths. Names label the genomes in the results.

labels

The genomes' labels, instead of their names. Otherwise a genome is labelled by its file name, else genome_<n>.

table

A taxa table: a path, text or data frame.

genus_column, species_column

1-based columns holding the genus and species. They default to 7 and 8 (the server's layout), so pass them for any other table.

field_separator

"tab" (default), "comma" or "space".

target_plastic

The plastic whose degradation pathway is mapped (default "PET").

min_step_identity, max_step_evalue

When a hit calls a pathway step present: its minimum % identity (default 40) and maximum e-value (default 1e-10).

min_reference_coverage, min_query_coverage

And the minimum % of the reference enzyme (default 70) and of your protein (default 50) the alignment must cover.

target_polymers

Polymers to limit the HMM polymer summary to, e.g. c("PET", "PLA").

threshold_mode

"gathering" (default: each profile's calibrated cut-off) or "evalue" (evalue only).

sequence

One sequence: residues, one-record FASTA text, or a Biostrings sequence (or a set of one).

Value

A plasticdb_job: the job as the server describes it (a list: id, job_type, status, release, ...). search_sequence() returns a list with the hits (a tibble) and what they were searched against (release, release_source, reference_sha256, diamond_version).

Details

submit_job() submits a job by its server name and returns a plasticdb_job at once; the typed helpers (annotate_gene(), annotate_genome(), compare_genomes(), annotate_list(), pathway_analysis(), hmm_screen(), build_tree()) name and document each job type's parameters. Then wait_job() polls until it finishes and job_results() returns its results. search_sequence() is synchronous: it searches one sequence now and returns the hits.

Inputs. A FASTA input is a file path (plain or gzip), FASTA text (a string starting with >, or a character vector of lines), a single line of residues, raw bytes, or a Biostrings::AAStringSet / Biostrings::DNAStringSet (use blast_type = "blastx" for nucleotide input). A taxa table is a path, text or a data frame (sent tab-separated, with its column names as the header row). Text and sets are written to temporary files; every upload is named after its contents (.gz exactly when it is gzip), as the server expects.

Releases. A pinned client (or release =) runs the job against that release's archived reference databases; a job type or option the release cannot answer signals plasticdb_release_unsupported_filter.

Retries and idempotency. Each submission is sent with an Idempotency-Key header: idempotency_key, or a new UUID for each call, and the same key on every retry of that call. The server keeps a key for 24 hours per user and answers a repeat with the job the first request created (job_replayed() is then TRUE), so with an API key a submission is retried like a read: on a timeout, a dropped connection or a 5xx. Pass your own key when a script may be re-run after a crash: the re-run gets the first job back instead of a duplicate. When the retries run out, the error names the key to resubmit with (field idempotency_key). The same key with a different request signals plasticdb_idempotency_key_reused.

Limits. Submissions are rate-limited (30 an hour); a 429 is waited out when Retry-After is within max_retry_wait. A file over the size limit, or more than 20 genomes, is plasticdb_payload_too_large.

Examples

## Arguments are checked before anything is sent:
res <- tryCatch(submit_job("no_such_job", ">q\nMKVLAAGIVALLLAAGCSS"),
    plasticdb_argument_error = function(e) conditionMessage(e))
res
# \donttest{
## Jobs need an API key (https://v2.plasticdb.org/profile/api-keys).
if (nzchar(Sys.getenv("PLASTICDB_API_KEY"))) {
    client <- plasticdb_client()
    genome <- tempfile(fileext = ".faa")
    seq <- paste0("MNFPRASRLMQAAVLGGLMAVSAAATAQ",
        "TNPYARGPNPTAASLEASAGPF")
    writeLines(c(">p1", seq), genome)
    job <- annotate_genome(genome, client = client)
    job <- wait_job(job, client = client)
    hits <- job_results(job, client = client)
    cmp <- compare_genomes(list(A = genome, B = genome), client = client)
    tree <- job_results(wait_job(build_tree(plastic = "PET", genus =
        "Pseudomonas", client = client), client = client), client = client)
    search_sequence("MNFPRASRLMQAAVLGGLMAVSAAATAQTNPYARGPNPTAASLEASAGPF",
        client = client)$hits
}
# }