Personal BLAST Navigator (PLAN) Function Reference

Related Document: Frequently Asked Questions and Small Tutorials

Table of Contents

0. Preface
1. Pre-BLAST Operations
   1. Manage Query Sequences...
      1. Upload New Query Sequences
      2. List Saved Query Sequences
      3. Download Original Query Sequences
      4. Download Un-annotated Query Sequences
2. Post-BLAST::Browsing
   1. BLAST Search History
      1. Summary of Search Session
      2. Upload Your Own BLAST Results
   2. Browse All Queries
   3. Browse All Targets
   4. Search for Records of Interest
   5. Filter BLAST Results
3. Post-BLAST::Personalization
   1. Favorite Queries
   2. Favorite Targets (Hits)
4. Post-BLAST::Export
   1. Download ...
      1. Original BLAST Result File
      2. Sequence Annotations (All Formats)
      3. Annotated Sequences (FASTA Format)
      4. Un-annotated Sequences (FASTA Format)
      5. Query-Target Pairs for Venn Diagram
5. User Plug-ins
   1. Plate/Gene Line Parsers ...
      1. Configure Plate/Gene Line Parser
      2. Re-generate Plates/Gene Lines
      3. View Results by Plate
      4. View Results by Gene Line
6. Project Operations
   1. Publish/Unpublish Project Data
   2. Edit/Apply Project Settings
   3. Permanently Delete Project

0. Preface

Thank you for using Personal BLAST Navigator (PLAN). PLAN is a generic web platform for automating BLAST searches, managing BLAST results, and mining and sharing results of interest. PLAN is developed by the bioinformatics group of the Samuel Roberts Noble Foundation. The system is being actively developed and continuously improved.

A public PLAN server is available for free at http://bioinfo.noble.org/plan/. You may be using this public server or a local deployment of PLAN in your institutional network. The BLAST options and user privileges provided by different servers may vary. This document provides essential information on the basic functions provided by PLAN. The functions are listed in the same order as they appear in PLAN's navigation bar for your easy reference.

1. Pre-BLAST Operations

1.A. Manage Query Sequences

1.A.a Upload New Query Sequences

Upload query sequences to the PLAN server, parse sequence information and save them to the database. This function requires query sequences in FASTA format. This process checks sequence ID duplication. If duplicated IDs are found, you may choose to 1) replace old sequences with uploaded sequences, 2) keep old sequences and skip the uploaded sequences with duplicated IDs, or 3) ignore the duplication warning, which creates potentially different copies of the same IDs. After successful sequence upload, you may 1) do nothing (return to the list of query sequences, see 1.A.b), or 2) do an automatic BLAST search on the uploaded sequences.

1.A.b List Saved Query Sequences

List all query sequences being successfully uploaded and saved to the database. Sequences are organized according to the original FASTA files. Operations on each FASTA file include

1. Do BLAST Search: This brings you to the BLAST search option page and searches the corresponding set of sequences against selected sequence database;
2. Download: This downloads your original query sequences in FASTA format with original descriptions;
3. Remove: This deletes the selected set of query sequences from the server.

1.A.c Download Original Query Sequences

Download all original query sequences or original query sequences from a single FASTA file. Sequence are downloaded in FASTA format with original descriptions. Optionally, you may download the query sequence subset that don't have any search results returned from previous search sessions (i.e. un-annotated/"no-hit" sequences). Also see 1.A.d.

1.A.d Download Un-annotated Query Sequence

Download all query sequences or query sequences from a single FASTA file that don't have any search results returned from previous search sessions (i.e. un-annotated/"no-hit" sequences). Sequence are downloaded in FASTA format with original descriptions. Also see 1.A.c.

2. Post-BLAST::Browsing

2.A. BLAST Search History

2.A.a. Summary of Search Sessions

List summary of all results from past search sessions. Results are organized according to the original search result file which is in NCBI text format. A search result file is either generated from automatic BLAST searches or uploaded by the user. On each search session, the search session's description and timestamp, search algorithm, and unique number of queries and unique number of targets (hits) are listed. Operations on each search session include:

