Settings: Settings Functionalities.

In matdoering/openPrimeR: Multiplex PCR Primer Design and Analysis

Settings Functionalities.

Description

DesignSettings

The DesignSettings class encapsulates all settings for designing and evaluating primer sets. Upon loading an XML file, the DesignSettings class checks whether the defined constraints can be applied by identifying whether the requirements for external programs are fulfilled. If the requirements are not fulfilled, the affected constraints are removed from the loaded DesignSettings object and a warning is issued. The loaded constraints are automatically ordered according to the option openPrimeR.constraint_order such that the runtime of the design_primers and filter_primers functions is optimized.

constraints

Gets the active constraints of the provided DesignSettings object.

constraints<-

Sets the active constraints of the provided DesignSettings object.

cvg_constraints

Gets the coverage constraints of the provided DesignSettings object.

cvg_constraints<-

Sets the coverage constraints of the provided DesignSettings object.

conOptions

Gets the constraint settings of the provided DesignSettings object.

conOptions<-

Sets the constraint settings of the provided DesignSettings object.

constraintLimits

Gets the constraint limits that are defined in the provided DesignSettings object.

constraintLimits<-

Sets the constraint limits of the provided DesignSettings object.

PCR

Gets the PCR conditions that are defined in the provided DesignSettings object.

PCR<-

Sets the PCR conditions that are defined in the provided DesignSettings object.

ConstraintSettings

The ConstraintSettings class encapsulates the constraints on the physicochemical properties of primers.

CoverageConstraints

The CoverageConstraints class encapsulates the conditions under which the coverage of primers is evaluated.

PCR_Conditions

The PCR_Conditions class encapsulates the PCR conditions for the computation of primer properties.

ConstraintOptions

The ConstraintOptions class encapsulates the options for constraint computations.

parallel_setup

Registers the specified number of cores with the parallel backend.

Usage

constraints(x)

## S4 method for signature 'DesignSettings'
constraints(x)

## S4 method for signature 'AbstractConstraintSettings'
constraints(x)

cvg_constraints(x)

## S4 method for signature 'DesignSettings'
cvg_constraints(x)

PCR(x)

## S4 method for signature 'DesignSettings'
PCR(x)

conOptions(x)

## S4 method for signature 'DesignSettings'
conOptions(x)

constraintLimits(x)

## S4 method for signature 'DesignSettings'
constraintLimits(x)

constraints(x) <- value

## S4 replacement method for signature 'DesignSettings,list'
constraints(x) <- value

## S4 replacement method for signature 'AbstractConstraintSettings,list'
constraints(x) <- value

cvg_constraints(x) <- value

## S4 replacement method for signature 'DesignSettings'
cvg_constraints(x) <- value

constraintLimits(x) <- value

## S4 replacement method for signature 'DesignSettings'
constraintLimits(x) <- value

PCR(x) <- value

## S4 replacement method for signature 'DesignSettings'
PCR(x) <- value

conOptions(x) <- value

## S4 replacement method for signature 'DesignSettings'
conOptions(x) <- value

parallel_setup(cores = NULL)

Arguments

x	A DesignSettings object.
value	An object to be used in one of the setters. For constraints<- and constraintLimits<-, a list with constraint settings or boundaries. Each list entry should have a permissible name and consist of at most two values providing the minimal and/or maximal allowed values, which have to be denominated via min and max. For conOptions<-, a list with constraint options. The permissible fields of the list and their types are documented in the ConstraintOptions class. For cvg_constraints<-, a list with coverage constraints. Each list entry must have a permissible name and contain a numeric vector with at most two components describing the minimal and/or maximal required values that are to be indicated via min and max. The permissible contraint identifiers are documented in the CoverageConstraints class. For PCR<-, a named list providing PCR conditions The permissible fields of the list and their types are documented in the PCR_Conditions class.
cores	A numeric providing the number of cores to use. The default is NULL such that half the number of available cores are used.

Details

Note that for the DesignSettings class, the fields Input_Constraints, Input_Constraint_Boundaries, and Coverage_Constraints should contain entries with at most two components using the fields min and/or max. The Input_Constraint_Boundaries should always be at least as general as the specified Input_Constraints.

For an overview of permissible constraints, please consider the ConstraintSettings documentation.

Value

The ConstraintSettings constructor defines a new ConstraintSettings object.

The CoverageConstraints constructor initializes a new CoverageConstraints object.

The ConstraintOptions constructor returns a new ConstraintOptions object.

The PCR_Conditions constructor defines a new PCR_Conditions object.

The DesignSettings constructor defines a DesignSettings object.

constraints gets a list with the active constraint settings.

cvg_constraints returns the list of active coverage constraints.

