MultiPLX

ReadMe.txt Version 1.2

MultiPLX is a tool for automatic grouping and checking PCR primers. It can
analyze many factors affecting primer pair compatibility, such as primer-primer
alignments, primer-product alignments, differences in melting temperatures and
product length differences. Grouping is based on calculated compatibility scores
and user specified cutoff vaues for each score.
It is also possible to use custom score values to incorporate additional
parameters into grouping.

1. Command-line arguments:

-primers FILENAME        - [REQUIRED] Load primers from file
-thermodynamics FILENAME - [OPTIONAL] nearest neigbour parameter file (default thermodynamics.txt)
-csalt                   - [OPTIONAL] Concentration of monovalent salts in mM (default 50)
-cmg                     - [OPTIONAL] Concentration of magnesium in mM (default 1.5)
-cdna                    - [OPTIONAL] Concentration of DNA in nM (default 50)
-saveprimerinfo FILENAME - [OPTIONAL] Save primer info to file ('-' is stdout)
-savealignments NAME NAME FILENAME - [OPTIONAL] Save primer alignement info to file ('-' is stdout)
-scores FILENAME       - [OPTIONAL] read scores from file (erase existing)
-scores +FILENAME      - [OPTIONAL] import scores from file (non-destructive)
-calcscores VALUES     - [OPTIONAL] calculate scores (1-5, for example 134) 
-listscores            - [OPTIONAL] List score codes
-savescores FILENAME   - [OPTIONAL] Save scores to file
-stringency VALUE      - [OPTIONAL] Set grouping stringency value (low, normal, high)
-cutoff# VALUE         - [OPTIONAL] Set grouping cutoff
-listcutoffs           - [OPTIONAL] List cutoff codes
-calcgroups MAXGROUPS MAXITEMSINGROUP - [OPTIONAL] Calculate groups
-initialorder VALUE    - [OPTIONAL] Initial order for grouping (file, friends, random)
-groupiter VALUE       - [OPTIONAL] Number of tries to find best grouping
-optimize ITERATIONS   - [OPTIONAL] Iterations to try while distributing items (default 10000)
-savegroups FILENAME   - [OPTIONAL] Save groups to file ('-' is stdout)
-groups FILENAME       - [OPTIONAL] Load group definitions from file
-saveoffenders FILENAME - [OPTIONAL] Save group analysis into file ('-' is stdout)
-v
-version               - [OPTIONAL] print program version information and exit
-h
-help                  - [OPTIONAL] print this help screen and exit program

The maximum number of primer pairs depends on available memory and build options. The
hard limit on 32 bit processors is about 15000 (determined by 2GB userspace memory limit)


2. Default parameters

2.1. Salt and DNA concentrations

Salt and DNA concentrations affect melting temperatures of primers, but this is mostly
irrelevant for multiplexing, as only temperature differences are used, and thus uniformly
lower or higher values do not affect results much. So if the exact experiment conditions are
not known beforehand, defaults (or whatever reasonable values) are safe to use for multiplexing.
MultiPLX uses the following formula to calculate melting temperature:

Tm = dH / (dS + 1.987 * ln (cDNA)) + 16.6 * log (Na+[NORM])

Tm - melting temperature in Kelvins
dH, dS - binding enthalpy and enthropy
Na+[NORM] - normalized salt concentration

To calculate Na+[NORM]

Na+[NORM] = (Na+[mM] + 120.0 * sqrt (Mg2+[mM] - dNTP[mM])) / 1000;

