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.

1. Build database

1.a Start SyMAP

Project Manager

1.b Load Project

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.c 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.d Align&Synteny

For the display buttons, see User Guide.

1.e CPU and Verbose

• Enter the maximum number of CPUs to use for the alignments.
  For example, if there are 8 alignments to be done, it will perform 4 at a time.
• Alternatively, the number of CPUs may be entered in the symap.config file or
  using the command line argument ./symap -p.

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.
• This can also be turned on using a command line argument ./symap -v.

1.f Additional information

2. Load Project Parameters

2.a Parameter panel

The Selected section of the Manager Click the Parameters link for a project to open the parameters panel shown on the right. Make sure these two parameters are correct before running the alignment: Minimum length, Sequence files. These are described in 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

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 right; the top chromosome images do not have it 'chr' removed and the bottom do. 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. 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 "Chr1", "Chr2", etc, and "Chr" 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, a prefix cannot be added to the sequence names. 5. This is case-insensitive.

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, as described in 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 Anno keywords or Anno files is 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 for Anno keywords, the Name=value would not be part of any gene annotation. This must be set before Load Annotations is executed.

2.f Saving project parameters

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

The params.txt file parameters are shown on the Project Parameters panel. These can only be viewed and changed using symap (not viewSymap). Do not edit params.txt with a standard editor.

3. A&S 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. Cluster Hits Use Selected Redo directly; the existing alignments for the pair will be used. Synteny If only synteny parameters are changed, click the lower-left drop-down and select Synteny Only (see drop-down). If the Align&Synteny has already been run, the last row will have an extra drop-down, as shown below (see drop-down):

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

All MUMmer files but the those with the .mum suffix are removed by symap. If you prefer them not to be removed, use the "-mum" command line parameter, i.e.

 ./symap -mum

3.c Cluster Hits

3.c.I Algo1 vs Algo2

Algo1 is the default for self-synteny and if there is no annotation; else Algo2 is the default.

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 includes 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.)

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

Defaults: Algorithm 1 (Algo1): If at least one project does not have annotation or it is self-synteny. Algorithm 2 (Algo2): If both projects have annotation and it is not self-synteny. The image on the left shows the defaults for Algorithm 2.

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 assigned. 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, go to the Pair Parameter panel, and select Number Pseudo in the lower-left drop-down; only this algorithm will be run. 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 C5) that link to repetitive genes on the right (Arab Chr02). These are important to keep. The right image shows a pile of hits in an intergenic region (Cabbage 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

The image on the left shows the defaults. The one exception is that Strict is turned off for draft sequence.

If the Align&Synteny has already been executed, and you want to try different synteny parameter, you may just run the synteny algorithm as described in Save.

See Synteny results for comparison of using the different synteny parameters. The following is a brief comparison of three images of 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 Draf->Seq2 and Seq2->Draf 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 option was not set, it can be set and the Synteny Only setting used (described below in 3.e Save).

Hints about synteny parameter settings

It is easier to experiment with synteny parameters since Synteny Only can be used to speed it up. For two genome complete sequence synteny, it is strongly suggested you start with Strict.

→ Suggestion: For large genomes, experiment with the parameters on just one or two pairs of the chromosomes; you can use xToSymap for the split. Note: the synteny results of one or two chromosomes will be slightly different compared to whole genome synteny.

3.e Save

Lower-left drop-down

If the Align&Synteny has already been run, the lower left side of the parameters window will have a drop-down with the following options:

Manager: The Selected Pair button will have its label replace to reflect the drop-down setting, as follows:

  Clust&Synteny → Selected Redo
  Synteny Only  → Synteny Only
  Number Pseudo → Pseudo Only

If you have changed the alignment parameters, you must remove them using the Clear Pair option on the Manager panel.

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).

4. Synteny parameter comparisons

Original vs Strict: Both allow a mix of inverted and non-inverted hits in a block, but Strict only allows small inversions within a non-inverted block and vice-versa (unless Merge is used). The Strict blocks tend to not have the tails of dots that have bigger gaps.
Original	Strict
Original chr1&chr7	Strict chr1&chr7
Orient: This requires all hits in a block to be in the same orientation. This options fits with what some other software packages consider 'synteny'.
Original Orient chr1&chr7	Strict Orient chr1&chr7
Merge Overlap: Only overlapping blocks can be merged. This will have little effect if Orient has been used since mixed blocks cannot be merged.
Original Merge Overlap chr1&chr7	Strict Merge Overlap chr1&chr7
Merge Close: Blocks that are close can be merged.
Original Merge Close chr1&chr7	Strict Merge Close chr1&chr7

Email: cas1@arizona.edu