The original SyMAP was written for diverse plant genomes with short introns, but has been modified to work for the long introns of mammalian genomes, and less diverse genomes.

Start SyMAP

Project Manager

1. Build database

1.a Selected

For any action that will remove the project or alignments from disk, a popup will occur to confirm that you want this done! If it will be removing multiple alignment directories, it will prompt on each one.

1.b Available Syntenies

This section shows a table with the status of alignments between the selected loaded projects. Each cell in the table represents a pair of projects and the cell contains a status code showing whether or not that pair has been aligned (codes are listed below). Note that the table shows each pair cell twice, but only the lower cells are activated.

Clicking on a cell selects that pair of projects (the cell will be highlighted in green), and the buttons that can be selected are activated.

See Pair Parameters for additional information on the Available Syntenies and codes.

1.c Function Buttons

For the remaining display buttons, see User Guide.

1.d CPU and Verbose

Verbose checkbox:

• If checked, detailed summary information is written as it processes the MUMmer files. The information is written both to the terminal and the logs/<proj-to-proj>/symap.log file.
• If this is not checked, it will write status information repeatedly on the same terminal line.
• See Demo examples.
• It is not saved as a parameter. This can also be turned on using a command line argument: symap -v

2. Project Parameters

2.a Parameter panel

Click the Parameters link for a project to open the parameters panel shown on the lower right. Make sure these two parameters are correct before running the alignment: Minimum length, Sequence files. See Load project.   Sequence and Anno (annotation) files: If the files are put in the default locations, nothing needs to be entered for them. Default locations: data/seq/<project-name>/sequence data/seq/<project-name>/annotation See input for a description of the input files.

2.b Display

New values take immediate effect on Save. Most of the values are shown in the Selected section, as shown on the right. The values are saved in the symap_5/data/seq/<project-name>/params.txt file.

2.c Load project

Group prefix
The term "Group" is used for any FASTA sequence type, e.g. chromosome, scaffold, contig. This option sounds trivial but is important for a good display, so please read carefully the following.

1. When a Group prefix is entered, it allows SyMAP to remove the prefix from the chromosome names and use the remaining part as a shorter name (e.g. '1' instead of 'chr1', as shown on the lower right). 2. If the sequence file has a mix of prefixes (e.g. Chr01, Scaf2345): If a Group prefix is entered, only sequences with that prefix will be loaded. Leave the Group prefix blank will load all sequences; their prefix will not be removed (e.g. the 'chr3' in the image on the right). 3. Long names really clutter the display; it is best to use a consistent prefix that SyMAP can remove, otherwise, use really short prefixes, e.g. 's' for scaffold, 'c' for chromosome. 4. You may remove the prefix after the project is loaded. For example, if your sequences had names "Scaf1", "Scaf2", etc, and "Scaf" was NOT entered as the Group prefix before load, you may enter it later and it will be removed from all sequence names. However, this is not reversible and a prefix cannot be added to the sequence names.

Minimum length
This must be an integer, commas are allowed (e.g. 1,000,000).
This is the minimum length of the FASTA sequence that will be loaded; smaller sequences will be ignored. Note that annotations for ignored sequences will also be ignored, but some warning messages will be printed to the terminal. See xToSymap Length for help with setting this parameter.

Sequence files
Select the input FASTA sequence file(s), or directories of sequence files. For formatting, see Sequence files. Default location: data/seq/<project-name>/sequence

If any either the sequence files or Minimal length parameters are changed:
▸ If the project has already been loaded, Reload Project.
▸ If A&S has previously been run, select Clear Pair and remove the alignment files, then run A&S.

2.d Load annotation

Anno keywords
A comma separated list of keywords. This can be used to reduce the annotation attribute keywords shown in the 2D display and Queries table. See the GFF Attributes section below.

