M(ARK)S(IM) Dec. 1, 2009 Payseur Lab University of Wisconsin

Transcription

1 M(ARK)S(IM) Dec. 1, 2009 Payseur Lab University of Wisconsin M(ARK)S(IM) extends MS by enabling the user to simulate microsatellite data sets under a variety of mutational models. Simulated data sets are output in STRUCTURE or whitespace-delimited format. For convenience, SNP-based data sets consisting of SNPs, SNP haplotypes, or SNPSTRs (a composite marker consisting of a linked SNP and microsatellite) may also be produced. In the case of SNP data, you may also choose to output the simulated data in SMARTPCA format. The user runs M(ARK)S(IM) by editing a parameter file to suit his or her needs and initiating the program from the command line. This program does not include extensive exception handling, so it is important that the user take a few minutes to become familiar with the entries of the parameter file. 1

2 2 1. INSTALLING, COMPILING, RUNNING M(ARK)S(IM) is written in C++ and requires the user to have MS installed in the M(ARK)S(IM) directory. See Hudson (2002, Bioinformatics, 18: ) for details regarding MS. M(ARK)S(IM) makes liberal use of the regular expression library boost::regex written by John Maddock. The BOOST libraries are bundled with M(ARK)S(IM) and the regex library must be installed and built before M(ARK)S(IM) itself can be compiled. The instructions given here have been tested on Linux (Ubuntu Hardy Heron and Red Hat Enterprise 5) and MacOsX. It should be possible to compile M(ARK)S(IM) on Windows, but we have not confirmed this. As a first step in this regard, however, you would need to obtain a zip file of the BOOST distribution specific to Windows from boost.org and follow installation instructions specific to your operating system. Since the installation of BOOST may cause users some headache, we have also written a Perl script that has a more limited scope of functions. The advantage is that this script does not require boost::regex and should be platform-independent. On the other hand, it is significantly less efficient than the C++ version, though this should only matter if you re generating 10 4 data sets or loci per data set. Please contact us at haasl@wisc.edu if you would like the script Unpacking M(ARK)S(IM) Move marksim.tar.gz to the desired directory and run: tar -xvzf marksim-0.1.tar.gz 1.2. Installing boost::regex Install and build the boost::regex library with:

3 3 cd boost/libs/regex/build make -fgcc.mak (This will take several minutes.) Finally, create a symbolic link to the regex file: cd../../../.. ln -s./boost/libs/regex/build/gcc/libboost regex-gcc-d-1 40.a regexlink 1.3. Compiling M(ARK)S(IM) Then, compile M(ARK)S(IM) with: g++ -I boost marksim.cc -o marksim regexlink 1.4. Backing up the parameter file It s a good idea to backup the parameter file params in case you edit it beyond recognition. You can accomplish this by running: cp params paramsbackup Then, should you need to recover the original params file, run: mv paramsbackup params 1.5. Running M(ARK)S(IM) Type./marksim If you haven t modified the parameter file, the first run will generate 10 data sets in STRUCTURE format, each comprising 10 unlinked loci, modelled under the stepwise mutation model (θ=10, no ascertainment bias) and sampled from 2 isolated populations (MS divergence parameter set to 0.025),

4 4 25 diploid individuals each. 2. EDITING THE PARAMETER FILE params TO MEET YOUR SIMULATION NEEDS In order to obtain simulated data sets of relevance to your study, modify the parameter file params. The following section explains the various parameters that you can manipulate. If you only modify params it is not necessary to recompile marksim.cc. Should you modify any of the source or header files, it is of course necessary to recompile for any changes to take effect. While editing params, take care not to add extra lines, remove backslash characters, or change parameter names. If you do alter params to a point of no return, follow the instructions in section 1.4 to recover the original params file. VERBOSE Values: 0, 1, 2 If set to 1, the current data set will print to the screen. If set to 2, the current locus will also print to the screen. FILEPREFIX Values: Any string with no white space. e.g., marksim output Each data set will spawn a separate file. The name of each output file will begin with this prefix. FORMAT Values: 0, 1, 2 STRUCTURE formatted files (value 0) assume diploid individuals. The first column is the individual s identifying number, the second column specifies

5 the population to which the individual belongs, and the third column is set to 0, specifying that population membership information should not be used. See the STRUCTURE manual for more information. If you care to change the third column to 1, open the header file Datasets.h and find the line: outstar << samplenum << " " << pop << " 0 "; Change the 0 to 1 and recompile marksim.cc. Also note that the genetic data for each diploid individual spans two rows in the output file. SMARTPCA formatted output (value 1) spawns 3 files per data set (with suffixes.ind,.geno, and.snp). All of these files are necessary for running SMARTPCA. In the.snp file, dummy chromosome numbers as well as genetic and physical distances are used. These will not affect the SMARTPCA run, but won t do you much good if your aim is to use this type of information in your simulation study. The SMARTPCA output is only meant for use with SNP (ISM modelled) data, although choosing this format in conjunction with other mutation models will not crash the program. Also note that diploid data are assumed, as the.geno file is created by adding the SNP values of two randomly chosen chromosomes together. Whitespace delimited output (value 2) prints haploid data one chromosome per line. Only genetic information is output. However, the lines are ordered. If you simulate two divergent populations, for example, all the chromosomes from one population are printed first, followed by all the chromosomes from the second population. 5 THETA Values: > 0 The θ value specified here only applies to microsatellite data and SNP haplotype data. SNP data and the SNP components of SNPSTR data are unaffected by this parameter. In these latter two cases, the simulated SNP is assured to be polymorphic and θ has no effect on where the mutation falls

