primer3 release 2.3.7 - manual

# PRIMER3 RELEASE 2.3.7 MANUAL

## CONTENTS

1. COPYRIGHT AND LICENSE
2. INTRODUCTION
3. CITING PRIMER3
4. FAIR USE OF PRIMER3
5. CHANGES FROM VERSION 2.2.3
6. INSTALLATION INSTRUCTIONS - UNIX/LINUX
7. INSTALLATION INSTRUCTIONS - Mac OSX
8. INSTALLATION INSTRUCTIONS - WINDOWS
9. BUILDING A Mac OSX UNIVERSAL BINARY
10. SYSTEM REQUIREMENTS
11. INVOKING primer3_core
12. COMMAND LINE ARGUMENTS
13. INPUT AND OUTPUT CONVENTIONS
14. AN EXAMPLE
15. HOW TO MIGRATE TAGS TO IO VERSION 4
16. "SEQUENCE" INPUT TAGS
17. "GLOBAL" INPUT TAGS
18. "PROGRAM" INPUT TAGS
19. HOW PRIMER3 CALCULATES THE PENALTY VALUE
20. PRIMER3 SETTINGS FILE FORMAT
21. OUTPUT TAGS
22. EXAMPLE OUTPUT
23. ADVICE FOR PICKING PRIMERS
24. CAUTIONS
25. WHAT TO DO IF PRIMER3 CANNOT FIND ANY PRIMERS?
26. DIFFERENCES FROM EARLIER VERSIONS
27. EXIT STATUS CODES
28. PRIMER3 WWW INTERFACES
29. ACKNOWLEDGMENTS

