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_treetakes filters in...instead.- ...
For
submit_job(), the job type's parameters (as named for its helper;labelsforcompare_genomes); forbuild_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 withthreshold_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_scovdefaults 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"(evalueonly).- 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
}
# }