> Instructions

The Instructions window (on right) lists the projects which were selected for querying. The Notes states what the Olap column represents; if one or more project pairs used Algo1, it will be gene overlap; if all project pairs used Algo2, it will be exon overlap. Open the Query Setup window by clicking on its tab in the left panel.

> Query Setup

Rules

Set up the desired filters and then select Run Query to execute it. When the search is complete, the table result panel will be displayed. 1. Most filters can be used in conjunction with other filters; options will be disabled if they cannot be used with a selected filter. 2. The Single queries returns rows without a hit, and only list genes for one project. 3. All Pair hits queries return a row per hit pair, i.e. aligned region between two chromosomes from two projects.

All Hit# are uniquely numbered for a chromosome pair, e.g. there will be a Hit# 3 on all chromosome pairs that have hits.

All genes have a Gene#, which are sequentially numbered per chromosome, e.g. there will be a Gene# 3 on all chromosomes that have at least 3 non-overlapping genes. Overlapping genes have the same number, but different suffixes, e.g. 4.b. Major and Minor genes: A hit can align to multiple genes on either or both chromosomes; it is assigned to the best (major) gene on each end. For example, in the image on the right, the pink gene is the major gene as the hit (pink line) fits it best, whereas the burgundy gene is the minor gene. When queries involve genes, only the hits to the major genes will be shown except for the following queries, which will also list the minor genes:       Every*, Hit#, Gene#, and Multi with Minor* checked.

Not numbered: The Gene# column will show the chromosome followed by ".~". Numbered: These are numbered sequentially, where the counts start after the annotated gene numbers. For example, if the last Gene# for Chr03 is 5550 (e.g. 3.5550.), the first pseudo gene number will be 6000 and the column will show 3.6000.~.

Wait/Stop Query:

→ Wait for the current query to stop running before starting another!
It is not possible to start a new query from the same panel, but you could start one from a different table; they both will fail, so do NOT do this!

→Stop When a query is running, you will see a status line and the Stop button. It cannot stop the database search, but once the search is done, it stops all subsequent processing.

1. General

Annotation Description Enter a substring: the entire annotation string (i.e. column All_Anno) will be searched for the substring. Hits will be shown that have at least one gene, of two possible, with the annotation.

Location

The From and To are disabled for Single genes, Block#, Collinear set#, Hit#, and Gene#.

2. Single genes

The Single queries produces rows of genes; there is no hit or block information since the rows do not represent hits.

• Orphan genes (no hits)
  Genes that do not a have a hit and meet the additional filters. The orphan genes are relative to the projects shown on the Instruction page. For example, if species X, Y and Z have synteny computed between all pairs, but only X and Y are selected, the orphan genes for X would be those with no hits to Y. If X,Y&Z are selected, the orphan genes for X would be those with no hits to Y and Z.
   
• All genes (w/o hits), i.e. genes with and without hits
  This shows all genes that meet the additional filters, regardless if they have a hit or not. There is always the same set of genes for a project, regardless of synteny.

Unselect species: When the Single or Gene# is selected, the check boxes beside the species names will be activated. In order to view the genes from just one species, deactivate the others. Additionally, a single chromosome can be selected, but location cannot be entered.

3. Pair hits

Each hit connects two species (projects) and hence represents a pair of aligned regions for two of the selected species. Filters are as follows:

In Block (Synteny Hit)

Annotated (Gene Hit)

Collinear size

Enter value: For the following 4 filters, do not include the 'Chr' number. Instead use the chromosome pull-downs to narrow the search to a specific chromosome, as exampled in Block#.

