PrimerDesign: Primer Design Functionalities.
In openPrimeR: Multiplex PCR Primer Design and Analysis

Description Usage Arguments Details Value Note Examples

design_primers: Designs a primer set maximizing the number of covered templates using the smallest possible number of primers. The algorithm tries to ensure that the designed set of primers achieves a coverage ratio not lower than required.cvg. To this end, the constraints for designing primers may be relaxed.
classify_design_problem: Uses reference beta distributions of primer coverage ratios to classify a primer design task into groups ranging from easy to hard. For easy tasks, it should not be a problem to design a small primer set. For hard tasks, however, a small set of primers may not be achievable.
get_initial_primers: Creates a set of primer candidates based on the input template sequences. This set of primers can be used to create custom primer design algorithms.

classify_design_problem(
  template.df,
  mode.directionality = c("both", "fw", "rev"),
  primer.length = 18,
  primer.estimate = FALSE,
  required.cvg = 1
)

get_initial_primers(
  sample,
  template.df,
  primer.lengths,
  mode.directionality = c("fw", "rev"),
  allowed.region.definition = c("within", "any"),
  init.algo = c("naive", "tree"),
  max.degen = 16,
  conservation = 1,
  updateProgress = NULL
)

design_primers(
  template.df,
  mode.directionality = c("both", "fw", "rev"),
  settings,
  init.algo = c("naive", "tree"),
  opti.algo = c("Greedy", "ILP"),
  required.cvg = 1,
  timeout = Inf,
  max.degen = 16,
  conservation = 1,
  sample.name = NULL,
  cur.results.loc = NULL,
  primer.df = NULL,
  updateProgress = NULL
)

`template.df`	A `Templates` object containing the template sequences with annotated primer target binding regions.
`mode.directionality`	The template strand for which primers shall be designed. Primers can be designed either for forward strands ("fw"), for reverse strands ("rev"), or for both strands ("both"). The default setting is "both".
`primer.length`	A scalar numeric providing the target length of the designed primers. The default length of generated primers is set to `18`.
`primer.estimate`	Whether the number of required primers shall be estimated. By default (`FALSE`), the number of required primers is not estimated.
`required.cvg`	The desired ratio of of covered template sequences. If the target coverage ratio cannot be reached, the constraint settings are relaxed according to the the constraint limits in order to reach the target coverage. The default `required.cvg` is set to 1, indicating that 100% of the templates are to be covered.
`sample`	Character vector providing an identifier for the templates.
`primer.lengths`	Numeric vector of length 2 providing the minimal and maximal allowed lengths for generated primers.
`allowed.region.definition`	A character vector providing the definition of region where primers are to be constructed. If `allowed.region.definition` is "within", constructed primers lie within the allowed binding region. If `allowed.region.definition` is "any", primers overlap with the allowed binding region. The default is "within".
`init.algo`	The algorithm to be used for initializing primers. If `init.algo` is "naive", then primers are constructed from substrings of the input template sequences. If `init.algo` is "tree", phylogenetic trees are used to form degenerate primers whose degeneracy is bounded by `max.degen`. This option requires an installation of MAFFT (see notes). The default `init.algo` is "naive".
`max.degen`	The maximal degeneracy of primer candidates. This setting is particularly relevant when `init.algo` is set to "tree". The default setting is `16`, which means that at most 4 maximally degenerate positions are allowed per primer.
`conservation`	Restrict the percentile of considered regions according to their conservation. Only applicable for the tree-based primer initialization. At the default of 1, all available binding regions are considered.
`updateProgress`	Shiny progress callback function. The default is `NULL` such that no progress is logged.
`settings`	A `DesignSettings` object specifying the constraint settings for designing primers.
`opti.algo`	The algorithm to be used for solving the primer set covering problem. If `opti.algo` is "Greedy" a greedy algorithm is used to solve the set cover problem. If `opti.algo` is "ILP" an integer linear programming formulation is used. The default `opti.algo` is "Greedy".
`timeout`	Timeout in seconds. Only applicable when `opti.algo` is "ILP". The default is `Inf`, which does not limit the runtime.
`sample.name`	An identifier for the primer design task. The default setting is `NULL`, which means that the run identifier provided in `template.df` is used.
`cur.results.loc`	Directory for storing the results of the primer design procedure. The default setting is `NULL` such that no output is stored.
`primer.df`	An optional `Primers` object. If an evaluated `primer.df` is provided, the primer design procedure only optimizes `primer.df` and does not perform the initialization and filtering steps. The default is `NULL` such that primers are initialized and filtered from scratch.

