2. If Perl isn t installed on your computer, download and run the appropriate installer from

Transcription

1 Instructions for using the Perl script BuildConsensusMap.pl Clare Nelson Dept. of Plant Pathology Kansas State University Introduction The script described in this guide is intended to be applied to a set of ordered genetic maps sharing some common markers. When the linear orders of the markers are in conflict in different maps, an analyst typically wishes to find out where these conflicts lie and how they may be most easily resolved. More generally, this program has nothing to do with genetics, but is applicable to any set of ordered lists of labels for which some of the labels are shared by some of the lists. But because it s written for geneticists and breeders, I ll stick to genetic terms such as map and marker. This guide is intended for analysts who may not be very familiar with running programs from the command line. It assumes you are working in the Windows operating system, but the script will work under Unix/Linux/OS X, since these OSs support Perl and gnuplot. However, in that case the output map won t be drawn since MapChart works only under Windows. How to start using the program 1. The FastCM directory contains 10 files. Place it anywhere on your hard drive. 2. If Perl isn t installed on your computer, download and run the appropriate installer from 3. Download and install gnuplot ( a free plotting program. 4. If using Windows, download and install MapChart, a free map-drawing program ( 5. Open a text editor, and from it open the BuildConsensusMap.pl script. You will need to make three changes: a) In the line use lib "C:/Code/eclipse/workspace/FastCM" substitute the path to the FastCM directory on your computer. b) In the line my $sgnuplot_path = "C:/Research/Software/gnuplot/bin/gnuplot.exe"; substitute the path to the gnuplot.exe executable on your computer. 1

2 c) In the line my $smapchart_path = "C:/Research/Software/MapChart/MapChart.exe"; substitute the path to MapChart.exe on your computer. Save the file (as text). 6. Data format Construct a spreadsheet in which each column contains a map title in the first cell, followed by marker names listed in map order. Leave no space characters in the sheet and no blank entries within marker lists. Marker names representing the same marker in different maps must be identically spelled, including case. Save as tabseparated text. If you have map position data, construct a position file in the same format as the marker file, except with map positions instead of marker names. The program will allow you to make either rank-based or position-based consensus maps. 7. Start MapChart before running the script. Otherwise the script will launch MapChart and show a map similar to the one in Figure 2, but will not launch gnuplot until MapChart is exited. If MapChart is already open, both plots will appear on the screen. 8. Open a console window and navigate to your data directory with cd and dir. At the prompt, type perl <path to your FastCM directory> bu and press the Tab key to have the shell complete the name for you. You should see something like this: perl C:\Research\Software\FastCM\BuildConsensusMap.pl Press the Enter key. You will now see the list of required and optional arguments. For your first try, you will need only the name of your map file, so press the up-arrow key on your keyboard to repeat the previous entry, and add the keyword -map followed by the name of your file: perl C:\Research\Software\FastCM\BuildConsensusMap.pl -map <map_file> Now press Enter. After a few seconds, you will see a gnuplot window similar to Fig. 1. You can assess the discordance remaining in the consensus map by the separation of colors across the main diagonal; if one half is solid black, a perfect map was possible. In Fig. 2 you will see a MapChart plot, in which each of your input maps is drawn beside the part of the consensus map containing its markers. 9. A rank-ordered map such as this one may be deceptive, because it assumes that in your marker list, all markers strictly precede or follow their neighbors, where in fact you may wish some markers to be considered as lying in the same bin and having no known mutual order. So that the program will take such ties into account, you can add your 2

3 position data. First, in your console window type quit in order to stop gnuplot and get your prompt back. Then, enter perl <path>/buildconsensusmap.pl -map <map_file> -pos <position file> where each of the expressions inside <> is to be substituted with the appropriate text. Figure 1. Optimization plot for consensus-map building. Upper plots show (left) a discordance plot, in which each cell in the ith row and jth column is colored if marker i precedes marker j in at least one input map; (right) an image of the input data, in which each row represents a map and each column a marker, and markers have been placed in optimal (least-discordance) consensus order; bottom: a trace plot of the ordering operation in which each of the horizontal tracks represents a single marker 3

4 Figure 2. Section of MapChart figure showing three rank-ordered input maps, with three consensus maps to their left. The orders of the consensus maps are identical, but the included markers and marker-label coloring differ according to the companion input maps. Description of arguments The words like -map that you type after the program name at the command prompt are keywords (known as switches) followed by the input values you wish the script to work with. Only the -map switch is required by our script, but the others are useful for changing the behavior of the script. When you call the script without providing the required -map argument (or enter -h as a switch), the required and optional arguments are shown as follows, instead of execution of the script. I won t explain the arguments in this short guide, but many of them are self-explanatory. Usage: perl c:\code\eclipse\workspace\fastcm\buildconsensusmap.pl -map Maps file: (ONLY REQUIRED ARGUMENT) -pos Positions file: cm positions file corresponding to the map file -con External consensus markers file: consensus-map names file -cpos External consensus positions file: consensus-map positions file corresponding to the names file -heatcons Plot input consensus heat map: plot the heat map for the input consensus instead of the built consensus (N, Y) -fwork Framework-markers file: file containing a subset of markers in an order required to be preserved -invert Invert ordering criterion: reverse the sense of consensus ordering (for some maps, reduces discordance) (N, Y) 4

5 -wts Map weights: weights string (1, denoting 1:1:1..., with a number for each of your maps) -fpp Futile polishing perturbations: number of futile polishing perturbation iterations, ditto (3) -fipi Futile interval-polishing iterations: number of futile interval-polishing operations, ditto (10) -u Use initial, not simulated, maps: make consensus from input maps (Y) or from maps simulated from single input map (N) -sim Simulation params: (only if simulating maps) num_maps:max num swaps:max swap range:max num drops (8:6:8:10) *** DISPLAY PREFERENCES *** -h Show arguments: show this usage message and exit, regardless of other arguments -gt Consensus global coloring: color consensus markers by global tension instead of input-map tension (N, Y) -heat Plot discordance heat map: show heat map of ordered consensus map (requires gnuplot) (Y, N) -pi Show iteration plots: show plot of iteration history (requires gnuplot to be installed) (N, Y) -save Save consensus: save output consensus map (Y, N) -oc Draw only common markers: for reducing size of MapChart plots (Y, N) -draw Draw maps: draw the consensus and input maps (requires MapChart to be installed) (Y, N) -cd Consensus draw interval: draw consensus every K maps (1) (possible: 0, 1, 2. 0 means only 1 consensus at left) -o Omit foreign markers: in each consensus, include only the markers present in the companion input map (Y, N) -mult Maps-to-nonsingletons drawing multiplier: Scale constant for raw-data heatmap height (10) -bound Compute optimization lower bound: Minimum possible discordance score for the input data set (N, Y) CAUTION: do not use if there are more than 150 nonsingletons! CAUTION: still under development and usually does NOT give the correct statistic. Don't forget to start MapChart before running the program -- see guide. 5

6 Figure 3. Consensus plots for seven input maps, showing the effect of not removing extraneous markers from each single-map-referenced consensus. The consensus maps, with colored labels, are drawn at the left of each input map. Compare Figure 2. Be aware that MapChart has some limits. FastCM does its best to set up the drawing parameters for MapChart, but sometimes does not succeed. 6