1. View Queries: View the results organized according to unique queries that are submitted in this search session.
2. View Targets: View the results organized according to unique targets (hits) that are returned from this search session.
3. Re-generate Plates: Re-generate and re-label the plate/gene line ID of each query sequence according to a selected plug-in parser.
4. Re-populate into DB: Re-populate the search results into database in case you forgot to do so or there was some error during last population. Result in NCBI text format has to be populated into database before they are viewable and searchable.
5. Download: Download the original NCBI text format result file.
6. Remove: Delete the selected result file. This also deletes all database records associated to this search session.

Note: "View Queries" and "View Targets" functions in this page list queries and targets submitted to / returned from the corresponding search session only. Also see 2.B Browse All Queries and 2.C Browse All Targets if you want to view queries and targets from all search sessions.

Note: The numbers of unique queries and targets in each search session refer to those that passed the project filter. Also see 2.E Filter BLAST Results .

2.A.b Upload Your Own BLAST Results

Upload your own BLAST result file generated by other BLAST programs such as the NCBI BLAST2. In current version, result file has to be in NCBI plain text format. You can add a short description on the result file upon upload. Once upload is successful, you need to follow the on-screen instructions to populate the results into database.

Note: A "NCBI plain text format" result file does not contain any hyper links or HTML tags. Results that are copied from NCBI web site are not guaranteed to work. BLAST2's command line program by default generates result in NCBI plain text format.

Note: If you forgot to populate the uploaded result file or for some reason the database population is failed. Try re-populating it through the "Summary of Search Sessions" (see 2.A.a).

2.B. Browse All Queries

Browse all queries that are submitted to all search sessions. On each query, all targets (hits) returned from all search sessions are listed.

Results may be presented in multiple pages, click on the page number or select a page number from the drop-down list to jump to the corresponding page. Alternatively, click on "Prev"/"Next" link to go to the previous/next page and "«"/"»" link to go to the first/last page.

On each query, click on the [»] link to view alignment details. Click on the checkbox in front of each query to select/deselect the corresponding query. With selected queries, scroll page down and find the "With Selected:" drop down menu to further operate them.

Operations on selected queries include:

1. Add to favorites: Add selected queries to an existing or new favorite category. Follow the on-screen instructions to select from existing categories or to create a new favorite category.
2. Download query sequences / annotations: Batch download selected sequences in different formats. Also see 4.A.b Download Sequence Annotations (All Formats).

Note: This page lists all queries and all corresponding targets (hits) returned from all search sessions. To browse queries/targets returned from a single search session, see 2.A.a Summary of Search Sessions.

2.C Browse All Targets (Hits)

Browse all targets (hits) that are returned from all search sessions. On each target, all queries that hit this target in all search sessions are listed.

Results may be presented in multiple pages, click on the page number or select a page number from the drop-down list to jump to the corresponding page. Alternatively, click on "Prev"/"Next" link to go to the previous/next page and "«"/"»" link to go to the first/last page.

On each target, click on the [»] link to view alignment details. Click on the checkbox in front of each target to select/deselect the corresponding target. With selected targets, scroll page down and find the "With Selected:" drop down menu to further operate them.

Operations on selected queries include:

1. Add to favorites: Add selected targets to an existing or new favorite category. Follow the on-screen instructions to select from existing categories or to create a new favorite category.
2. Download query sequences / annotations: This function is being implemented and will be available soon.

Note: This page lists all targets and all corresponding queries that hit the targets in all search sessions. To browse queries/targets returned from a single search session, see 2.A.a Summary of Search Sessions.

2.D. Search for Records of Interests

This brings up the search form. There are two search options, described below:

1. Search by a list of query or target accession IDs. Returns a subset of search results according to the provided accession IDs. The list of IDs can be separated with any of the following common delimiters: space, tab, comma (,), semi-column (;) or a new line. Exact (strict) match and partial match options are provided. This is useful for batch download results on specific IDs.
   
2. Search in descriptions. Returns a subset of queries/targets whose descriptions contain the provided search term. This is useful for identifying genes with specific functional annotations.

Note: This search form is also accessible through the "Search" link on the top of the workspace.

Note: Search in descriptions utilizes MySQL's full-text search engine. Some too generic search queries such as "clone", "sequence" may be automatically filtered and thus return no result.