Anno files
Select the input GFF3-formatted annotation files corresponding to your sequences. Note, using a GFF3 file directly can cause problems if it does not conform to what SyMAP expects; see Annotation files. Annotation is optional but highly recommended. Default location: data/seq/<project-name>/annotation

If either of the above are changed:
▸ If the annotation has already been loaded, Reload Annotation.
▸ If A&S has been previously run, re-run A&S (the existing alignments files will be reused).

2.e GFF Attributes

The gene annotation is shown on the 2D display and as columns in the Queries results table. The attributes (annotations) comes from the last column of the GFF file. The attributes are a keyword=value list, e.g.

   ID=gene-AT1G01010;Name=NAC001;ID=rna-NM_099983.2;product=NAC domain containing protein 1

If there are many different keywords in the attribute list, this causes too many columns in the Queries table. This can be reduced by one (or both) of the following:

Anno key count: If there are many different keywords in the attribute list, set this count N to filter out all keywords with <N occurrences. The Anno key count can be modified at any time using symap (not viewSymap).

Anno keywords: The keyword=value pairs to be saved for each gene can be limited by listing the desired keywords separated by commas. Using this approach, it will also reduce annotation description per gene in the 2D display. Referring to the example above, if the string "ID, product" was entered, the Name=value would not be part of any gene annotation. This must be set before Load Annotations is executed.

2.f Rules for saving project parameters

  data/seq/<project-name>/params.txt

When the project is loaded, all parameters are saved to the database except the A&S parameters (Mask-genes and Order-against). When the A&S is executed, then the corresponding parameters are saved to the database.

Any parameter that does not have the default value will be shown on the View popup.

3. Pair Parameters

3.a Parameter panel

The table on the right has cells that have the following completed: Value Alignment Synteny blank No No A Yes No ✔ Yes Yes

Alignment will not be redone if the cell contains an A. This is important because MUMmer is very time-consuming, but the synteny computation is not (see timing results); hence, one can make changes to the cluster or synteny parameters and re-run without redoing the alignments. Select a pair cell in the Available Syntenies table followed by the Parameters button, which will popup the panel shown on the right. If a ✔ or A in pair cell exists and the parameters for a section are changed, do the following: Changed Section Action Alignment Select Clear Pair to remove the existing alignments, then Selected Pair (ReDo). Cluster Hits Use Selected Pair (ReDo) directly; the existing alignments for the pair will be used. Synteny Use Selected Pair (ReDo) directly; the existing alignments for the pair will be used.   The parameters are described in the following 3 sections: Alignment, Cluster hits and Synteny.

3.b Alignment

Preparing the sequences

Concat: The following statistics are from comparing Arabidopsis thaliana (119M) against Brassica rapa (297M) on a MacOS using 1 CPU.

48819 hits
  334 synteny blocks
46319 gene hits
38334 synteny hits

Finished in 1 hour 8 minutes

48846 hits
  334 synteny blocks
46348 gene hits
38345 synteny hits

Finished in 1 hour 35 minutes

MUMmer parameters

3.c Cluster Hits

3.c.I Algo1 vs Algo2

Algo1 is the default since it works for all inputs.

Wrong strand The wrong strand is when all hits in a cluster are to the same strand (++/--) yet the cluster aligns to two genes on the different strands (+-/-+), or vice versa.

Algo1 does include these hits. You can view them in the Queries where the Hit St column will be different than the two gene Gst columns.

Algo2 does NOT include these hits. You can request to view the potential hits during the A&S by running it with the "-wsp" flag, i.e. ./symap -wsp . This will only show gene pairs with (1) multiple hits to exons (in one or multiple gene pairs), (2) at least one is not an overlapping gene. It is up to the user to determine what is real.

Hints about parameter settings

Hint for Algo1: Increasing the Top N parameter can cause too many hits and reduce synteny. Decreasing it can remove more gene-pair hits. Hence, try Algo2 if you want more gene pairs.