PCR gets the list of PCR conditions defined in the provided DesignSettings object.

conOptions returns a list with constraint options.

constraintLimits gets the list of constraint limits.

constraints<- sets the list of constraints in a DesignSettings object.

cvg_constraints<- sets the list of coverage constraints in the provided DesignSettings object.

constraintLimits<- sets the list of constraint limits in the provided DesignSettings object.

PCR<- sets the constraint options in the provided DesignSettings object.

conOptions<- sets the specified list of constraint options in the provided DesignSettings object.

parallel_setup returns NULL.

Slots

Input_Constraints

A ConstraintSettings object specifying the desired target value ranges for primer properties.

Input_Constraint_Boundaries

A ConstraintSettings object specifying the limits for relaxing the constraints during the primer design procedure. This slot may contain the same fields as the Input_Constraints slot, but the specified desired ranges should be at least as general as those specified in the Input_Constraints slot.

Coverage_Constraints

A CoverageConstraints object specifying the constraints for computing the primer coverage.

PCR_conditions

A PCR_Conditions object specifying the PCR-related settings.

constraint_settings

A ConstraintSettings object providing options for the computation of individual physicochemical properties.

status

Named boolean vector indicating which of the possible constraints are active (TRUE) and which are not (FALSE).

settings

For ConstraintSettings, a named list containing the settings for the active constraints. The list may contain the following fields:

primer_coverage:

The required number of covered template sequences per primer.

primer_specificity:

The required required specificity of primers in terms of a ratio in the interval [0,1].

primer_length:

The required lengths of primer sequences.

gc_clamp:

The desired number of GCs at primer 3' termini.

gc_ratio:

The desired ratio of GCs in primers in terms of numbers in the interval [0,1].

no_runs:

The accepted length homopolymer runs in a primer.

no_repeats:

The accepted length of dinucleotide repeats in a primer.

self_dimerization:

The lowest acceptable free energy [kcal/mol] for the interaction of a primer with itself. The identification of self dimers requires the software OligoArrayAux (see notes).

melting_temp_range:

The desired melting temperature (Celsius) of primers. The accurate computation of melting temperatures requires the software MELTING (see notes).

melting_temp_diff:

The maximal allowed difference between the melting temperatures (Celsius) of primers contained in the same set. The accurate computation of melting temperatures requires the software MELTING (see notes).

cross_dimerization:

The lowest acceptable free energy [kcal/mol] for the interaction of a primer with another primer. The identification of cross dimers requires the software OligoArrayAux (see notes).

secondary_structure:

The lowest acceptable free energy [kcal/mol] for the formation of primer secondary structures. Secondary structures are determined using the software ViennaRNA (see notes).

For PCR_Conditions, a named list with PCR conditions. The following fields are possible:

use_taq_polymerase:

A logical identifying whether you are performing PCR with a Taq polymerase (TRUE) or not (FALSE).

annealing_temp:

The annealing temperature in Celsius that is to be used for evaluating the constraints defined in the ConstraintSettings object. If the annealing temperature field is not provided, a suitable annealing temperature is automatically computed using a rule of thumb (i.e. subtracting 5 from the melting temperature).

Na_concentration:

The molar concentration of monovalent sodium ions.

Mg_concentration:

The molar concentration of divalent magnesium ions.

K_concentration:

The molar concentration of monovalent potassium ions.

Tris_concentration:

The molar concentration of the Tris(hydroxymethyl)-aminomethan buffer.

primer_concentration:

The molar concentration of the PCR primers.

template_concentration:

The molar concentration of the PCR templates.

For CoverageConstraints, a named list with constraint options. Each list entry should have an entry min and/or max in order to indicate the minimal and maximal allowed values, respectively. The following identifiers can be used as coverage constraints:

primer_efficiency:

The desired efficiencies of primer-template amplification events in order to be considered as covered. primer_efficiency provides a value in the interval [0,1], which is based on DECIPHER's thermodynamic model, which considers the impact of 3' terminal mismatches.

annealing_DeltaG:

The desired free energies of annealing for putative coverage events between primers and templates. Typically, one would limit the maximally allowed free energy.

stop_codon:

Whether coverage events introducing stop codons into the amplicons should be allowed or discarded. Here, a value of 1 indicates coverage events that induce stop codons. As such, setting both minimum and maximium to zero will disregard coverage events inducing stop codons, while setting the minimum to zero and the maximum to 1 will allow coverage events that induce stop codons.

substitution:

Whether coverage events introducing substitutions into the amino acid sequence are considered or discarded. The same encoding as for stop_codon is used, that is, the value 1 indicates coverage events inducing substitutions. Hence, to prevent substitutions, the maximal value of substitution can be set to zero.