2.E. Filter BLAST Results

Set, change or apply filters on all your BLAST results. Currently there are four filtering options:

1. Filter by bit score: All alignments with bit scores that are lower than the specified threshold will be hidden.
2. Filter by e-value: All alignments with e-values that are higher than the specified threshold will be hidden.
3. Limit number of top hits (optional): Click on the checkbox in front of this option to activate/deactivate this filter. Once activated, only the specified number of top hits will be shown.
4. Hide queries with no hits (optional): Click on the checkbox in front of this option to activate/deactivate this filter. Once activated, queries with no target (hit) that pass filters 1 and 2 above will be hidden.

Note: These filters also affect the statistics on numbers of unique queries / targets in the Summary of Search Session.

3. Post-BLAST::Personalization

3.A. Favorite Queries

List all your favorite query categories and the number of queries in each category. Operations on each category include:

1. Browse Queries: Click on the category ID, name or number of items will by default list all queries in the category. The query list page follows the same template as that of "Browse All Queries" (see 2.B), with an extra "Remove from this favorite category" options on selected queries.
2. Delete: Delete the favorite category. Queries assigned in this category are NOT deleted.
3. Rename: Rename the favorite category.

Additionally, you may create a new, empty favorite category in this page. Please follow the "Add A New Category" on-screen instructions to create a new favorite category.

Note: Favorite targets are organized and displayed in a similar way. See also 3.B. Favorite Targets.

3.B. Favorite Targets

List all your favorite target categories and the number of targets in each category. Operations on each category include:

1. Browse Targets: Click on the category ID, name or number of items will by default list all targets in the category. The target list page follows the same template as that of "Browse All Targets (Hits) " (see 2.C), with an extra "Remove from this favorite category" option on selected targets.
2. Delete: Delete the favorite category. Targets assigned in this category are NOT deleted.
3. Rename: Rename the favorite category.

Additionally, you may create a new, empty favorite category in this page. Please follow the "Add A New Category" on-screen instructions to create a new favorite category.

Note: Favorite queries are organized and displayed in a similar way. See also 3.A. Favorite Queries.

4. Post-BLAST::Export

4.A. Download ...

4.A.a. Original BLAST Result File

This function is an alias of function 2.A.a. Summary of Search Sessions, which list a summary of past searches and allows you to download the selected original BLAST result file.

4.A.b. Sequence Annotations (All Formats)

Export sequence annotations in various formats. Options in this page include:

• Annotate Each Query With:
  1. Top hit in terms of highest score: Use the top hits' ID and description to annotate the query sequences. A "top hit" here is the one with highest bit scores among all targets (hits) of each query.
  2. Top hit in terms of lowest e-value: Use the top hits' ID and description to annotate the query sequences. A "top hit" here is the one with lowest e-value among all targets (hits) of each query.
  3. All shown targets (hits) that passed the project filters: Use the IDs and descriptions of all targets (hits) that passed the project filter to annotate the query sequences. See also 2.E. Filter BLAST Results.
• If Multiple Targets DBs Found:
  1. Treat all DBs together: The comparisons for "top hit" selections above will be across multiple databases. This assigns only one "top hit" to each query.
  2. Treat each DB separately: The comparisons for "top hit" selections above will be within each database. This assigns one "top hit" in each library and hence may annotate a query for multiple times.
  3. Use a selected DB only: Limit annotations to be within the targets (hits) from a selected database only. This practically excludes BLAST results against unselected database(s).
• Annotation Format:
  1. Natural language: Assign a/multiple sequence description(s) to each query sequence in natural language style (e.g. "Similar to <top hit ID>, <description> with bit score <...> and e-value <...>").
  2. Tab-delimited with target ID and description: Output full annotations in tab-delimited text format for downstream analysis using other software such as Excel.
  3. Tab-delimited with target ID only: Output annotations with targets IDs only, in tab-delimited text format for downstream analysis using other software such as Excel. This essentially generates Query ID - Target ID pairs for a simplified view.
