Editing CrocoBLAST:UserManual (section)

=1. Manage BLAST jobs=
The efficiency of CrocoBLAST lies in its ability to parallelize the execution of your BLAST jobs. This is related to breaking each big calculation into smaller pieces, and then organizing the execution of the pieces. Depending on the job, CrocoBLAST may benefit from using smaller or larger smaller pieces. CrocoBLAST automatically detects the ideal size for breaking the input file and does it for you. Alternatively, the size of each input file fragment can be manually specified as described in examples "1.3" and "1.4."

== 1.1. Creating BLAST jobs ==
As already mentioned, BLAST takes an input file with unknown sequences and aligns each such sequence against a database of known sequences. To create a job, you must first specify the [http://www.ncbi.nlm.nih.gov/BLAST/blast_program.shtml BLAST program] you plan to use, which depends on the nature of the unknown sequences in your input file, and the nature of the sequences in the reference database. Then, you need to specify the name of the ''database'' listed in the CrocoBLAST index (more details on that below) that contains the reference sequences you wish to use. Finally, provide the input file and the location where you want CrocoBLAST to place the output files. Keep in mind that the output files may be quite large. Finally, if you want to change the default BLAST settings, you can do so by specifying the [http://www.ncbi.nlm.nih.gov/books/NBK279675/ names and values of the BLAST options] of interest.

# <code>crocoblast -add_to_queue <span style="color:blue">blast_program database</span> <span style="color:green">input_file output_folder</span></code>
# <code>crocoblast -add_to_queue <span style="color:blue">blast_program database</span> <span style="color:green">input_file output_folder</span> --blast_options <span style="color:blue">option1 value1 option2 value2 ...</span></code>
# <code>crocoblast -add_to_queue <span style="color:blue">blast_program database</span> <span style="color:green">input_file output_folder</span> --size_of_fragment <span style="color:blue">size_in_kb</span></code>
# <code>crocoblast -add_to_queue <span style="color:blue">blast_program database</span> <span style="color:green">input_file output_folder</span> --size_of_fragment <span style="color:blue">size_in_kb</span> --options <span style="color:blue">option1 value1 option2 value2 ...</span></code>

If no "--blast_options" are specified, CrocoBLAST will use all BLAST default values.

If no "--size_of_fragment" is specified, CrocoBLAST will take up to 5 seconds to auto-detect the ideal size for that job on your computer.

Note that, CrocoBLAST does not accept that the "--size_of_fragment" argument to be placed after "--blast options". If you intend to use both settings, please follow example number 1.4. 

When you create a BLAST job, CrocoBLAST automatically assigns each BLAST job a unique job ID, and updates the CrocoBLAST queue.

== 1.2 Removing BLAST jobs ==

In case you want to remove a BLAST job from the queue, you can do so by referring to it using its job_id. The job_id is informed every time a job is added to the queue, but you can also learn it using the command "status" described in the example "1.4.1".

# <code>crocoblast -remove_from_queue <span style="color:blue">job_id</span></code>
# <code>crocoblast -remove_from_queue <span style="color:blue">job_id_1 job_id_2 ...</span></code>

The first command will remove only one CrocoBLAST job from the queue, while the second command can be used for removing several jobs at once.

== 1.3 Verifying the state of the queue ==

While CrocoBLAST operates with the concept of queue, it is important to note that only one job (the first on the queue) is active at any given time. You can check the current state of the CrocoBLAST queue using the command:

# <code>crocoblast -status</code>

This will provide you with information regarding which jobs are on queue, with full details regarding the job ID and BLAST setup, as well as a description about the progress of each job. The progress of each job is described in three main directions: fragmentation of the input file, alignment, and assembly of results. In case CrocoBLAST is running when the "status" command is submitted, the estimated time for finishing the first job on the queue is also informed.

== 1.4 Moving a BLAST job to the top of the queue ==

As only one job (the first on queue) is active on CrocoBLAST at each time, moving another job to the top of the queue can be useful for changing the order in which the jobs will be executed. You can move a job to the top of the CrocoBLAST queue using the commands:

# <code>crocoblast -move_top_queue <span style="color:blue">job_id</span></code>
# <code>crocoblast -move_top_queue <span style="color:blue">job_id_pos_1 job_id_pos_2 ...</span></code>