Hint for Algo2: On the output to the terminal (in Verbose mode), if any chromosome pair shows over 10,000 hits, the parameters probably need to be made more stringent; too many hits confuses the synteny algorithm, which results in synteny blocks not being found; it also results in very long execution time.

→ Suggestion: For large genomes, experiment with the parameters on just one pair of the chromosomes. (You can use xToSymap for the split.)

→ Using the v5.6.0 algorithm, I have experimented with the datasets (1) human, chimpanzee, mouse (2) Arabidopsis, Brassica rapa, Brassica oleracea. Only B. rapa to B. oleracea needed parameter adjustment: the number of G1 hits was over 200k, which is way more than typical; by increasing all parameters a small amount, this reduced to just over 100k.

3.c.II Parameter description

3.c.III Pseudos and Piles

The end of a hit may not overlap an annotated gene; by default, this will just show a Gene# of 'N.~' where N is the chromosome number. If Number Pseudo is selected, a pseudo Gene# will be created. The counts start after the annotated gene numbers and are suffixed by "~". For example, if the last Gene# for Chr03 is 5550 (e.g. 3.5550.), the first pseudo gene number will be 6000 (e.g. 3.6000.~).

If A&S was run without numbered pseudos, you can add them later by executing: ./symap -pseudo; the Selected Pair button will be replaced with Pseudo Only, which will just do the numbering (the Number Pseudo will need to be selected, but it will remind you). This cannot be undone; you would need to re-run A&S with the Number Pseudo unchecked to remove them.

Piles of Hits

The below image shows a pile of hits on the left (Cabb Chr02) that link to repetitive genes on the right (Arab Chr05). These are important to keep. The right image shows a pile of hits in an intergenic region (Cabbagge Chr03) to multiple other regions (B.rapa Chr01). There are MANY occurrence of repeats like this in the MUMmer file, which is why these piles must be filtered; if they are not, the synteny algorithm does not perform well.

3.d Synteny

¹Same orient uses the same algorithm as the original except that it evaluates the hits for one orientation, than the other. It also adds a constraint that the correlation must be positive for blocks of hits in the same orientation, and negative for opposite orientation.

²Merge may be beneficial when there are many small blocks. Below shows an example where the first image does not have merged blocks and the second does (the blue dots are hits that belong to the block).

The following three images show the same regions when evaluated with the following 3 parameter sets:
Default (one block)                Same orient (three blocks)          Same orient with Merge (two blocks).
In the last image, the reverse orientation block is embedded in another block

Order against

The Seq1->Seq2 and Seq2->Seq1 use the Abbreviation set in the Project parameters panel. The "->" indicates that the first sequence will be ordered against the second.

If the draft has been aligned to the Order against sequence, but this parameter was not set, it can be set and the A&S run with the existing alignment files.

3.e Rules for saving pairs parameters

  data/seq_results/<proj1-to-proj2>/params.txt

The file parameters are shown on the pair Parameter panel. These can only be viewed and changed using symap (not viewSymap).

Any parameter not the default will be shown on the Summary page.

BEWARE: If you run A&S, then change the PROmer or NUCmer settings, but forget to Clear Pair before running A&S again, the parameters on the Summary page will be wrong (SyMAP does not check for this situation).

3.f MUMmer parameters

To see the parameters for the default MUMmer V3 on MacOS, from the symap directory:

./ext/mummer/mac/mummer -h
./ext/mummer/mac/promer -h
./ext/mummer/mac/nucmer -h

./ext/mummer/linux/mummer -h
./ext/mummer/linux/promer -h
./ext/mummer/linux/nucmer -h

./ext/mummer4/m4/bin/mummer -h
./ext/mummer4/m4/bin/promer -h
./ext/mummer4/m4/bin/nucmer -h

After running MUMmer, all alignment files are removed except the ".mum" file; to prevent removal,
execute ./symap -mum.

Email Comments To: symap@agcol.arizona.edu