terminal_mismatch_pos:

The position relative to the primer 3' terminal end for which mismatch binding events should be allowed, where the last base in a primer is indicated by position 1. For example, setting the minimal value of terminal_mismatch_pos to 7 means that only coverage events that do not have a terminal mismatch within the last 6 bases of the primer are allowed.

coverage_model:

Use a logistic regression model combining the free energy of annealing and 3' terminal mismatch positions to determine the expected rate of false positive coverage calls. Using coverage_model, you can specify the allowed ratio of falsely predicted coverage events. Typically, one would limit the maximal allowed rate of false positives. Note that setting a small false positive rate will reduce the sensitivity of the coverage calls (i.e. true positives will be missed).

For ConstraintOptions, a named list with constraint options. The following fields are permissible:

allowed_mismatches:

The maximal number of allowed mismatches between a primer and a template sequence. If the number of mismatches of a primer with a template exceeds the specified value, the primer is not considered to cover the corresponding template when the coverage is being computed.

allowed_other_binding_ratio:

Ratio of allowed binding events outside the target binding ratio. This value should be in the interval [0,1]. If the specified value is greater than zero, all coverage events outside the primer binding region are reported. If, however, the identified ratio of off-target events should exceed the allowed ratio, a warning is issued. If allowed_other_binding_ratio is set to 0, only on-target primer binding events are reported. The setting of allowed_other_binding_ratio is ignored when designing primers, which always uses a value of 0.

allowed_region_definition:

The definition of the target binding regions that is used for evaluating the coverage. In case that allowed_region_definition is within, primers have to lie within the allowed binding region. If allowed_region_definition is any, primers only have to overlap with the target binding region.

hexamer_coverage:

If hexamer_coverage is set to "active", primers whose 3' hexamer (the last 6 bases) is fully complementary to the corresponding template region are automatically considered to cover the template. If hexamer_coverage is set to inactive, hexamer complementarity does not guarantee template coverage.

primer_coverage

Computing the primer coverage involves identifying which templates are expected to be amplified (covered) by which primers. The primer_coverage constraint determines the minimal and maximal number of coverage events per primer that are required. The computation of primer coverage is governed by the coverage constraints postulated via CoverageConstraints and the constraint options defined via ConstraintOptions.

primer_specificity

Primer specificity is automatically determined during the primer coverage computations but the constraint is only checked when the primer_specificity field is available. The specificity of a primer is defined as its ratio of on-target vs total coverage events (including off-target coverage). Low-specificity primers should be excluded as they may not amplify the target region effectively.

primer_length

The length of a primer is defined by its number of bases. Typical primers have lengths between 18 and 22. Longer primers may guarantee higher specificities.

gc_clamp

The GC clamp refers to the presence of GCs at the 3' end of a primer. For the gc_clamp constraint, we consider the number of 3' terminal GCs. For example, the primer actgaaatttcaccg has a GC clamp of length 3. The presence of a GC clamp is supposed to aid the stability of the polymerase complex. At the same time, long GC clamps should be avoided.

no_runs