Block#
Enter a single block number (the Block column is formatted Chr.Chr.Block#).
This will display all hits with this block number from any chromosome pair.

Example using the chromosome pull-downs: if you select Chr 1 from the first project, Chr 2 from a second project, and enter block=3, you will see hits in block 1.2.3.

Collinear Set#
Enter a set number (the Collinear column is formatted Chr.Chr.Size.Set#).
This will display all hits with this set number from any chromosome pair. See Block example.

Hit#
Enter a hit number. Both major and minor gene hits will be shown.
This will display all hits with this number from any chromosome pair. See Block example.

Gene#
Enter a Gene# number (the Gene# column is formatted Chr.Gene#.suffix, where suffix may be blank).
A row will only show if the gene has a hit. All hits with the Gene# on either end will be shown.
→ If a gene has a suffix:
 • If only a number is entered, all genes with the numeric prefix will be displayed (including minor hits).
 • If a number.suffix is entered, the exact gene will be displayed, including minor hits.
→ Select a chromosome:
 • The hit has to have one end to the chromosome, but the Gene# can be on either end.
 • By unselecting the other species (see Unselect species), the Gene# will only be on the specified end.
→ Group:
 • When a gene hits multiple places on the same opposite chromosome, the hits are put in a group
   (see Group column), which can be viewed with the 2D Group pull-down option (similar to Multi-hit).

4. Compute Groups

These two options are computed on the fly. They produce query results with values for the Group column; this in turn allows the View 2D Group option to be used.

4.1. Multi-hit genes

List all genes that have >= N hits to the same species.

• The target gene refers to the gene with >= N hits to the opposite species.
• The target must be a gene, but it can be to non-gene hits on the opposite species.
• Used with the following filters:
  • Both (Annotated Genes): if selected, the opposite species must also have a gene hit.
  • Chr: If one or more chromosomes are selected, the target genes will only be on those chromosomes.
• See Multi-hit Gene Report... for a good way to see a condensed view of the results.

The table can list the same hit multiple times, because gene X and gene Y may be connected by a hit, and both genes have >=N hits, so the hit in both groups need to be shown. An example is shown on the right, where Hit#881 is in both Atha Group#3 and Brap Group#15. The image below shows the two groups, where the group hits are highlighted in magenta; these were produced using the View 2D option Group (selecting any hit in the group results in the same 2D display).

4.2. Cluster genes

• This algorithm finds clusters of overlapping genes. That is, every gene in the cluster aligns to at least one other gene in the cluster, and all genes that align to any gene in the cluster are included.
• Each cluster is given a group number, which is shown in the Query Results table (column name Group).
• These can be pre-filtered by species chromosome, One gene, etc.
• Pseudo (un-annotated) will be included if they are number.

If there are only two species, the only filter will be >=N. For more than 2 species, the filters are shown on the right.

Alternative algorithm:
PgeneF: If you start viewSymap with the "-g" flag, you will see the filters from the original PgeneF cluster algorithm. →Note: the PgeneF feature has not been tested for a long time except superficially (i.e. making sure it has the same results as the previous release).

If you start viewSymap with the "-g" flag, you will see the filters as shown on the right. The one addition to v5.6.3 is the >= N hits filter.

Result Panel

1. Results Table

• Pair Hits:
  • The table contains columns for all of the selected species, but each hit only connects two species, and the other species columns are empty.
  • Each Hit# is only listed once unless minor genes are included (see Rules).
  • A gene may be listed more than once if it has multiple major hits.

• Single genes:
  • If the query specified Single genes, then each row represents one gene and shows data only for one species.

You can sort the columns by clicking the column name in the table, and rearrange them by dragging the column name. You can add/remove columns using the Select Columns button at the bottom.

2. Columns

The buttons on the bottom will be Select Columns and Hide Stats. If Select Columns is selected, it changes to Hide Columns and the Hide Stats is replaced with the 3 buttons explained below.

In the column panel shown above, hover over a column name to see its brief description. Following are the full descriptions of the columns.

2.1 Pair hits columns

2.2. Single genes columns

Arab-Cabb orphans

Arab-Brap orphans

Arab-Brap-Cabb orphans

Gene #1.2 is an orphan for Arab-Cabb but has a count of 1 because it is not an orphan in Arab-Brap. It is not listed in the Arab-Brap-Cabb table because Arab-Brap has a hit to it.

2.3 Columns and order shown

The selected columns are saved between sessions (described below), but the order is not.

2.4 Auto-save columns

If you have multiple SyMAP databases, when you change between them the columns displayed are relative to the last SyMAP database queried (they may seem some what random to a different SyMAP database).

3. Statistics

Most of the statistics are self-explanatory except the following:

Annotated and Genes: The first is the number of hits that overlap one or more genes, where a gene can have multiple hits. The second is the number of Genes with at least one hit.

Groups: This statistic is only shown if the Group column is populated.
For Multi-hit Genes: there is a column with the number of groups with each of the other species. If there is over 2 species, this will also include the highest group number in parenthesis. For example,

  A.thal  Groups: #50 (50)    #142 (192)
  B.rapa  Groups: #618 (810)  #984 (1794)
  Cabbage Groups: #847 (2641) #495 (3136)

4. Top buttons

The Unselect All unselects any selected rows.

4.1 Show

4.2 MSA...

Select one or more rows from the query table. The sequences of the selected hit(s) are written out and a multiple alignment is created using either MAFFT (Katoh 2013 MBA:30) or MUSCLE (Edgar 2004 NAR:32). MAFFT can be run with multiple CPUs and the optional --auto option, where --auto takes longer but allows MAFFT to determine the best algorithm to use.

Merge overlapping hits Instead of repeating the alignment of identical regions, overlapping hits will be merged. The above shows that Atha.01 has 5 merged hits. Use gapless hits Multiple subhits can be clustered into one hit, where there are gaps between them. The subhits are concatenated together with 5 N's in between each non-overlapping subhit. This is important for long genes as found in humans, where there are often hits to exons with large gaps covering the introns. None of the above Align from the start coordinate to the end coordinate of each end of each selected hit. Trim There can be a long set of bases at the beginning or end of one sequence, these will be removed.

While aligning, the line at the top of the panel will state the number of bases aligned as shown on the right. The Stop does not stop MAFFT or MUSCLE, that must be done manually.

General Notes:
→ Wait for the current MSA to stop running before starting another!
It is not possible to start a new MSA from the same table, but you could start one from a different table; they both will fail, so do NOT do this!

→ Stop: This removes the tab from the left panel, but it does not stop the execution of MAFFT or MUSCLE.

• Their processes will be called muscle for MUSCLE and distbfast for MAFFT; MAFFT may have some other process running, but distbfast seems to be the one that takes the most time/memory.
• To stop: you can type top at the command line, copy the 'process number' beside distbfast or muscle, then at the terminal, type kill -p 'process number'.
• Make sure distbfast or muscle are stopped, as they take a lot of memory!
  However, if you do not see it, then it has completed.

MAFFT Notes:
→ All executables were removed that did not seem necessary. However, I may have removed one(s) that are used in certain unusual situations when --auto is used. Try again with --auto unchecked.
→ On Mac, if you are using MAFFT --auto, you may get a "Cannot be verified" for dndpre. See MacOS and external programs to fix this.

4.3 View 2D

This displays the 2D view for the selected entry (see 3-chromosomes). The region displayed can be specified by the drop-down beside the View 2D button, as follows:

Example:

The table below shows results from the Collinear search. The image on the right shows the 2D for the set. After the initial display, the 2D view can be changed as described in the User Guide.   The table below shows results when the Group column has a value (using Gene#, Multi-gene or Cluster search). The Group option can be used with these rows.

4.4 Export...

CSV: Export the rows using the selected set of columns to a CSV format suitable for import into Excel. HTML: Export the rows using the selected set of columns to a HTML format suitable for viewing on the web (e.g. Example). The Include Row column option is available because this column is alway present, but it may be desirable to exclude it in the output. FASTA: (Pairs Only) For each row, the two hit sequences from the Hstart to Hend are written to file. NOTE: this is a very slow function and takes minutes if many rows are selected.

4.5 Gene Report...

• The report is on the genes in the query table; hits without paired genes are ignored.
• Unless the query is for Collinear, Multi-hit or Cluster genes, a Gene report will be produced.
• This is most relevant when used with >2 species. It has not been tested for >4 species.
• Gene, Collinear and Multi-hit genes produce a reference-based report whereas the Cluster genes does not; however Cluster genes shares most of the same options.

Reference-based Interface

The menu on the lower-right shows the options that will always exist. There may be additional options in between the middle lines, depending on the condition used to create the table, as discussed below.

Reference: In all cases, a reference must be selected; all reference genes are listed in a column, and any genes it links to (has a hit) are referenced in the other species columns. Gene Annotation Columns: One or more annotation keywords can be entered in a comma-delimited list (e.g. product, ID); the keywords must be found in the All_Anno keyword column. A column will be created containing the values of all entered keywords. Columns can be entered for any of the species (not just the reference).

Additional options for >2 species: The following options will be shown between the middle lines if there are >2 species. The options are explained with the respective report.

Link: This term is used to indicate that there is a hit between two species, typically non-reference species.

For all reports:

• The reference column is in italics. In the TSV file, the reference header has an '*'.
• The annotations correspond to the genes listed for the species. A "---" indicates that there is a gene with no corresponding annotation. If there is more than one gene in a column, the corresponding annotations will be separated by a ";".

Gene Report

Rows are always merged that share the same reference. The top line shows there are 15 single rows (one gene for each species) and 0 multi rows (multiple non-reference genes for at least one species). There are 2 multi rows in Mus11, where one is shown in the 3rd row.

A "=" indicates that the gene is linked to the gene next to it (ignoring the Reference column); a "+" indicates it is linked to the gene over one column (only happens when there are 4 species).

Collinear Report

The report on the right shows the first union of the A.thal collinear sets. This was generated with Per Union checked. The '1 [3 sets]' indicates it is the first union with 3 collinear sets. For the non-reference gene columns, by default, the collinear set size and number (size.setN) is shown. For example, row 4: Gene# Species Chr Collinear set 59 A.thal Chr01 6.6, 8.104, 8.1 5153.a B.rapa Chr09 6.6 28 B.rapa Chr10 8.104 1 Cabbage Chr05 8.1 The other genes in each collinear set are obvious since they share the same size.setN, e.g. #8.1 is shown in 8 rows.

Multi-hit gene report

The Group (size-number) is shown above each group. This used the Gene# option so it prefixes the annotations.

4.5.5 Cluster hit report

The cluster report has no reference, as shown on the right (i.e. no radio buttons for selection). Cluster gene - additional options (for any number of species) Display Linked rows Each row will be linked genes. Hence, a gene can be listed in multiple rows if it has multiple unique linkage patterns.   Unlinked unique Only the unique genes are listed along with how many links they have. There is no indication of what genes are linked (but this is faster then the above). Show Group Show the Group#(size-group number).

Unlinked unique: Cluster #1 (7-1) shows that there is only one Hsa gene, which has 4 links; likewise for the one Mus gene; however, there are 5 Pan genes. If there are only two species shown, then this is an easier way to view the results.

Linked rows: Every gene listed in a row is linked. The first row of 7-1 is the only one that is linked across all species. There are 229 fully linked rows in the 177 clusters; each one has the number of fully linked rows in parenthesis next the cluster label. This is the most informative when >2 species are included.

4.6 Search...

The Search... produces a popup as shown on the right. The columns in the popup will vary depending on the columns displayed in the table. This will only show the columns that are searchable. Besides the top 4 shown, the species Gene# and all of the Gene Annotation columns are searchable. Search results in the table positioning to the row with the first occurrence of the search string, and the row will be selected. Last# This searches on the last number of a "." or "-" delineated string, i.e. Block, Collinear, Group and Gene#. For a Gene# with a character suffix (e.g. 1.1.a for chr01, gene# 1.a), enter the 1.a. Exact This searches for the exact string. Substring This searches for a substring, which is most relevant for the Gene Annotation of 'desc' or 'product'.

> Results

All query results are listed under the > Results tab on the left. Clicking this tab shows the table of queries illustrated above. Query results can be displayed by clicking a result on the left panel, or double-clicking it in the list of results table shown above.

The only way to remove query results from the left tab is by selecting them in this table followed by Remove Selected, remove all with Remove All.

3-chromosomes

Select two rows with the following requirements: (1) Each row must have two genes. (2) There must be a shared gene. Different species Same species Select View 2D with either the Region and Collinear options. The image on the right used the Collinear options.   2D Highlight Conserved Genes shows how to highlight shared or unique genes in the 2D display of 3 chromosomes.

Email Comments To: symap@agcol.arizona.edu