## 1. COPYRIGHT AND LICENSE

    Copyright (c) 1996,1997,1998,1999,2000,2001,2004,2006,2007,2008,2009,2010
                  2011,2012,2013,2016
    Whitehead Institute for Biomedical Research, Steve Rozen
    (http://purl.com/STEVEROZEN/), Andreas Untergasser and Helen Skaletsky. All rights
    reserved.

        This file is part of the primer3 suite and libraries.

        The primer3 suite and libraries are free software;
        you can redistribute them and/or modify them under the terms
        of the GNU General Public License as published by the Free
        Software Foundation; either version 2 of the License, or (at
        your option) any later version.

        This software is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
        GNU General Public License for more details.

        You should have received a copy of the GNU General Public License
        along with this software (file gpl-2.0.txt in the source
        distribution); if not, write to the Free Software
        Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    OWNERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

## 2. INTRODUCTION

Primer3 picks primers for PCR reactions, considering as criteria:
o oligonucleotide melting temperature, size, GC content, and primer-dimer possibilities,
o PCR product size,
o positional constraints within the source (template) sequence, and
o possibilities for ectopic priming (amplifying the wrong sequence)
o many other constraints.
All of these criteria are user-specifiable as constraints, and some are specifiable as terms in an objective function that characterizes an optimal primer pair.

## 3. CITING PRIMER3

We request but do not require that use of this software be cited in publications as
Untergasser A, Cutcutache I, Koressaar T, Ye J, Faircloth BC, Remm M and Rozen SG.
Primer3--new capabilities and interfaces.
Nucleic Acids Res. 2012 Aug 1;40(15):e115.
The paper is available at http://www.ncbi.nlm.nih.gov/pmc/articles/PMC3424584/
Source code available at http://sourceforge.net/projects/primer3/.

## 4. FAIR USE OF PRIMER3

The development of primer3 is promoted by a small group of enthusiastic scientists mainly in their free time.They do not gain any financial profit with primer3.
There are two groups of primer3 users: end users, who run primer3 to pick their primers and programmers, who use primer3 in their scripts or software packages. We encourage both to use primer3.
If you are an end user, we request but do not require that use of this software be cited in publications as listed above under CITING PRIMER3.
If you are a programmer, you will see that primer3 is now distributed under the GNU General Public License, version 2 or (at your option) any later version of the License (GPL2). As we understand it, if you include parts of the primer3 source code in your source code or link to primer3 binary libraries in your executable, you have to release your software also under GPL2. If you only call primer3 from your software and interpret its output, you can use any license you want for your software. If you modify primer3 and then release your modified software, you have to release your modifications in source code under GPL2 as well.
We chose GPL2 because we wanted primer3 to evolve and for the improvements to find their way back into the main distribution. If you are programming a new web interface which runs primer3, please include in the about page of the tool the sentence "<your software name> uses primer3 version ...". Please consider releasing your software under GPL2 as well, especially if you do not want to maintain it in the future.
There is no need to ask us for permission to include primer3 in your tools.

## 5. CHANGES FROM VERSION 2.2.3

1. The tag PRIMER_THERMODYNAMIC_ALIGNMENT was replaced by two new tags:
- PRIMER_THERMODYNAMIC_OLIGO_ALIGNMENT which governs hairpin and oligo-oligo interactions. Therefore, whenever it is set to 1 (the default) thermodynamic alignments will be used for oligo-oligo interactions and hairpins.
- PRIMER_THERMODYNAMIC_TEMPLATE_ALIGNMENT which governs the oligo-template interactions and, when set to 1 (default is 0), will cause primer3 to use the thermodynamic alignment against templates.
The reason for this change is to provide the option of using the old alignment for oligo-template interactions when the thermodynamic alignment is too slow or the template is too long (there is a hard limit THAL_MAX_SEQ=10k on the length of sequences involved in thermodynamic alignments).
2. We changed the following default values:
2.1. Changing default oligo temperature calculations
PRIMER_TM_FORMULA=1 (was 0)
PRIMER_SALT_CORRECTIONS=1 (was 0)
2.2. Making thermodynamic secondary structure calculations for oligos the default:
PRIMER_THERMODYNAMIC_OLIGO_ALIGNMENT=1 (was 0)
2.3. The following need reasonable values to support the changes in 2.1 and 2.2 above:
PRIMER_SALT_DIVALENT=1.5 (was 0.0)
PRIMER_DNTP_CONC=0.6 (was 0.0)
2.4. To make old defaults easily accessible, we added a command line argument, --default_version=1, which directs primer3_core to use the old defaults. --default_version=2 directs primer3_core to use the new defaults. The default is --default_version=2.
2.5. IMPORTANT: because PRIMER_THERMODYNAMIC_OLIGO_ALIGNMENT=1, PRIMER_THERMODYNAMIC_PARAMETERS_PATH must point to the right location. This tag specifies the path to the directory that contains all the parameter files used by the thermodynamic approach. In Linux, there are two *default* locations that are tested if this tag is not defined: ./primer3_config/ and /opt/primer3_config/. For Windows, there is only one default location: .\primer3_config\. If the the parameter files are not in one these locations, be sure to set PRIMER_THERMODYNAMIC_PARAMETERS_PATH.
2.6. Changed default for
PRIMER_LIB_AMBIGUITY_CODES_CONSENSUS=0 (was 1)
(0 is almost always the the behavior one wants.)
2.7. To get the behavior of -default_version=1 when -default_version=2 set the following:
PRIMER_TM_FORMULA=0
PRIMER_SALT_CORRECTIONS=0
PRIMER_THERMODYNAMIC_OLIGO_ALIGNMENT=0
PRIMER_THERMODYNAMIC_TEMPLATE_ALIGNMENT=0
PRIMER_SALT_DIVALENT=0.0
PRIMER_DNTP_CONC=0.0
PRIMER_LIB_AMBIGUITY_CODES_CONSENSUS=1
2.8. To get the behavior of -default_version=2 when -default_version=1 set the following:
PRIMER_TM_FORMULA=1
PRIMER_SALT_CORRECTIONS=1
PRIMER_THERMODYNAMIC_OLIGO_ALIGNMENT=1
PRIMER_THERMODYNAMIC_TEMPLATE_ALIGNMENT=0
PRIMER_SALT_DIVALENT=1.5
PRIMER_DNTP_CONC=0.6
PRIMER_LIB_AMBIGUITY_CODES_CONSENSUS=0
3. We changed the NULL value for SEQUENCE_FORCE_{LEFT,RIGHT}_START_END to -1000000, and made it an error to select PRIMER_FIRST_BASE_INDEX <= this value. This is to correct an error when SEQUENCE_FORCE_{LEFT,RIGHT}_START_END was -1 (value previously used to indicate a NULL) but PRIMER_FIRST_BASE_INDEX was < 0, which caused the intended NULL value (-1) to be treated as a constraint on primer location (a constraint that was not possible to satisfy).
4. We changed the PRIMER_TASK called 'pick_detection_primers' to 'generic' while retaining 'pick_detection_primers' as an alias for backward compatibility.
5. The code now uses 'end' alignments when assessing template mispriming using thermodynamic alignments. This is consistent with the approach taken with the previous alignment algorithm and with checking for mispriming against repeat libraries.
6. We removed PRIMER_PAIR_MAX_HAIRPIN_TH (which was ignored previously).
7. Primer3 now requires the user to set SEQUENCE_TARGET, not SEQUENCE_INCLUDED_REGION when PRIMER_TASK=pick_discriminative_primers
8. When PRIMER_TASK=pick_discriminative_primers or PRIMER_TASK=pick_cloning_primers the value of SEQUENCE_INCLUDED_REGION is no longer changed to the entire input sequence.
9. The handling of divalent cations when PRIMER_SALT_CORRECTIONS=2 (not the default and not the recommended value) has been updated. The rationale is that, when divalent cations are present, the formula by Owczarzy et al., 2004 (used previously by Primer3) can be improved upon as described in (Ahsen et al., 2010; Owczarzy et al., 2008). Therefore we have updated the melting temperature calculation to follow the scheme in Figure 9 of (Owczarzy et al., 2008). Please find references to these papers below in the manual.
10. We modified the error handling of non-memory related errors that can occur during the thermodynamic alignment. They are no longer fatal errors.
11. We removed io_version 3, which was only kept for backward compatibility with very old versions of primer3.
12. In addition, several error corrections:
12.1. Corrected a short, fixed-size buffer for the file/path names specified by the command line arguments -output, -error and for the settings file.
12.2. Two other corrected errors were in p3_set_gs_primer_self_end and p3_set_gs_primer_internal_oligo_self_end, which erroneously multiplied their 'val' arguments by 100.
12.3. Primer3 now detects and handles the situation in which user-supplied primers (SEQUENCE_PRIMER and SEQUENCE_PRIMER_REVCOMP) have the left primer to the right of the right primer. Also issue a warning if user-supplied primers occur in more than one location in the template.

## 6. INSTALLATION INSTRUCTIONS - UNIX/LINUX

Unzip and untar the distribution. DO NOT do this on a PC if you are going to compile and/or test on a different operation system. Primer3_core will not compile and various tests will fail if pc newlines get inserted into the code and test files. Instead, move the distribution (primer3-<release>.tar.gz) to Unix/Linux, and then
$ unzip primer3-<release>.tar.gz
$ tar xvf primer3-<release>.tar
$ cd primer3-<release>/src
If you do not use gcc, then you will probably have to modify the makefile to use your (ANSI) C compiler with the compile and link flags it understands.
$ make all
# You should have created executables primer3_core, ntdpal,
# olgotm, and long_seq_tm_test
$ make test
# You should not see 'FAILED' during the tests.
If your perl command is not called perl (for example, if it is called perl5) you will have to modify the Makefile in the test/ directory.
ntdpal (NucleoTide Dynamic Programming ALignment) is a stand-alone program that provides primer3's alignment functionality (local, a.k.a. Smith-Waterman, global, a.k.a. Needleman-Wunsch, plus "half global"). It is provided strictly as is; for further documentation please see the code.

## 7. INSTALLATION INSTRUCTIONS - Mac OSX

How to install this software
============================
1. Double click on the .tar.gz file to extract the archive.
2. The binary files are located in the 'bin' [for 'binary'] folder
3. (Optional) To run the tests, cd to the new directory and then the test folder
4. (Optional) Within this folder run: a. 'perl -w p3test.pl'
5. (Optional) You should not see 'FAILED' during the tests.
6. (Optional) *NOTE*: If your perl command is not called perl (for example, if it is called perl5) you will have to modify the internals of the test scripts).
7. Copy the following files to a location of your choice:
a. bin/long_seq_tm_test
b. bin/ntdpal
c. bin/oligotm
d. bin/primer3_core
8. (Optional) Make sure this location is within your $PATH (see below)
Where to put the binary files
=============================
A good place to put these is within ~/bin/ (this means in your home folder, within a folder named `bin` [for 'binary']).
You can also just drag the 'bin' folder to a location within your home directory.
You can certainly also copy the files within 'bin' to /usr/local/bin (if you are an administrator) or another similar location.
You may need to adjust the permissions on the binaries if you get fancy.
Add the location to your $PATH
==============================
This is an optional step, but it will allow you to run primer3 in any directory on your machine as your user just by typing its name (primer3_core).
*** You should be very careful when altering your $PATH as things can go very wrong. See below for an alternate method. ***
If you added the binaries to /usr/local/bin, then you do not need to do this.
If you added the binaries to a local directory (let's say ~/bin/), do the following:
1. Edit your ~/.bash_profile. You can edit this on the command line (Terminal) with:
nano ~/.bash_profile
2. Add the following line if it is not present (replacing '~/bin' if you used another directory):
PATH=$PATH:~/bin/
3. If a PATH line *is* present, ensure you add a colon to the end of what is there and then the directory, so if you have something like:
a) PATH=$PATH:/usr/local/genome/bin:/sw/bin
make it look like:
b) PATH=$PATH:/usr/local/genome/bin:/sw/bin:~/bin
4. Quit and restart terminal for the changes to take effect.
If you don't add the location to your $PATH
===========================================
Assuming you don't want to modify your $PATH, you can still run the binaries. Let's assume you put the files in '~/bin/. You may run primer3_core by doing either of the following:
1. ~/bin/primer3_core < yourInputFile
2. /Users/<your username>/bin/primer3_core < yourInputFile
The first option is just a shortcut to the second.