Na+[mM], Mg2+[mM] - the concentrations of monovalent and divalent cations in mM/l
dNTP[mM] - the total concentration of nucleotide triphosphates in mM/l
(Source: von Ahsen, N., Wittwer, C.T., Schutz, E., Oligonucleotide Melting Temperatures
under PCR Conditions: Nearest-Neighbour Corrections for Mg2+, Deoxynucleotide Triphosphate,
and dimetyl Sulfoxide Concentrations with Comparison to Alternative Empirical Formulas.
Clinical Chemistry 47, No. 11, 2001


2.2. Cutoff and stringency

Stringency values are just convenient packages of individual cutoffs. If one only wants to
adjust few cutoff values, specifying both stringency and cutoff is possible (defaults are
loaded from stringency, and specific cutoff values override defaults).

Low stringency (-stringency low)

PrimPrimEnd2:           -6.0
PrimPrimEnd1:          -10.0
PrimPrimAny:           -10.0
PrimProdEnd1:          -14.0
PrimProdAny:           -14.0
Max prod len diff:         -
Min Prod len diff:         -
Max Melting temp diff:     -
Max custom score:          -

Normal stringency (-stringency normal)

PrimPrimEnd2:           -4.0
PrimPrimEnd1:           -8.0
PrimPrimAny:            -8.0
PrimProdEnd1:          -12.0
PrimProdAny:           -12.0
Max prod len diff:         -
Min Prod len diff:         -
Max Melting temp diff:     -
Max custom score:          -

High stringency (-stringency high)

PrimPrimEnd2:           -2.0
PrimPrimEnd1:           -6.0
PrimPrimAny:            -6.0
PrimProdEnd1:          -10.0
PrimProdAny:           -10.0
Max prod len diff:         -
Min Prod len diff:         -
Max Melting temp diff:     -
Max custom score:          -

As you can see, default values do not take neither product length differences nor melting
temperature differences into account, so if these should be used, specifying explicit
cutoff values is needed.

The higher the stringency is, the more groups is needed with fewer members in each group. We
expect normal parameters to give reasonable values, but in practice multiplexing results
depend on many more factors (quality of primers, enzymes used etc.), so often it may be
preferable to decide preferred multiplexing level initially, and use MultiPLX to help to find
optimum grouping solution. As only the score calculation is time-consuming, it can be done
once, and reuse saved score file for different grouping runs.


3. File formats

Primer File
--------------------------------------------

    PCR Name [TAB] Left primer [TAB] Right Primer [TAB] Product(s) (optional)
    ...

Multiple products can be listed, separated by single space.
PCR Name (such as SNP name) has to be unique.


Score file
--------------------------------------------

    Name [TAB] Name [TAB] Column names
    PCR Name 1 [TAB] PCR name 2 [TAB] Scores
    ...

Valid column headers are:
PrimPrimEnd2, PrimPrimEnd1, PrimPrimAny, PrimProdEnd1, PrimProdAny, Custom
If header is unrecognized, column will be silently ignored.
Any number of scores can be present in score file, in arbitrary column order.
Not all primer combinations have to be present in score file.
Extra primer combinations (with unrecognized names) will be silently ignored.

Importing (-scores +FILENAME) score file with custom score column is the way
to include user-specified parameters into grouping. There can be only single
custom score, so if more are needed, user has to join these beforehand into
composite score, using perl, excel or some other tool.

Groups file
--------------------------------------------

    MXMultiplexTable
    Name [TAB] 1 [TAB] 2...
    Group ID [Tab] PCR 1 [TAB] PCR 2...
    ...

All tables can have arbitrary number of comment rows, starting with '#'.


4. Examples

4.1. Calculating score table and saving it to file

  cmultiplx -primers myprimers.txt -calcscores 134 -savescores myscorefile.txt

4.2. Calculating groups from score table

  cmultiplx -primers myprimers.txt -scores myscorefile.txt -calcgroups 1000 1000 -stringency high
    -savegroups mygroupfile.txt

4.3. Viewing alignements between primer pairs

  cmultiplx -primers myprimers.txt -savealignments P1 P2 alignfile.txt

  * P1 and P2 are primer (PCR) names from primer file

4.4. Verifying existing groups

  cmultiplx -primers myprimers.txt -scores myscorefile.txt -groups mygroups.txt -stringency high
    -saveoffenders offenderlist.txt




5. WinMultiPLX

There is also convenient graphical version of MultiPLX for Windows in development.
For more information, check out at http://www.biodata.ee/



5. November 2004

