Contents

Its features include the following (for a pictorial introduction, see the Tour):

GUI manager to run synteny computations and view results. Multiple display modes (dot plot, circular, side-by-side, closeup, 3D). Draft sequence ordering by synteny, i.e. align a draft genome to a fully sequence (not draft-to-draft). Construction of cross-species gene families. Complete annotation-based queries. All displays accessible through the web. Can align FPC maps to sequenced genomes.

Publications

        C. Soderlund,  W. Nelson, A. Shoemaker and A. Paterson (2006)
        SyMAP: A System for Discovering and Viewing Syntenic Regions of FPC maps 
        Genome Research 16:1159-1168.

        C. Soderlund, M. Bomhoff, and W. Nelson (2011) 
        SyMAP: A turnkey synteny system with application to plant genomes.
        Nucleic Acids Research 39(10):e68.

Getting Started

Follow the steps below to get started with SyMAP. If you are working with FPC files, see also here; for problems, see troubleshooting. Note that each SyMAP application window has a separate Help button providing further details on the use of its functions.

1.	Use a Linux or Mac machine.	It needs to have Java v1.6 or later, and sufficient processing power. See system requirements.
2.	Prepare sequences and annotation.	Sequences can be in one or many files and can be masked or unmasked. See preparing the sequences. Annotation format is gff3; see annotation files.
3.	Download SyMAP.	Installation is a simple unzip. See installation.
4.	Run the demo.	Highly recommended. See running the demo.
5.	Set up MySQL.	SyMAP can run on its own but we recommend that you use a separate MySQL installation, which can be on any machine. See SyMAP and MySQL.
6.	Import your files.	The Manager interface makes this easy; see creating a new project.
7.	Compute alignments and synteny.	This also easy through the Manager interface. See runtime and memory.
8.	View results.	These functions are located on the Manager interface. Detailed description of the user interface is in the User Guide.
9.	Share through the web.	A web install script is provided; see web display.

System Requirements

SyMAP runs primarily on Intel systems with Linux or Mac OSX (tested on OSX 10.6.8 and 10.8.3). Windows is supported for viewing and querying only.

For performing large alignments (e.g. 1Gb genomes or more) it is essential to have multiple CPUs, a 64-bit computer, and at least 5Gb of RAM for each CPU that you intend to use. (Note that you can set the number of CPUs for SyMAP to use).

For viewing alignments, CPU and memory needs are typically negligible, unless you are performing queries on more than 4-5 genomes at once.

Installation

Installation simply consists of unzipping the download package, using the command

     > tar -xzvf symap_42.tar.gz

This can be done anywhere and creates a directory called symap_42. You can move this directory later if desired.

To run SyMAP, change into the symap_42 directory and run the command

     > ./symap 

Running the Demo

If you have not used SyMAP before, it is essential to run the demos. You can run them immediately after unzipping the package; it is not necessary to install MySQL (on Linux only) because a Java-controlled version of the database is included in the package.