Homopolymer runs (e.g. the primer aaaaa has a run of 5 A's) may lead to secondary structure formation and unspecific binding and should therefore be avoided.

no_repeats

Dinucleotide repeats (e.g. the primer tatata has 3 TA repeats) should be avoided for the same reason a long homopolymer runs.

self_dimerization

Self dimerization refers to a primer that binds to itself rather than to one of the templates. Primers exhibiting self dimers should be avoided as they may prevent the primer from amplifying the templates. Therefore primers with small free energies of dimerization should be avoided.

melting_temp_range

The melting temperature is the temperature at which 50 are in duplex with templates and 50 Hence, primers exhibiting high melting temperatures have high affinities to the templates, while primers with small melting temperatures have small affinities. The melting temperatures of the primers determine the annealing temperature of the PCR, which is why the melting temperatures of the primers should not deviate too much (see melting_temp_diff).

melting_temp_diff

The differences between the melting temperatures of primers in a set of primers should not deviate too much as the annealing temperaturte of a PCR should be based on the smallest melting temperature of a primer in the set. If there are other primers in the set exhibiting considerably higher melting temperatures, these primers may bind inspecifically due to the low annealing temperature.

cross_dimerization

When two different primers bind to each each other rather than to the templates, this is called cross dimerization. Cross dimerization should be prevent at all costs because such primers cannot effectively amplify their target templates. Cross dimerizing primers can be excluding primers exhibiting small free energies of cross dimerization.

secondary_structure

When a primer exhibits secondary structure, this may prevent it from binding to the templates. To prevent this, primers with low free energies of secondary structure formation can be excluded.

Note

The following external programs are required for constraint computations:

MELTING (http://www.ebi.ac.uk/biomodels/tools/melting/):

Thermodynamic computations (optional) for determining melting temperatures for the constraints melting_temp_diff and melting_temp_range

OligoArrayAux (http://unafold.rna.albany.edu/OligoArrayAux.php):

Thermodynamic computations used for computing self_dimerization and cross_dimerization. Also required for computing primer_coverage when a constraint based on the free energy of annealing is active.

ViennaRNA (http://www.tbi.univie.ac.at/RNA/):

Secondary structure predictions used for the constraint secondary_structure

The following external programs are required for computing the coverage constraints:

OligoArrayAux (http://unafold.rna.albany.edu/OligoArrayAux.php):

Thermodynamic computations used for computing the coverage constraints annealing_DeltaG, primer_efficiency, and coverage_model

See Also

read_settings for reading settings from XML files, write_settings for storing settings as XML files, constraints for accessing constraints, constraintLimits for accessing constraint boundaries, cvg_constraints for accessing coverage constraints, conOptions for accessing constraint options, PCR for accessing the PCR conditions.

Examples

# Initializing a new 'ConstraintSettings' object:
constraint.settings <- new("ConstraintSettings")
# Retrieving the constraint settings from a 'DesignSettings' object:
data(Ippolito) # loads a 'DesignSettings' object into 'settings'
constraints(settings)
# Modifying the constraint settings:
constraints(settings)$no_runs["max"] <- 10
constraints(settings) <- constraints(settings)[names(constraints(settings)) != "gc_clamp"]

# Initialize a new 'CoverageConstraints' object:
cvg.constraints <- new("CoverageConstraints")
# Retrieving the coverage constraints from a 'DesignSettings' object:
data(Ippolito) # loads a 'DesignSettings' object into 'settings'
cvg_constraints(settings)
# Modifying the coverage constraints
cvg_constraints(settings)$primer_efficiency["min"] <- 0.001

# Initialize a new 'ConstraintOptions' object:
constraint.options <- new("ConstraintOptions")
# Retrieve the constraint options from a 'DesignSettings' object:
data(Ippolito) # loads a 'DesignSettings' object into 'settings'
conOptions(settings)
# Prevent off-target binding:
conOptions(settings)$allowed_other_binding_ratio <- 0

# Initialize a new 'PCR_Conditions' object:
PCR.conditions <- new("PCR_Conditions")
# Retrieving the PCR conditions from a 'DesignSettings' object:
data(Ippolito) # loads a 'DesignSettings' object into 'settings'
PCR(settings)
# Modifying the PCR conditions:
PCR(settings)$use_taq_polymerase <- FALSE

# Load a settings object
filename <- system.file("extdata", "settings", 
                 "C_Taq_PCR_high_stringency.xml", package = "openPrimeR")
settings <- read_settings(filename)
# Modify the constraints
constraints(settings)$gc_clamp["min"] <- 0
# Modify the constraint limits for designing primers
constraintLimits(settings)$gc_clamp["max"] <- 6
# Modify the coverage constraints
cvg_constraints(settings)$primer_efficiency["min"] <- 0.001
# Modify the PCR conditions
PCR(settings)$Na_concentration <- 0.0001
# Modify the constraint options
conOptions(settings)$allowed_mismatches <- 0

# Load some settings
data(Ippolito)
# View the active constraints
constraints(settings)
# Require a minimal GC clamp extent of 0
constraints(settings)$gc_clamp["min"] <- 0
# View available constraints
settings

# Load some settings
data(Ippolito)
# View all active coverage constraints
cvg_constraints(settings)
# Increase the maximal false positive rate to increase the sensitiviity of coverage predictions
cvg_constraints(settings)$coverage_model <- c("max" = 0.1) 
# View available coverage constraints:
settings

# Load some settings
data(Ippolito)
# View the active constraint limits
constraintLimits(settings)
# Extend the GC relaxation limit
constraintLimits(settings)$gc_clamp <- c("min" = 0, "max" = 6)
# View available constraints
settings

# Load some settings
data(Ippolito)
# View the active PCR conditions
PCR(settings)
# Evaluate primers with a fixed annealing temperature
PCR(settings)$annealing_temperature <- 50 # celsius
# View available PCR conditions
settings

# Load some settings
data(Ippolito)
# View the active constraint options
conOptions(settings)
# Prevent mismatch binding events
conOptions(settings)$allowed_mismatches <- 0
# View available constraint options
settings
# Use two cores for parallel processing:
parallel_setup(2)

matdoering/openPrimeR documentation built on Feb. 11, 2024, 9:22 p.m.