6 6 on the genealogy. Regardless, you should keep a place-holding number here even when simulating SNP data. LOCI Values: 1+ DATASETS Values: 1+ MSCOMMAND Values: an appropriate string starting with./ms and ending with -T >ms outfile You can make the MS command as complicated as MS will allow. However, there are several things that must be included in your MS command designation. First all MS commands must begin with./ms. Second, make sure that the -T flag is included near the end of the command. Third, make sure the last item in the command is >ms outfile. Fourth, make sure replicate number is always set to 1, where replicate number is 1 in the command that begins./ms I... Also understand that M(ARK)S(IM) produces data from unlinked markers. Thus, specification of recombination in the MS command is generally nonsensical. Finally, specification of θ via the -t switch is not necessary. If you do use the -t switch, whatever you enter there is overridden by what you specify for THETA in the PARAMS file. P Values: [0.01, 1.0] The value of p only applies to the GSM. p is the probability of single-step mutation. Probabilities of mutations > 1 step size are drawn from a geometric distribution parameterized by p. Regardless of the mutation model selected, you do need to have a place-holding number here.

7 7 MODEL Values: 0, 1, 2, 3, 4, 5 Value 0 specifies the stepwise mutation model for microsatellites. Value 1 specifies the generalized stepwise mutation model for microsatellites. Value 2 specifies an approximately infinite alleles model for microsatellites. Value 3 specifies SNP data under the infinite sites model. Value 4 specifies SNPSTR data. A SNPSTR is a composite marker consisting of a microsatellite (SMM modelled) and SNP locus. SNPSTR alleles are represented as a single integer in the output data file. The microsatellite allele is multiplied by 100 if it is linked to the derived SNP allele and unmodified if it is linked to the ancestral allele. A sample of SNPSTR alleles might therefore look like this: Value 5 specifies SNP haplotype data. This will not work with SMART- PCA output. Each unique haplotype is assigned a corresponding integer. As mentioned above, the value of θ specified in the params file does apply here. Recombination is not modelled, so only low values of θ should be specified in the params file. Specified ascertainment will have no effect on SNP haplotype data. MONOMORPHS Values: 0, 1 If you specify 0, the program will discard any monomorphic loci. You will still end up with the specified number of loci, because the program continues to work until the desired number of polymorphic loci are generated. Of course, this may noticeably increase run time when θ is very low. SNP data (model 3) are always polymorphic, regardless of the setting here. ASCERTAINMENT

8 8 Values: 0, 1 Value 0 specifies no ascertainment bias. Value 1 specifies that ascertainment bias should be modelled according to the values entered in ASCSAMPLESIZE and ASCHET. ASCSAMPLESIZE Values: 5 and size of first (or only) population This parameter value specifies the number of chromosomes you want to use to assess diversity at a locus. Ascertainment samples are always drawn from the first (or only) population. ASCHET Values: [0, 1.0] This parameter value specifies the minimum value of heterozygosity you re willing to accept at a locus. Although, you can choose values between 0 and 1 inclusive, realize that 0 eliminates ascertainment bias. Conversely, high ASCHET values may be unattainable, especially if ASCSAMPLESIZE is low. In the latter case, the program will continue to work and work, searching for an impossible level of heterozygosity. ISLANDS Values: appropriate integers If you specify multiple populations in your MSCOMMAND, the number of chromosomes sampled from each population must be exactly specified here. For example, if your MSCOMMAND includes -I , you should enter here. If you re simulating a sample of 100 chromosomes from a panmictic population, you should simply enter 100 here. Entering the wrong value(s) is not likely to crash the program, but it will botch the population labels in STRUCTURE and SMARTPCA formatted output. Also, because

9 STRUCTURE and SMARTPCA data are output as diploid data it is absolutely necessary that the number of chromosomes in each population is divisible by TROUBLESHOOTING and BUGS This is a new program that does not include much exception handling. If you run into difficulties, you should first make sure that the values in params are properly specified. Try starting over with the backup file that you made (Section 1.4). Remember that some error messages may be complaints from MS itself. Always check that the MSCOMMAND follows proper MS syntax. If, after checking the params file, the program s behavior still baffles you, send an explanation of the problem and a copy of your params file to: haasl@wisc.edu