classify_design_problem determines the difficulty of a primer design task by estimating the distribution of coverage ratios per primer by performing exact string matching with primers of length primer.length, which are constructed by extracting template subsequences. Next, a beta distribution is fitted to the estimated coverage distribution, which is then compare to reference distributions representing primer design problems of different difficulties via the total variance distance. The difficulty of the input primer design problem is found by selecting the class of the reference distributions that has the smallest distance to the estimated coverage distribution. An estimate of the required number of primers to reach a given required.cvg can be computed by setting primer.estimate to TRUE. Since this estimate is based solely on perfect matching primers, the number of primers that would actually be required is typically less.

The primer design algorithm used by design_primers consists of three steps: primer initialization, filtering, and optimization. The method for initializing a set of candidate primers is determined via init.algo. If init.algo is set to naive, primers are created by extracting substrings from all input template sequences. If init.algo is set to tree, degenerate primers are created by merging similar subsequences by forming their consensus sequence up to a degeneracy of at most max.degen. The tree-based initialization is recommended for related sequences.

The candidate primer set is filtered according to the constraints specified in the settings object. In some cases, it is necessary to relax the constraints in order to reach the desired required.cvg. In these cases, primers that fail the input constraints may be selected. If you would like to skip the initialization and filtering stages, you can provide an evaluated Primers object via primer.df.

Optimizing a primer set entails finding the smallest subset of primers maximizing the coverage, which is done by solving the set cover problem. If melting temperature differences are a constraint, the optimization procedure automatically samples ranges of melting temperatures to find optimal sets for all possible temperatures. You can select the used optimization algorithm via optia.algo, where you can set "Greedy" for a greedy algorithm or "ILP for an integer linear program formulation (ILP). While the worst-case runtime of the greedy algorithm is shorter than the worst-case runtime of the ILP, the greedy solution may yield larger primer sets than the ILP solution.

classify_design_problem returns a list with the following fields:

Classification: The estimated difficulty of the primer design task.
Class-Distances: The total variance distance of the fitted beta distribution to the reference distribution.
Confidence: The confidence in the estimate of the design tasks' difficulty as based on the class distances.
Uncertain: Whether the classification is highly uncertain, that is low-confidence.
Nbr_primers_fw and Nbr_primers_rev: The respective number of required forward and reverse primers if primer.estimate was set to TRUE.

get_initial_primers returns a data frame with candidate primers for optimization.

design_primers returns a list with the following fields:

opti:: A Primers object providing the designed primer set.
used_constraints:: A list with DesignSettings objects for each primer direction providing the (possibly relaxed) constraints used for designing the optimal primers.
all_results:: A list containing objects of class Primers. Each list entry corresponds to an optimal primer set for a given melting temperature.
all_used_constraints:: A list containing DesignSettings object for each optimized set in all_results.
filtered:: A list with data providing information on the results of the filtering procedure.

Some constraints can only be computed if additional software is installed, please see the documentation of DesignSettings for more information. The usage of init.algo = "tree" requires an installation of the multiple alignment program MAFFT (http://mafft.cbrc.jp/alignment/software/).

# Classify the difficulty of a primer design task
data(Ippolito)
design.estimate <- classify_design_problem(template.df[1:30,])
# Estimate the number of required primers to amplify the first 5 templates
design.estimate.nbr <- classify_design_problem(template.df[1:5,], mode.directionality = "fw",
                         primer.length = 20, primer.estimate = TRUE)

data(Ippolito)
# Naive primer initialization
init.primers <- get_initial_primers("InitialPrimers", template.df, 
                         c(18,18), "fw", init.algo = "naive")
# Tree-based primer initialization (requires MAFFT)
## Not run: 
init.primers <- get_initial_primers("InitialPrimers", template.df, 
                         c(18,18), "fw", init.algo = "tree")

## End(Not run)

# Define PCR settings and primer criteria
data(Ippolito)
# design only with minimal set of constraints
constraints(settings)$primer_length <- c("min" = 18, "max" = 18)
constraints(settings) <- constraints(settings)[c("primer_length", "primer_coverage")]
# Design only forward primers using a greedy algorithm
optimal.primers.greedy <- design_primers(template.df[1:2,], "both", settings, init.algo = "naive")
# Usage of the tree-based initialization strategy (requires MAFFT)
## Not run: 
out.dir <- tempdir()
optimal.primers.tree <- design_primers(template.df[1:2,], "both", settings,
                         init.algo = "tree", opti.algo = "ILP",
                         max.degen = 16,
                         cur.results.loc = out.dir)

## End(Not run)