• If A Query Has Multiple Annotations: Either option "Annotation each query with" - "all shown targets (hits) that passed the project filters" or "If multiple DBs found" - "treat each DB separately" may assign multiple annotations to a query. In this case, options are:
  1. Consolidate all annotations into the same line: All annotations are assembled into a single line. This practically outputs a single annotation record on each query sequence.
  2. Spread multiple annotations into multiple lines: This practically outputs multiple annotation records on each query sequence.
• Other options:
  1. Include query descriptions in BLAST results: If this option is checked, the original query descriptions in the BLAST results will be kept together with assigned annotations based on targets' (hits') descriptions. Otherwise, the annotations will replace the original query descriptions.
  2. Include query sequences and force the output file in FASTA format: This generates sequence file in FASTA format, with annotations appearing as the sequences' new descriptions.
     
     Note: This option requires that query sequences being saved in PLAN database. Also see 1.A.a. Upload New Query Sequences.
  3. Include query descriptions in query FASTA file: If this option is checked, the original query descriptions in the query sequence file will be kept together with assigned annotations based on targets' (hits') descriptions. Otherwise, the annotations will replace the original query descriptions.

4.A.c. Annotated Sequences (FASTA Format)

This is an alias of function 4.A.a. Download Sequence Annotations (All Formats), with option "Include query sequences and force the output file in FASTA format" automatically checked.

4.A.d. Un-annotated Sequences (FASTA Format)

This is an alias of function 1.A.d. Download Un-annotated Query Sequences.

4.A.e. Query-Target Pairs for Venn Diagram

This function treats all query sequences as a library and all target databases as another, then generates a summary on the number of overlapping sequences between these two libraries and the numbers of unique sequences in each library for Venn diagram drawing. A detailed list of query-target pairs is also provided.

5. User Plug-ins

5.A. Plate/Gene Line Parsers...

5.A.a. Configure Plate/Gene Line Parser

List available plate/gene line parsers and select one to be applied to the project. Click the "Update" button to re-generate plate/gene line IDs using the selected parser. Also see 5.A.b. Re-generate Plates/Gene Lines.

5.A.b. Re-generate Plates/Gene Lines

Re-apply the currently activated plate/gene line parser to all query sequences in the project and re-generate the corresponding plate/gene line IDs. Also see 5.A.a. Configure Plate/Gene Line Parser.

5.A.c. View Results by Plate

Browse the BLAST summary on query sequences organized by plate IDs. On each plate ID, the total number of unique queries and total number of unique targets (hits) are listed. Follow the link to view all queries from the selected plate and their BLAST results.

Note: Numbers of unique queries and targets (hits) refer to those who passed the project filters. Also see 2.E. Filter BLAST Results.

5.A.d. View Results by Gene Line

Browse the BLAST summary on query sequences organized by gene line IDs. On each gene line ID, the total number of unique queries and total number of unique targets (hits) are listed. Follow the link to view all queries from the selected gene line and their BLAST results.

Note: Numbers of unique queries and targets (hits) refer to those who passed the project filters. Also see 2.E. Filter BLAST Results.

6. Project Operations

6.A. Publish/Unpublish Project Data

Depending on your data publication mode, this function name may vary.

The default data publication level to a private project is unpublished. In this level, "Publish Project Data" is clickable, which allows you to publish your project data in two different levels: 1) Open access with full control: Other users will see your project in the "Public Projects" list and they will have full control over your project, including adding or deleting any data. 2) Published as read-only. Other users will see your project in the "Public Projects" list. They may browse and search your data but they cannot make any changes to the project.

If you log in your project when it is published, either for open access or read-only. "Unpublish Project Data" is clickable, which allows you to hide your project from public. The project then will be accessible only with your login email/password.

Note: Project originally created as "Public Projects" (i.e. without login email/password) always remain public for open access with full control.

6.B. Edit/Apply Project Settings

Edit project description. Customize the number of items listed per page, and the number of top targets (hits) for each query in the list of queries, or top queries for each target (hit) in the list of targets (hits). Changes will take effect after you press the "Update" button.

6.C. Permanently Delete Project

Delete your project and all data associated with the project, including sequence files and database records, BLAST result files and database records, and all your favorite categories.

Note: Data deletion is permanent and there is no way to recall your data once deleted.