## 8. INSTALLATION INSTRUCTIONS - WINDOWS

How to install this software
============================
1. Unzip the '.zip' file downloaded from SourceForge.net
2. You will create a primer3-<release> folder in the location where the file was unzipped
3. You may copy the files from the 'bin' directory of the primer3-<release> folder to a location of your choice. The exact same files are located within the 'src' folder so that the tests may be run (windows does not allow relative paths in shortcuts).
Running the tests
=================
You must install a perl distribution to run the windows tests.
We *strongly* recommend you install ActiveState perl (http://www.activestate.com/products/activeperl/) as this was used to test our primer3 builds, and it is known to work.
1. Click on 'Start > Run...'
2. Type 'cmd' into the space provided
3. Hit enter (or select 'OK')
4. Navigate to the location of the tests:
A. if you put it in
C:/Documents and Settings/YourName/primer3-<release>/test/,
you would type
'cd c:/Documents and Settings/YourName/primer3-<release>/test/'
B. you can also type 'cd ' (don't forget the space after cd) and drag the primer3-<release> folder onto the command-line window from windows explorer, this will fill in the location for you
5. On the command line, run 'mingw32-make TESTOPTS=--windows' in this directory. You can also run the tests individually, for example 'perl p3test.pl --windows'.
6. You should see [OK] for all of the tests.
Running the software
====================
To run the program, you must do so from the MS-DOS command-line. The intricacies of the DOS command line are beyond the scope of this document. Google for more information, if needed. Here is a quick summary:
1. Click on 'Start > Run...'
2. Type 'cmd' into the space provided
3. Hit enter (or select 'OK')
4. Navigate to the location of the binary:
A. if you put it in
C:/Documents and Settings/YourName/Temp,
you would type
'cd c:/Documents and Settings/YourName/Temp'
B. you can also type 'cd ' (don't forget the space after cd) and drag the primer3 folder onto the command-line window from windows explorer, this will fill in the location for you
5. Run the example file by typing:
primer3_core.exe < example
Other files may be run in a similar fashion. If your input filename is 'MyData.txt' you can run primer3 using this file (in the correct format; see README) with:
primer3_core.exe < MyData.txt
If your file is not in the folder containing primer3_core.exe, you could run the program from the primer3_core folder using:
primer3_core.exe < c:/someOtherFolder/someOtherFolder/MyData.txt
Finally, if you want to run the program without going to its folder, assuming primer3_core.exe is in c:/Temp, you could run:
c:/Temp/primer3_core.exe < c:/someOtherFolder/someOtherFolder/MyData.txt

## 9. BUILDING A Mac OSX UNIVERSAL BINARY

** To build a processor-native, NON-universal binary of primer3, the following is NOT necessary**.
The instructions above should be sufficient.
A pre-compiled, universal binary download for OSX is available from http://sourceforge.net/projects/primer3/ for the current release.
These instructions assume you want to build binaries compatible with *both* of the current processor architectures used by the Apple platform (i,e. the binaries will be run on both PPC and Intel platforms).
Provided you have the OS X developer tools installed (you can download from http://developer.apple.com after registering for a free account), you can compile a universal build (Intel and PPC native) of primer3.
o you must be running OS X > 10.4 and should have the most recent version of XCode
o run `make -f Makefile.OSX.Leopard all` if you run OS X 10.5
o run `make -f Makefile.OSX.Tiger all` is you run OS X 10.4
o run the tests as directed above
Additional instructions for 'installing' the binaries may be found in the README.OSX.txt.
You should be able to compile a 3-way binary which includes PPC64 support (Intel, PPC, PPC64) by adding the `-arch ppc64` flag to the end of both the CFLAGS and LDFLAGS lines at the top of Makefile.OSX. This has not been tested.

## 10. SYSTEM REQUIREMENTS

Please see http://sourceforge.net/projects/primer3/ for up-to-date information. Primer3 should compile on any system using with an ANSI C compiler like Linux/Unix, MacOS 10 or MS Windows. The Makefile will probably need to be modified for compilation with C compilers other than gcc.

## 11. INVOKING primer3_core

By default, the executable program produced by the Makefile is called primer3_core. This is the C program that does the heavy lifting of primer picking. There are also two, more user-friendly, web interfaces (distributed separately).
The command line for primer3 is:
primer3_core [ -format_output ] [ -default_version=1|-default_version=2 ] [ -io_version=4 ] [ -p3_settings_file=<file_path> ] [ -echo_settings_file ] [ -strict_tags ] [ -output=<file_path> ] [ -error=<file_path> ] [ input_file ]
A complete list of valid command line arguments can be found in COMMAND LINE ARGUMENTS below.
If no input file is specified, primer3_core will read its input from stdin.

## 12. COMMAND LINE ARGUMENTS

This section presents the list of arguments that may given in the command line. Any unique abbreviation of the arguments is allowed (e.g. -ab instead of -about) and each argument can be preceded by either one or two dashes. In the case of arguments that receive values, the '=' can be replaced by a space.

### -about

With this argument primer3 generates one line of output indicating the release number and then exits. This allows scripts to query primer3 for its version.

### -default_version=n

n=2 is the default, and directs primer3_core to use the latest default values (the ones documented here). n=1 directs primer3_core to use defaults from version 2.2.3 and before.

### -format_output

This argument indicates that primer3_core should generate user-oriented (rather than program-oriented) output.

### -strict_tags

This argument indicates that primer3_core should generate a fatal error if there is any tag in the input that it does not recognize. This tag also applies to the settings file (see documentation for the -p3_settings_file argument), if any, but with limitations: lines that do not begin with PRIMER_ or P3_FILE_ID are always ignored in the settings file.

### -p3_settings_file=file_path

This argument specifies a settings file, file_path. Primer3 reads the global ("PRIMER_...") parameters from this file first. Tags appearing in the settings file override default primer3 settings. The values set in the settings files can be also overridden by tags in the input file. See primer3 file documentation for details on the file format. WARNING: the -strict_tags flag applies only to tags beginning with the string "PRIMER_"; lines that do not begin with the string "PRIMER_" are ignored.

### -echo_settings_file

This argument indicates that primer3_core should print the input tags specified in the given settings file. If no settings file is provided or if the -format_output option is given, this argument will have no effect.

### -io_version=n

This argument is provided for backward compatibility. -io_version=4 is the only legal value and the default. -output=file_path