mPrime Help

  1. Introduction
  2. Tutorial
  3. Reference
  4. References and websites
  5. Installation
  6. Software licenses and copyrights

I. Introduction

The mPrime software package provides a front-end for primer3, a widely-used open source program (http://primer3.sourceforge.net) for choosing oligonucleotide primers for polymerase chain reaction (PCR). In addition, it uses Bowtie (http://bowtie-bio.sourceforge.net) to rapidly identify potential mispriming sites within a particular genome. For any given primer pair identified by primer3, all sites in the genome with up to a user-specified number of mismatches, as well as potential PCR products, are identified by Bowtie. The Tm for each priming (or mispriming) site is computed by mPrime using the nearest-neighbor method. This information should facilitate making better choices of primers for PCR, cloning, or DNA sequencing. Target sequences may be imported into the program from fasta files, extracted from compressed fasta files that, for example, include an entire chromosome sequence, or downloaded from an Ensembl DAS Reference Server.

mPrime was written in J (Version 8.01), an Array Programming Language developed by JSoftware, Inc., and runs on Windows, OSX, or Linux. Detailed installation instructions and system requirements are provided below.

II. Tutorial

This tutorial will work through a simple session for selecting PCR primers. Detailed descriptions of the menu and toolbar options as well as the four tabs in the program window are provided in the Reference section.

Start the program by choosing mPrime from the Start menu (Windows), double-clicking the mPrime icon in the program folder (Mac OSX), or typing "./mprime" in a terminal window after changing to the mPrime directory (Linux). The program window will be displayed as shown below.

mPrime initial window

Load sequence We want to select a primer pair for amplifying a specific target sequence, so we will select the PCR radiobutton in the Task group on the Pick tab. We want to amplify, for sequencing, the first exon of the Msh5 gene. We'll download that sequence from Ensembl. Press the Load button (or choose Open sequence from the Sequence menu) to obtain the dialog box at right.

Choose Retrieve from Ensembl so we can download the sequence from the Ensembl DAS server. Also select the Mouse radiobutton in the Species box. The exon sequence we want is on Chromosome 17 from 35,183,176-35,183,567 bp, so we'll download 1 kb of sequence beginning at 35183001 bp (fill in the Start, Length, and Chrom. edit boxes accordingly). We've also entered a file name in the Save as edit box to save the retrieved sequence to our computer. If we had left that edit box blank, a copy of the sequence would be temporarily saved to the temp directory of the mPrime folder. Press the OK button, and the sequence will be downloaded and you will go back to the main program window. Note that the file msh5-1.seq is also included in the mPrime installation directory.

We want to choose both forward and reverse primers, so the Left and Right checkboxes are selected. To include the exon in the product, we enter 170-570 in the Target bases edit box. The value for Product sizes must be changed from the default value of 100-300 to 400-600 (given that our target is 400 bp), or no primers will be reported. Alternatively, you could simply enter the target sequence and press the Auto button. In that case, mPrime will fill in the values for Included bases and Product sizes to allow a 50 base pair window around the target sequence. (Note that the Clear button will clear those three edit boxes.) The two checkboxes at the bottom of the Choose/Specify oligos box determine whether primer3 will report primers even if none match the selection criteria (Pick anyway) and whether each forward and reverse primer is unique (Pick unique). The default behavior (Pick unique selected) is that each primer is unique. If this box is not selected, each primer pair is unique, but some forward or reverse primers may appear in multiple pairs. We'll choose to pick unique primers. The edit box at the bottom of the form (Number to pick) is left at the default, so 5 pairs will be reported (if possible). We will leave all of the values in the General and Penalty tabs at their defaults (more on that in the Reference section). Finally, to run primer3 and choose our primers, select Primer > Run primer3 from the menu, press the primer3 button button on the toolbar, or enter ctrl-p from the keyboard. The results from primer3 will be shown in a new window, a portion of which is shown below:

mPrime window 2

primer3 output

The results shown in the window include a header that displays selected parameter values and the standard output from primer3 (with the format-output option). These results can be printed or saved as a text file by choosing the appropriate menu option or toolbar button. You can also annotate the output after pressing the Annotate button primer3 button or choosing Edit > Annotate. Following the information shown in the figure, the DNA sequence and positions of the target sequence and primers are shown. At the bottom of the edit window, data for the remaining primer pairs is provided (reproduced below).

ADDITIONAL OLIGOS
                    start  len      tm     gc%  any_th  3'_th hairpin seq

 1 LEFT PRIMER         92   20   59.68   60.00    8.19   0.00   41.75 CGGAGATAGGCACTCATGGG
   RIGHT PRIMER       630   20   60.11   55.00    0.00   0.00    0.00 GGGAAAGTGCTGCGAATTGG
   PRODUCT SIZE: 539, PAIR ANY_TH COMPL: 0.00, PAIR 3'_TH COMPL: 0.00

 2 LEFT PRIMER         93   20   59.31   60.00    8.19   0.00   41.75 GGAGATAGGCACTCATGGGG
   RIGHT PRIMER       676   20   59.75   60.00    0.00   0.00    0.00 GTTGGTCAGGGAGGTGGATC
   PRODUCT SIZE: 584, PAIR ANY_TH COMPL: 0.00, PAIR 3'_TH COMPL: 0.00

 3 LEFT PRIMER         39   20   60.82   60.00    0.00   0.00    0.00 CTCGGAAGGGCATGGATTGG
   RIGHT PRIMER       631   20   60.45   55.00    0.00   0.00    0.00 CGGGAAAGTGCTGCGAATTG
   PRODUCT SIZE: 593, PAIR ANY_TH COMPL: 0.00, PAIR 3'_TH COMPL: 0.00

 4 LEFT PRIMER         38   20   60.82   60.00    0.00   0.00   39.21 CCTCGGAAGGGCATGGATTG
   RIGHT PRIMER       629   20   60.73   55.00    5.36   5.36    0.00 GGAAAGTGCTGCGAATTGGC
   PRODUCT SIZE: 592, PAIR ANY_TH COMPL: 0.00, PAIR 3'_TH COMPL: 0.00

Statistics
       con   too   in    in  not          no    tm    tm   high  high  high        high     
       sid  many  tar  excl   ok   bad    GC   too   too any_th 3'_th hair-  poly   end     
      ered    Ns  get   reg  reg   GC% clamp   low  high  compl compl   pin     X  stab   ok
Left  1475     0    0     0    0    62     0   423   555      0     0   180     0     0  255
Right 4085     0    0     0    0   303     0   188  2798      0     0   146     0     0  650
Pair Stats:
considered 1097, unacceptable product size 1090, 
  primer in pair overlaps a primer in a better pair 209, ok 7
libprimer3 release 2.3.5

mPrime window 2 We next want to check our primers for potential binding to off-target sites in the genome. We will use Bowtie, developed at the University of Maryland Center for Bioinformatics and Computational Biology by Langmead et al. This program was designed to rapidly align short reads produced by next-gen sequencers to a reference genome, but is also ideal for our purpose. From the main window, choose Primer > Check mispriming from the menu or press the align icon button on the toolbar to obtain the dialog box at right. Alternatively, press ctrl-m when either the main window or a primer3 output window has the focus.

Bowtie uses Burrows-Wheeler transformed indexes to represent the genome. We've made index files corresponding to each mouse chromosome and placed them in the e:\dna-data\mus-chr-indexes\ directory. To use that set of indexes, we select the Local only radiobutton. We the chose the directory using the Browse button and the location of one of the files is indicated in the Index files edit box. Because we want to search all of the chromosomes for matches to the primers, we've checked the Search all indexes in directory box. Alternatively, we could run the Bowtie program on a remote server, by selecting the Remote only radiobutton. An advantage of this approach is that we can install mPrime on any computer and depend on the server to store the index files and it may also run the alignment more quickly.

The desired primer pair (of the five provided by primer3) is selected in the Choose primer pair listbox. Alternatively, you could select the Test all pairs checkbox and all of the primer pairs will be analyzed for mispriming. The radiobuttons below (Return hits per index) allow us to specify whether the best 2 or 3 hits per chromosome are returned, or all sites matching the criteria are provided by Bowtie. Generally, leave the default All selected. We can also specify how many mismatches (in the range 0-3) are allowed between the potential mispriming site and our primer in the Max mismatches edit box. Bowtie will also screen the genome for potential primer pair binding sites that could give rise to an unintended PCR product if we leave the Check pairs box selected. We indicate the Max distance between the forward and reverse oligos in the adjacent edit box. Finally, we can choose to report all of the potential binding sites, or just the best 10 (by Tm) using the Top 10 only checkbox. Pressing the OK button will run Bowtie and show the result in a new window (similar to the primer3 results window. The information can then be annotated, printed or saved to a text file as before. The results of our Bowtie run are reproduced below.

The results first show the pair fragments (where the primers are in the correct orientation and within 2 kb, as we specified). For our primer pair, we see only one set of matches at the correct position. Next, the top 10 priming sites for the forward and reverse primers are listed, with their chromosomal location, strand, sequence (mismatches are indicated by lower case), number of mismatches, and the Tm of the oligo for that site. Note that only a single perfect match is found for each primer (at the desired site) and that the next best Tms are 8.5° and 5.0° lower than the perfect match site. If our chosen primer pair had the potential to yield multiple products, or some of the mismatched sites had a Tm too close to our perfect match site, we could repeat the analysis with another primer pair. Note that the Tms reported by mPrime may differ by a small amount from those indicated by primer3 because a slightly different algorithm is used by mPrime.

Mispriming analysis
Source is local
Local files at e:\ensembl\ensembl-67\mus\mus-chr-ncbim37\
Bowtie reporting all for all chromosomes
Mispairs allowed = 3
Max pair distance = 2000
Tm parameters (mM Na, mM Mg, uM dNTP, uM DNA) = 50 1.5 600 0.05

Primer pair 0- GGAAGGGCATGGATTGGTCA;GAAAAGGCGGGAAAGTGCTG
Forward primer - 178 sites
Reverse primer - 167 sites

Pair fragments
Chr F-Pos    Sequence             F-Tm R-Pos    Sequence             R-Tm
17  35183042 GGAAGGGCATGGATTGGTCA 59.8 35183619 CAGCACTTTCCCGCCTTTTC 59.4

Top 10 priming sites

Forward primer: GGAAGGGCATGGATTGGTCA
Chr Position  Strand Sequence             MM Tm
17  35183042  +      GGAAGGGCATGGATTGGTCA 0  59.8
9   14183167  +      cGAAGGGCATGGcTTGcTCA 3  51.3
6   127610579 +      GGAAGGGCcTGGcTTGcTCA 3  51.1
17  85677099  +      ctAAGtGCATGGATTGGTCA 3  50.6
1   175256110 +      GGAAGGGCcTGGATgGGTCA 2  50.4
4   124179890 -      gGAaCAATCCAgGCCCTTCC 3  50.4
13  28693845  -      TGACCAATCCATGtCCTTgt 3  49.7
6   56399549  -      TGACCAATCCAaGCaCTTCC 2  49.5
11  96061777  +      GGAAGGGCAcGGAgTGGTCc 3  49.3
2   64442900  +      GaAAGaGCATGGATTGGTCA 2  49

Reverse primer: GAAAAGGCGGGAAAGTGCTG
Chr Position  Strand Sequence             MM Tm
17  35183619  -      CAGCACTTTCCCGCCTTTTC 0  59.4
4   75608091  -      CAGCACTTTCCtGCCTTTTC 1  54.4
X   128546279 -      aAGCACTTTCCCGgCTTTTa 3  52
X   88734563  -      CAGCACTTgCCCGaCTTTTt 3  50.1
2   11516903  +      GcAAAGcCGGGAcAGTGCTG 3  49.1
5   70044557  -      CAGCACTaTCCCGCCTaTTg 3  49.1
14  13995617  +      tAAAAGcCGGGAAAGaGCTG 3  49
16  87461943  +      cAgAAGcCGGGAAAGTGCTG 3  48.9
19  27210419  -      CAGCACTcTCCtGCCTTTTC 2  48.3
15  95194742  +      cAtAtGGCGGGAAAGTGCTG 3  48.1

Run time = 41.241 sec.

III. Reference

Detailed information for the four tabs in the mPrime window and for the menu choices is provided below. Further information on the default choices within the tabs can be found in the primer3 documentation.

Pick tab

After loading the sequence file, the ID is taken from the fasta sequence name (modified if needed so that it will be an allowable filename) and the length of the sequence is placed in the Seq length edit box. Four possible primer3 tasks can be chosen in the Task box. PCR will identify the usual forward and reverse primers for sequence amplification, while Detection will also identify an internal primer that can be used for hybridization to the PCR product. Choosing either of these options will initially select the Left, Internal, and Right checkboxes below, as appropriate. The Sequencing option will cause primer3 to select oligos suitable for sequencing through the target region. The Cloning option will choose primers to amplify a specific sequence for cloning into an appropriate vector. To use that option, designate the positions of the first and last bases of the desired sequence in the Include bases edit box, which will be the 5' ends of the forward and reverse primers, respectively. Because the ends are fixed, the Tm of the oligo will be controlled by the length of the primer, rather than its position. Hence, Pick anyway is selected by default because you may be forced to use less than ideal primer pairs. This option will report primer pairs even if none of the possible primers meet the criteria detailed in the General tab.

Pick tab

The Left,Internal, and Right checkboxes control whether primer3 will identify the corresponding primers. You can put a specific sequence in one of the adjacent edit boxes to insure that it is used for that primer. For example, putting a sequence in the Left edit box and leaving the Right edit box empty will choose primer pairs with the Left sequence as the forward primer and various reverse primers. Pick unique controls whether primer3 reports unique primer pairs (unchecked) or unique primers (checked, the default). In the former case, each of the reported pairs is unique, but some pairs may share identical forward or reverse primers. When selected, this option will insure that no two primers cover an identical sequence.

If a range of Target bases is specified, primers will be chosen such that the product will include that region. For example, if 300-500 is placed within that edit box, the forward primer will be chosen proximal, and the reverse primer distal, to that interval, subject to the remaining constraints within the tab. For both the PCR and Detection tasks, the Auto button will fill in the Include bases and Product sizes boxes such that the primers are chosen within 50 bases proximal and distal to the target. The Include bases edit box is useful to restrict the focus of primer3 to a subinterval of the loaded sequence. This may be helpful if you've loaded a 10 kb sequence, but want primers and products to fall within a smaller interval. In addition, the value in this edit box has a specialized meaning if the Cloning task is selected, as discussed above. The sequence that is shown in the primer3 results window will be limited to the Include bases interval, along with 60-120 bp proximal and distal to that interval. To insure that a particular subsequence does not overlap any of the chosen primers, indicate that region in the Exclude bases edit box; this option may be useful if your sequence contains a repetitive element. In order to obtain a PCR product that is in-frame, specify the position of the ATG in the Start edit box. The allowable range(s) of product sizes is entered in the Product sizes edit box. Multiple size ranges may be entered: primer3 will generally choose primers that satisfy the other criteria to yield products in the smallest possible size range. Note that mPrime does only limited checking for consistency among the values entered in these five edit boxes. For example, if the range indicated in Target bases is 400 bp, but 100-300 is entered in the Product sizes edit box, you will get an error message telling you that the chosen Product sizes are too small. In other cases, primer3 may run but will return a result of NO PRIMERS FOUND.

The final edit box on the Pick tab is Number to pick. The default value of 5 will instruct primer3 to return 5 primer pairs, if possible.

General tab

The General tab allows you to specify values for many of the parameters used by primer3 to choose primers. With a few exceptions, discussed below, the values shown in these edit boxes reflect the default values for primer3. The function of these parameters should be obvious in most cases. For example the first three rows of edit boxes allow you to specify the Minimum, Optimum, and Maximum for primer length, Tm, and GC content. Further details on these and the other parameters may be found in the primer3 documentation.

General tab

The bottom left three rows of edit boxes refer to the reaction conditions for PCR and the method used to compute the primer Tm. The Monovalent and Divalent edit boxes specify the mM concentrations of monovalent and divalent cations (e.g., Mg++). The Oligo concentration refers to the nM concentration of the primers. The default value of 50 is intended to reflect the concentration of "annealing oligos" and is less than the starting concentration in the PCR mix. This value has a significant effect on the estimated Tm, which in turn will drive the choice of oligos. As noted in the primer3 documentation, the appropriate value for PCR (as opposed to the melting of paired oligonucleotides in solution) should be "empirically determined". In any event, the default value generally yields results that work in practice. The value in the Tm formula box can be 0 (the default in older versions of primer3) or 1. Using the older method for estimating Tm (0) will often give results that differ from the true Tm by several degrees. Using the nearest neighbor method (a value of 1) will give more accurate results in primer3 and the same method is used by mPrime to estimate Tm in the analysis of mispairing. The value for Salt formula can be 0, 1, or 2 to force primer3 to correct the Tm for the concentrations of monovalent and divalent cations. A value of 0 will select the less accurate method previously used by primer3, while 1 or 2 will utilize the methods of SantaLucia or Owczarzy, respectively. Leave both of these formula values at the default of 1 or you will see large differences in the Tms computed by primer3 and mPrime.

Penalty tab

The Penalty tab allows you to specify values for the various penalty functions used by primer3 to choose optimal primers. The values shown on this tab are the default values for primer3 and you should generally not need to change them. See the primer3 documentation for further details.

Penalty tab

Hyb Oligo tab

This tab includes edit boxes for the various parameters and penalty values for the internal oligo. These values may need to be modified if you choose the Detection task.

HybOligo tab

File menu

The Load parameters (folder open button toolbar button), Save parameters (folder save button), and Reset defaults (reset button) choices refer to the primer3 parameters set in the various tabs. If you routinely want to choose primers with a Tm range that is slightly higher or lower than the original primer3 default values, you can enter all of the desired values in the appropriate edit boxes on the tabs. When you have your desired set of parameter values, you can save them to a file using the Save parameters menu choice (default file extension is .mprime). Then you can reload these values in a later session by using the Load parameters menu choice. The Reset defaults menu choice puts all of the primer3 parameters back to their default values.

Preferences dialog The fonts used by mPrime as well as the URLs for the Ensembl DAS reference servers can be set by choosing Preferences (preferences button) from the File menu. This action will open the preferences dialog:

The fonts for all of the mPrime windows and dialogs can be selected by pressing the Change button in the Form font line. Select the desired font and adjust the size from the font dialog box that comes up. Note that you will likely need to use a somewhat smaller font than usual because of the high density of control elements in the mPrime windows. A monospaced font should be chosen as the Report font. It will be used to display the output of the primer3 and Bowtie programs. The Margin and Orientation entries control printing of that output.

The three edit boxes in the Ensembl URLs box contain the URLs for the mouse, human, and rat Ensemble DAS reference servers. These URLs are accurate as of 6/2012 but you may need to change them in the future. The correct URLs can be obtained from Ensembl (http://www.ensembl.org/das/dsn). The final edit box contains the URL for a remote Bowtie server. After installing mPrime, you will need to type the appropriate value into this edit box. If you are inside the network at the McArdle Laboratory for Cancer Research, that value is http://genome.oncology.wisc.edu, as shown in the dialog. Instructions for setting up your own Bowtie server are provided on the mPrime website.

The Exit choice in the File menu quits the program.

Sequence menu

Load sequence Target sequences are loaded for use in mPrime by choosing the Open sequence menu option, or alternatively by pressing the Load button in the main program window or the new folder button toolbar button. You will then obtain the dialog box shown at right.

Three alternative methods may be used to load the desired sequence, as shown in the Choose method box. Open fasta file loads the sequence from a fasta file. The file must contain a single sequence or you will see an error message. Extract from fasta file allows you to import a sub-sequence from that given in the fasta file. This option is useful if you have a local copy, for example, of a whole genome with one fasta file per chromosome. You can choose to store the extracted sequence in a new file by entering the file name in the Save as edit box or using the Browse button to open up a file dialog. Both of the fasta options will read compressed (.gz) files, allowing you to store the whole mouse genome in approximately 1.4 Gb.

The Retrieve from Ensembl option makes it possible to download a specific sequence from one of the Ensembl DAS Reference Servers (see http://www.ensembl.org/info/data/ensembl_das.html). The URLs for the servers can be changed (as the genome build is updated) from the Preferences dialog discussed above. Choose the appropriate species from the radiobuttons at the lower left of the dialog, then enter the starting nucleotide, number of base pairs to download, and chromosome in the Start, Length, and Chrom. edit boxes, respectively. This option should be used to download moderate amounts of sequence (less than 100 kb in length). If you routinely need longer sequences, you should consider downloading the compressed chromosome files from Ensembl (see http://www.ensembl.org/info/data/ftp/index.html).

Pressing the OK button will retrieve the desired sequence and load it for use in mPrime.

After you have loaded a sequence in mPrime, you can view it by choosing the View sequence option in the Sequence menu or pressing the view sequence button toolbar button.

The Build index choice from the Sequence menu (or the database button toolbar button) allows you to build a new Bowtie index from a fasta sequence file. This option is intended to make it easy to build an index for a relatively small sequence file (less than a few megabases), such as that for a virus or BAC. Building a whole genome index requires a 64-bit operating system, at least 8 GB of memory, and several hours. You should probably consult the Bowtie manual for instructions and not attempt to build a whole genome index from within mPrime. Note that pre-built indexes for the cDNAs, chromosomes, and whole genomes of mice, rats, and humans are available from the mPrime website.

build index dialog

Use the upper Browse button to choose the fasta source file. Note that this fasta file can contain multiple sequences, which will all be included in the index. In the dialog above, we've chosen a fasta file containing the Epstein-Barr virus genome. Use the lower Browse button to choose the directory to store the Bowtie index. Finally, enter a name for the index in the Index name edit box. Press the OK button and the bowtie-build program will be run to build the new index. The results of the run will be displayed in a View results window. Bowtie will generate six files in the target directory; in this case, the files are ebv.1.ebwt, ebv.2.ebwt, ebv.3.ebwt, ebv.4.ebwt, ebv.rev.1.ebwt, and ebv.rev.2.ebwt. If you wanted to match primer pairs against both the ebv and human genomes, you could copy these six files to the directory containing all of the human chromosome indexes and specify that directory and the Local only source in the Check mispriming dialog. Alternatively, you could specify Remote+Local as the source, Human as the Remote species, and the EBV index directory under Local files.

Primer menu

To invoke primer3 and identify primers, select Run primer3 from the Primer menu or press the primer3 button toolbar button (or enter ctrl-m from the keyboard). mPrime is designed to use version 2 of primer3 (currently primer3-2.3.5), which is available from (http://primer3.sourceforge.net/). Documentation for this version of primer3 is included in the mPrime package. mPrime captures the standard output of primer3 and displays it in a new window with a bit of editing. The top of the window has a summary of the parameters used for primer3, and in particular changes from the primer3 default settings. The primer3 output follows with the only modification being that most of the sequence outside of the Include bases interval (if one is set in the Pick tab) is removed. This editing will provide a more concise output, particularly if a large portion of the loaded sequence is not included.

The primer3 output will contain information on only the number of pairs specified in the Number to pick option of the Pick tab. You can view all of the acceptable forward and reverse primers by choosing Primer > Show all primers from the menu or pressing the view primers button toolbar button. The lists of primers will be displayed in a new View results window.

Modify defaults dialog mPrime will allow you to set nearly all of the options used by primer3 (there are 137 of them), but some have been omitted to simplify the program interface. You can also change those settings from their defaults by choosing Modify other defaults from the Primer menu. You will then see the dialog box shown at right. Enter the desired PARAMETER=value information in the edit box, with one per line and no blank lines, and press OK. For example, to change the defaults used to choose sequencing primers you could enter:

PRIMER_SEQUENCING_INTERVAL=200
PRIMER_SEQUENCING_LEAD=100
PRIMER_SEQUENCING_INTERVAL=400

These values differ from the defaults of 250, 50, and 500, respectively. The modified defaults entered in this dialog are applied after all of the settings in the mPrime tabs, so you could change those as well. A complete list of the primer3 parameters and their default settings is provided in the primer3 documentation. Be cautious in using this option!

Check mispriming dialog After identifying primer pairs with primer3, you can identify potential, off-target priming sites by choosing Check mispriming from the Primer menu, or pressing the align button toolbar button. You can also enter ctrl-m from the main window or a primer output window. You will then see the dialog box at right (also shown above in the tutorial). The Bowtie program, which is available from (http://bowtie-bio.sourceforge.net) and identified by the authors as "an ultrafast memory-efficient short read aligner", was originally designed to align the short reads obtained from next-gen sequencers to whole genome reference sequences. Typically, a set of index files that encompasses the whole genome is used for that purpose, but for our needs to align pcr primers, it's more efficient to use multiple index files with one set for each chromosome. Whole genome index files for a variety of species are available from the Bowtie website. Indexes for the individual chromosomes, whole genomes, and cDNAs for the mouse, human and rat genomes are available from the mPrime website or you can build your own, as described in the Bowtie manual.

The Browse button is used to specify the location of one of the necessary Index files. If you want to search all of the indexes in that directory (i.e., the indexes for the other chromosomes for that genome), select the Search all indexes in directory checkbox.

The primer pair to be tested is chosen from the Choose primer pair combobox. You can conveniently test all of the primer pairs provided by primer3 by selecting the Test all pairs checkbox.

You can limit the number of mispriming sites returned for each chromosome using the Return hits per index set of radiobuttons, but it's generally best to leave the default All choice selected. The Bowtie program will find matching sequences with up to 3 mismatches. You can specify how many mismatches are allowed in the Max mismatches edit box. Leaving that value at the default of 3 is generally a good idea, because sites with 3 mismatches at the 5' end of the primer will often anneal well. After Bowtie is run, mPrime estimates the Tm for each mismatch site. Checking the Top 10 only box will limit the output to the 10 sites for each primer with the highest Tm (including the intended priming site). Bowtie also has a paired-reads mode that is useful for finding potential mispriming PCR products. To do so, select the Check pairs box and enter the Max distance between the primers (default 2000 bp) in the edit box. After pressing the OK button, Bowtie is run and you will see a progress dialog until the Bowtie analysis is complete. This analysis should complete fairly quickly. On a standard desktop running Windows 7, the whole genome scan shown in the tutorial took about 40 seconds. Faster results, often less than 10 seconds, can be obtained for subsequent runs on machines with 4 Gb (or more) of memory because the indexes remain cached in memory.

The Bowtie index files consume a fair bit of disk space (2-3 Gb per species) and the mispriming analysis may take 1-2 minutes on older computers with 2 Gb (or less) of memory. To make it easier to run mPrime on multiple desktops or laptops within a lab, it's possible to shift all of the Bowtie analyses to a lab or departmental server running a php-enabled web server. mPrime will use the server if you choose the Remote only radiobutton and have provided the URL for the server in the Preferences dialog. The remote version will check the entire genome (indicated by the Species radiobuttons) and runs with the All hits, Top 10 only, and Check pairs options enabled. You can still specify the Max mismatches and Max distance options. If you want to use the server for aligning to genomic DNA, but also check against an additional set of indexes (e.g., a viral genome), select the Remote+Local option. Servers with enough memory to maintain the indexes in cache will return results in 2-3 seconds. Directions for setting up a Bowtie server may be found on the mPrime website.

A sample of the output from the Bowtie analysis is discussed above in the Tutorial.

Window menu

An extended session with mPrime can result in a large number of View results windows. Choose Cascade from Window menu to organize them neatly in the upper left of your screen, or Minimize to hide all of the mPrime windows.

Help menu

Choosing Help from the Help menu, or pressing the help button toolbar button should open a copy of this manual in your browser. You can check for updates to mPrime by selecting Check for updates. About will display the dialog at right. The version number and date for the mPrime program is displayed in the upper right edit window. The mouse on the left is one of our favorites.

About dialog

IV. References and websites

primer3

Rozen S, Skaletsky H (2000) Primer3 on the WWW for general users and for biologist programmers. In: Krawetz S, Misener S (eds) Bioinformatics Methods and Protocols: Methods in Molecular Biology. Humana Press, Totowa, NJ, pp 365-386.

Koressaar T, Remm M (2007) Enhancements and modifications of primer design program Primer3. Bioinformatics, 23: 1289-1291.

Website: http://primer3.sourceforge.net

Bowtie

Langmead B, Trapnell C, Pop M, Salzberg SL. (2009) Ultrafast and memory-efficient alignment of short DNA sequences to the human genome. Genome Biology, 10:R25.

Website: http://bowtie-bio.sourceforge.net

Primer Tm estimation

SantaLucia, J, Hicks, D (2004) The thermodynamics of DNA structural motifs. Annu. Rev. Biophys. Biomol. Struct. 33: 4015-4040.

SantaLucia, J. (1998) A unified view of polymer, dumbbell, and oligonucleotide DNA nearest-neighbor thermodynamics. Proc. Natl. Acad. Sci. USA 95: 1460-1465.

SantaLucia, J, Allawi, H. T., Seneviratne, P. A. (1996) Improved nearest-neighbor parameters for predicting DNA duplex stability. Biochemistry, 35: 3555-3562.

Owczarzy, R., Moreira, B. G., You, Y., Behlke, M. A., Walder, J. A. (2008) Predicting stability of DNA duplexes in solutions containing magnesium and monovalent cations. Biochemistry, 47: 5336-5353.

V. Installation

mPrime will run on Windows (XP or later), Linux (Ubuntu 12.04 and CentOS 5 have been tested), and Mac OSX (Intel only). Note that both 32-bit and 64-bit versions of the program are available for each platform. The Windows setup program will install the correct version for your computer. For OSX or Linux, download the 32-bit or 64-bit version as appropriate. The main advantage of the 64-bit version is that whole genome indexes may be searched (locally) on computers with 4GB or more of memory. With the 32-bit version (or on computers with less memory), you must do local searches using the set of chromosome indexes. If you're not sure which version to use, download the 32-bit version (and don't try to search whole genome indexes locally). Platform specific instructions are provided below.

For Windows, run the installer and start the program using the shortcut on your desktop or in the Start menu. The OSX version is distributed as a disk image. Open the disk image, copy the mPrime folder to your home directory and double-click the mPrime icon within that folder. On Linux, untar the mprime3-arch.tar.gz file within your home directory and start the program from a terminal window by changing to the mprime3 directory and entering ./mprime.

Several other programs are also required for mPrime to function; these programs are either part of the mPrime installation package or are routinely part of the operating system installation. These other software requirements include:

Qt toolkit: The user interface uses the Qt toolkit. For Windows and OSX, the appropriate shared libraries are installed in the Qt folder within the installation directory. Because of the way OSX handles shared libraries, you will have a conflict if you have already installed Qt to the /Library/Frameworks directory (not a common occurrence outside of the developer community). To test for that conflict, open a terminal window, change directories to the mPrime 3.0/bin folder, and enter ./mprime. If you have duplicate libraries, you will see a string of error messages indicating that fact in the terminal window. Simply rename the Qt folder in the installation directory to Qt.0 to resolve the problem.

For Linux, you will need to insure that the Qt4 libraries are installed on your system. Try running the mPrime program. If you get an error indicating that the Qt libraries are not installed, you will need to install libqt4-core and libqt4-gui.

primer3: The primer3_core executable must be present in the bin subdirectory of the mPrime folder. The primer3_config folder in the bin directory contains the thermodynamic parameters required by primer3 for computing Tm values. Only version 2 of primer3 is supported by mPrime. The most recent version of the software is primer3-2.3.5, and is available from the primer3 website (http://primer3.sourceforge.net/releases.php). Note that you may need to click on the link to the "SourceForge Downloads Page" to get access to version 2. This version is currently available only as source code, so to update to a newer version of the primer3 program, you may need to compile it yourself. The compiled primer3 executable from the version dated 5/3/2012 is included in the mPrime package.

Bowtie: The Bowtie software package for various platforms is available from http://bowtie-bio.sourceforge.net. The mPrime package includes the required bowtie and bowtie-build executables from version 1.0.0, which is installed in the bin subdirectory of the mPrime folder. You will also need a set of Bowtie index files for your desired genome. A set of files for the mouse, human, and rat genomes, with each chromosome in a separate index, is available from the mPrime website. Whole genome and cDNA indexes for these three species are also available from the mPrime website, or you could make your own following directions in the Bowtie manual.

curl: The curl program is required to download sequence data from the Ensembl DAS Reference Servers. It is installed in the bin subdirectory of the mPrime folder on Windows, but is generally already present on OSX systems. On Linux the wget program is used instead. To check for the presence of wget (or curl) on these systems, open a terminal window and enter "wget" (or "curl"); if you get an error message indicating that the program is not found, install it to your system.

zlib: The zlib library is required to allow reading of compressed sequence files. If this library is not present, you will get an error the first time you attempt to load a fasta file (compressed or not). The zlib1.dll file (version 1.2.7) is installed in the bin subdirectory of the mPrime package on Windows. This library is generally present on OSX or Linux systems. For OSX, make sure that the file libz.dylib is present in the /usr/lib directory. On Linux, insure that libz.so.1 is in /usr/lib. On some systems you may need to make a symbolic link with the above name to the installed version of libz.

VI. Software licenses and copyrights

mPrime

The mPrime package (the software and its documentation) are copyrighted (2013) by Norman Drinkwater. Use of this software is subject to the Artistic License 2.0, a copy of which may be found in the help/licenses subdirectory of the software package. Among the other provisions of this license, note that: The package is provided by the copyright holder and contributors "as is" and without any express or implied warranties. The implied warranties of merchantability, fitness for a particular purpose, or non-infringement are disclaimed to the extent permitted by your local law. Unless required by law, no copyright holder or contributor will be liable for any direct, indirect, incidental, or consequential damages arising in any way out of the use of the package, even if advised of the possibility of such damage.

J

mPrime runs under the J software environment, which is copyrighted by Jsoftware, Inc. (1994-2013). The J software distribution may be obtained from http://www.jsoftware.com; details of the J software license may be found at that site.

Qt toolkit

The mPrime user interface is written with the Qt toolkit (copyright 2012, Digia Plc), which is subject to the GNU Lesser General Public License (LGPL, version 2.1). For further information, see http://qt-project.org/doc/qt-4.8/opensourceedition.html.

primer3

mPrime uses (i.e. forks) the primer3_core executable to choose oligonucleotide primers. The primer3 software package is available from http://primer3.sourceforge.net. This software is copyrighted (1996-2012) by the Whitehead Institute for Biomedical Research, Steve Rozen, Andreas Untergasser and Helen Skaletsky. It is licensed under GPLv2, a copy of which may be found in the help/licenses subdirectory of the mPrime package.

Bowtie

mPrime uses (i.e. forks) the bowtie executable to align primers to genomic sequence. Bowtie was written by Ben Langmead and Cole Trapnell and is available from http://bowtie-bio.sourceforge.net. It is licensed under the Artistic License 2.0. A copy of this license and the program authorship details (bowtie-authors.txt) may be found in the help/licenses subdirectory of the mPrime package.

zlib

mPrime requires the zlib compression library, copyrighted (1995-2010) by Jean-loup Gailly and Mark Adler. The library is included in the mPrime package for Windows, but is generally already installed in OSX and Linux systems. The license for the zlib library may be found at http://www.zlib.net/zlib_license.html.

curl

mPrime for Windows includes the curl executable, which may be obtained from http://curl.haxx.se. This software is licensed under an MIT/X derivative.

Fugue icons

Some of the toolbar icons are from the Fugue icon collection, created by Yusuke Kamiyamane and licensed under a Creative Commons Attribution 3.0 License. The collection may be obtained from http://p.yusukekamiyamane.com/.