COMER web service API help page

Command-line interface to services
Programatic access to services
Results in the graphical environment

Command-line interface to services

Conducting a homology search

The simplest way to conduct a COMER2 search from the command line with a sequence query (e.g., "TKPCQSDKDCKKFACRKPKVPKCINGFCKCVR") and default settings against the default database, which is a PDB70 profile database, is to issue the following command:

curl https://bioinformatics.lt/comer/search/api/submit -F sequence=TKPCQSDKDCKKFACRKPKVPKCINGFCKCVR

The communication between the client (the user side) and the server is asynchronous. Connections are non-blocking, and the server always responds with a string in JSON format. On success, the first field ("success": true) indicates no errors, and the second field ("job_id": "MyJobID") specifies the ID ("MyJobID" in this example) of the submitted job. This job ID is used for communication with the server:

If the submission of a job fails, a response string will indicate an error and contain a reason message:

Specifying options

The COMER web server API allows for specifying all options that are available in the graphical user interface. The syntax for specifying different options using curl is as follows: -F option1_name=option1_value -F option2_name=option2_value ... The names of available options, along with their description, can be found in the COMER settings file.

In the following example, a COMER2 search is configured with a statistical significance threshold of E-value=0.0001, which means that hits detected with a significance greater than this value will not be displayed. Also, HMMER3 replaces HHblits for sequence search when building an MSA for the query (see the Help page):

curl https://bioinformatics.lt/comer/search/api/submit -F sequence=TKPCQSDKDCKKFACRKPKVPKCINGFCKCVR -F EVAL=0.0001 -F hmmer_in_use=true -F hhsuite_in_use=false

Multiple COMER2 profile databases can be selected for searching using COMER2 by specifying the corresponding option once for each database name. The following example instructs the server to search the PDB70, Pfam, and UniProtKB/Swiss-Prot COMER2 profile databases:

curl https://bioinformatics.lt/comer/search/api/submit -F sequence=TKPCQSDKDCKKFACRKPKVPKCINGFCKCVR -F comer_db=pdb70_231224 -F comer_db=pfamA_36.0 -F comer_db=swissprot90_2023_02

The names of the up-to-date databases are provided here:

For COMER: pdb70_231224 (PDB70), scope70_2.08 (SCOPe70), pfamA_36.0 (Pfam), swissprot90_2023_02 (UniProtKB/SwissProt90), ECOD-F70_20220613 (ECOD-F70), COG-KOG (COG-KOG), NCBI-CD_3.19 (NCBI-Conserved-Domains)
For HHsuite: UniRef30_2022_02 (UniRef30), bfd_metaclust_clu_complete_id30_c90_final_seq.sorted_opt (BFD)
For HMMER: uniref50_2022_08.fasta (UniRef50), mgy_clusters_2022_05.fa (MGnify)

Uploading data files

The command-line option "-F sequence=" corresponds to the main text field (for entering queries) in the graphical user interface and accepts queries of different types and in different formats (see the Help page). For a larger number of queries given, it is much more convenient to provide the server with the input file instead of entering the data in the command line.

Let us assume that one or more queries are stored locally in file /path/to/my/directory/queries.input, and options are located in file /path/to/my/directory/job.options. Then, use the following command to submit a job with input data to be read from these files:

curl https://bioinformatics.lt/comer/search/api/submit -F input_query_file=@/path/to/my/directory/queries.input -F input_search_parameters_file=@/path/to/my/directory/job.options

Querying job status

Once the job is submitted, query job status asynchronously by typing:

curl https://bioinformatics.lt/comer/search/api/job_status/MyJobID

where MyJobID is the job ID returned by the submit command (see Conducting a homology search). A typical successful response from the server is the following:

which shows that the submission was successful ("success": true) and the job is running ("status": "queued"). Once the job finishes running, the status in the response string will be "finished" ("status": "finished"). If errors have occurred, the status field will be "failed" ("status": "failed") or an error message if the submission failed ("success": false).

Retrieving results

The following command is used to retrieve from the server the resulting profile-profile alignments in JSON format, associated with job MyJobID:

curl https://bioinformatics.lt/comer/search/api/results_json/MyJobID

If it is issued during the execution of the job, the results will be empty ("results": []), the number of successfully processed queries will be 0 ("number_of_successful_sequences": 0), and the status will indicate the process being in progress ("status": "queued"):

The profile-profile alignments along with intermediate results, including initial queries, constructed MSAs and profiles, and log files, are also available as a single compressed zip file:

curl https://bioinformatics.lt/comer/search/api/results_zip/MyJobID

The input data, the options of the job, and the job progress information can be retrieved separately using the following commands:

curl https://bioinformatics.lt/comer/search/api/job_input/MyJobID

curl https://bioinformatics.lt/comer/search/api/job_options/MyJobID

curl https://bioinformatics.lt/comer/search/api/job_error/MyJobID

Programmatic access to services

The COMER web server provides programmatic access to running homology searches using the server's computational resources. An example Python script that conducts a COMER2 search with a sequence query and default settings, waits for results, and prints them on standard output is available here.

Results in the graphical environment

The COMER web server maintains a unified job control system. Jobs submitted using the command-line or programmatic interface are also valid for inspection in the graphical user environment as if they were submitted on the server's main page.

Given job ID MyJobID, visit the results page at:

https://bioinformatics.lt/comer/search/results/MyJobID