Settings {openPrimeR} | R Documentation

## 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. Note that this value is the buffer concentration. To determine corresponding Tris ion concentration, the value of the buffer concentration is halved.

  `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)

[Package openPrimeR version 1.8.0 Index]