Change into the symap_42 directory. If you have mySQL on your machine, then edit symap.config and enter database and host information (see SyMAP and MySQL). If you have Java 3D on your machine, then enter ./symap else enter ./symap -no3d Many lines of text will print to the console, as SyMAP launches the supplied MySQL database. When this is done, the Project Manager window opens, shown at right. (Click Images for larger version)   There are four demo projects listed on the left. Check "Demo-Seq" and "Demo-Seq2". A link "Load All Projects" will be displayed in the top of the right panel; select it to load the projects, which will take several minutes; when done, the Manager will look as shown in the image. In the "Available Syntenies" table, click the cell for the "Demo_Seq2" row and the "Demo_Seq" column. If you have two CPUs available, set the "CPUs" setting to "2". Then click the "Selected Pair" button to start the alignment.   The alignment will take about 30 minutes (15 with two CPUs). When done, the table will have a checkbox, signifying that the synteny is available for viewing. Click the cell again which will enable the viewing buttons, e.g "Dot Plot".   Click "Dot Plot" and you will see the dot plot shown here. By clicking and/or selecting regions you can zoom into certain regions and bring up detailed views of the alignments. The Help button (question mark) provides full information on the functions.   Return to the Manager, and click the "Chromosome Explorer" button. This brings up the Explorer, shown at right. (If this does not work, restart with symap -no3d; the 3D view on the right will not be available). Here you can pick different sets of chromosomes, using the small icons at left, and see them in different views. At first you only see the reference chromosome, which is initially chr3 from Demo-Seq (the reference has a red box around its number). Click on the icons for Demo-Seq2 chr1 and chr3, to see the 3D view at right. The ribbons represent synteny blocks (green for inverted).   Click the "Circle" button to see a Circos-style3 display of the same chromosomes:   Click the 2D button to see a side-by-side view of the same chromosomes. Note that the reference is in the middle. Brown lines show the individual anchors (see how symap works).   Selecting a region on one of the sequence tracks using the mouse zooms to that region. Now the annotation icons (blue) for individual genes can be seen in the center of each sequence track. If you zoom in even closer, then you can click the "Sequence Filter" button and the top of a sequence track (or right click in the sequence), and check "Show Descriptions for Annotations", and you will see the annotation text for each gene.   Returning to the Manager, click the "SyMAP Queries" button. This brings up the SyMAP Query window in Overview mode. Click the "Query Setup" option on the left-hand side and you will see the Query Setup window: The query does two basic things: A. Locate syntenic regions based on annotation B. Create putative gene families across the species by grouping the genes (or regions) which are connected by anchors.   Enter "glycosyl" for the "Annotation String Search" and press "Do Search". 55 results are returned. Click the "PgFSize" column header to sort by this column, giving the table at right: Each row is an anchor connecting two of the chromosomes. At the top of the table are 7 anchors grouped into a putative family (PgeneF=25 in the image, but it may be numbered differently when you run it). The rows with a non-empty "BlockNum" are anchors involved in synteny blocks. You could restrict the query to only these anchors, if desired. Synteny anchors are more likely to represent a true ancestral relationship; however, synteny blocks can not always be detected in sparser regions. If you query with more than two species, you can ask interesting questions such as "show me the glycosyl-related gene families which are present in species A and B but not in species C".   The remainder of the demo relates to draft sequence, i.e. unanchored shotgun sequence. If you aren't working with draft sequence, you can skip to Creating a New Project.   Return to the Manager and load the Demo-Draft project, following the same steps used to load the previous two projects. On the Summary List, under the Demo-Draft listing, you will see the parameter "Order Against: demo_seq". With this setting, the Demo-Draft contigs will be ordered using synteny to Demo-Seq, as soon as that alignment is run.   Use the "Selected Pair" button to align Demo-Draft and Demo-Seq, as before. The alignment will take about 20 minutes. When done, open the dot plot for this pair and you will see that the draft contigs have been ordered and oriented to agree with the Demo-Seq. (For real projects the agreement will not be so good!)   The ordering on Demo-Draft is in the database only; it does not change the sequence files on disk. However, SyMAP does write out ordered "pseudomolecule" files created from the draft contigs. These are put in the form of a new SyMAP project which can be loaded and aligned. You will see this new project in the Projects panel, as shown at right. A text file showing the ordering information is also written to the Demo_Draft project directory, which you can find under the data/pseudo subdirectory of the symap directory. This is the end of the demo. At this point you will probably want to proceed by reading the next section to learn how to create your own project in SyMAP.

Creating a New Project

To create a new project, start symap (i.e. ./symap and press the "Add Project" button at the lower left. Enter the name and type of the project. The Help button on the dialog provides further information.

After saving the new project, it appears in the Projects list on the left, but it is still an empty shell. Check its box and it will appear in the Summary section (right hand side) where you will then click the "Parameters" link to open the Parameters window.

On the Parameters window you will add the filenames for the sequences and annotations for the project, as well as setting other parameters if desired. The Help button on this window provides the necessary details.

After setting parameters, the project is ready to be loaded and aligned using the same steps as in the demos.

Preparing the Sequences

Masking is not really necessary unless the genome is highly repetitive and those repeats are shared with other genomes being aligned. (Repeats cause particular trouble for self-alignments, see self-alignments in SyMAP).

Another masking option which is available if you have gene annotation is to mask out everything but the annotated genes. You can enable the "mask_genes" option on the Parameters window for your project (turn it on before doing the alignments).

Note that sequence files should be in FASTA format and the name of a sequence is the string immediately following the ">", e.g.

>chr3  oryza sativa
GAATTCGAATTTGGGTAATGCTAATCAATACAGGTCAAAATCTATGTATTGAGTGGAATATACTGCAAAGTAATTACCTT
CTTCCAAAGGAAAGCATTCCTTCTCTCTTGTGGGACTAGCAGATGATCTCGCAGCCAAGACGTGACCACCCAAGGCTCAC
...

Three things are important in naming sequences for SyMAP:

A.	Sequence names can contain only letters, numbers, and underscores.
B.	The sequence names must exactly match those used in the annotation files (first column), or the annotations will not be loaded.
C.	If possible, use a consistent prefix such as "chr" for all sequences, followed by a short number. If this is not possible, see note below.

Note: If you are unable to meet condition C, then you should set the parameter "grp_prefix" to the prefix of the sequences. SyMAP will then remove the prefix and use the shortened names in the displays, saving space. (If you set "grp_prefix", and some sequences don't have the prefix, they will keep their full names.)

Annotation Files

The last column (attributes) contains "tag=value" pairs describing the annotation. You can set which attributes to use, or use all those occurring more than a certain number of times (open the Parameters window for the project, look for parameter "annot_keywords").

Important: Only the annotation on "gene" entries is shown in the displays or used for searching. For entries "exon", "CDS", "gap", and "centromere", only the coordinates from the gff file are used; the annotation text is not read.

Working with FPC Files

Creating an FPC project is the same as for a sequence project except that you choose the type "fpc", and then the Project Parameters window has some different paramaters. The Parameters window is where you will enter the FPC file, and your fasta files of marker and BAC-end sequences.

Note that the BAC-end sequence names must be exactly the clone names used in FPC, with extension "r" or "f" labeling the strand. In other words if the FPC map has a clone "a0435B26" then the BES for that clone can be named "a0435B26f" or "a0435B26r".

The BES and marker alignments in an FPC project are performed using BLAT¹, in contrast to MUMmer² for sequence projects. The running time is typically several times longer than that of MUMmer (described here), but the memory usage is much lower.

SyMAP and MySQL

The MySQL installation does not need to be on the machine where you will do the computations or view the results, as long as it is on an accessible network. Once the server is ready, fill out the database parameters in the "symap.config" file in the main SyMAP directory, as described here.

Note that it is a good idea to have separate admin and client usernames, where the client has read-only access. If you set up the web displays, they will use the client username. The "admin" user needs to have sufficient permissions to create a new database.

Note that the default settings of MySQL are poorly suited for large-scale data storage. You will want to adjust the parameters innodb_buffer_pool_size,innodb_flush_log_at_trx_commit as described here.

MySQL on the Mac:
Download and install the "MySQL Community Server" from http://dev.mysql.com/downloads/mysql/. Also install the Preferences Panel, and use that to start the server. In symap.config, use

db_name             = symap
db_server           = localhost
db_adminuser        = root
db_adminpasswd      = 
db_clientuser       = root
db_clientpasswd     = 

The memory usage of MUMmer is typically 5G per CPU, however it can be as high as 10G for very long or repetitive chromosomes.

Web Display

SyMAP's Java-based architecture makes it easy to share results over the web. All you have to do is create a single html file with the following project-browser tag (edited for your parameters):

<applet  archive='symapApplet.jar'
    code='symap.SyMAPBrowserApplet'
    name='SyMAP'
    codebase='http://URL_TO_JAR_FILE_DIRECTORY'
    width='100%'
    height='100%'
> 
    <param name='database' value='jdbc:mysql://DATABASE_HOST_ADDRESS/DATABASE_NAME'>
    <param name='username' value=''> <!-- should be a READ-ONLY user!! -->
    <param name='password' value=''>
    <param name='title' value='SyMAP Project Browser'>
    <!-- param name='projects' value='maize, soy' --><!-- uncomment this line to show only certain projects -->
</applet>

You can also create custom pages showing dotplots, circle plots, and other displays using individual applet tags, following these examples:

Display Type	Example	Code
Block View (two species)		<applet code='blockview.BlockApplet' name='SyMAP' codebase='http://URL_TO_JAR_FILE_DIRECTORY' archive='symapApplet.jar' > <param name='database' value='jdbc:mysql://DATABASE_HOST_ADDRESS/DATABASE_NAME'> <param name='username' value=''> <param name='password' value=''> <param name='project1' value='grape'> <param name='project2' value='poplar'> <alt='The Java Applet is loading, please be patient'> </applet>
Circle View (multi-species)		<applet code='circview.CircApplet' name='SyMAP' codebase='http://URL_TO_JAR_FILE_DIRECTORY' archive='symapApplet.jar' > <param name='database' value='jdbc:mysql://DATABASE_HOST_ADDRESS/DATABASE_NAME'> <param name='username' value=''> <param name='password' value=''> <param name='project1' value='grape'> <param name='project2' value='poplar'> <param name='project3' value='soy'> <alt='The Java Applet is loading, please be patient'> </applet>
Chromosome Explorer (multi-species)		<applet code='symapCE.SyMAPAppletExp' name='SyMAP' codebase='http://URL_TO_JAR_FILE_DIRECTORY' archive='symapApplet.jar' > <param name='database' value='jdbc:mysql://DATABASE_HOST_ADDRESS/DATABASE_NAME'> <param name='username' value=''> <param name='password' value=''> <param name='project1' value='grape'> <param name='project2' value='poplar'> <param name='project3' value='soy'> <alt='The Java Applet is loading, please be patient'> </applet>
Dot Plot (multi-species)		<applet code='dotplot.DPApplet' name='SyMAP' codebase='http://URL_TO_JAR_FILE_DIRECTORY' archive='symapApplet.jar' > <param name='database' value='jdbc:mysql://DATABASE_HOST_ADDRESS/DATABASE_NAME'> <param name='username' value=''> <param name='password' value=''> <param name='project1' value='grape'> <param name='project2' value='poplar'> <param name='project3' value='soy'> <alt='The Java Applet is loading, please be patient'> </applet>
Query Interface (multi-species)		<applet code='symapQuery.SyMAPQueryApplet' name='SyMAP' codebase='http://URL_TO_JAR_FILE_DIRECTORY' archive='symapApplet.jar' > <param name='database' value='jdbc:mysql://DATABASE_HOST_ADDRESS/DATABASE_NAME'> <param name='username' value=''> <param name='password' value=''> <param name='project1' value='grape'> <param name='project2' value='poplar'> <param name='project3' value='soy'> <alt='The Java Applet is loading, please be patient'> </applet>
Alignment Summary (two species)		<applet code='symap.projectmanager.common.SummaryApplet' name='SyMAP' codebase='http://URL_TO_JAR_FILE_DIRECTORY' archive='symapApplet.jar' > <param name='database' value='jdbc:mysql://DATABASE_HOST_ADDRESS/DATABASE_NAME'> <param name='username' value=''> <param name='password' value=''> <param name='project1' value='grape'> <param name='project2' value='poplar'> <alt='The Java Applet is loading, please be patient'> </applet>

If one of the projects is an FPC project, indicate that with a parameter tag with type number corresponding to the project name tag:

<param name='type1' value='fpc'>

Database Parameters

Self Alignments and SyMAP