The openPrimeR Shiny user interface

Matthias Döring

2023-04-25

openPrimeRui provides a Shiny application for the openPrimeR package, which offers functionalities for designing and analyzing multiplex polymerase chain reaction (PCR) primer sets. In the following, we illustrate how to navigate the user-interface for three application scenarios: evaluating a primer set, comparing primer sets, and designing novel primer sets.

Preliminaries

Since openPrimeRui provides a user-interface for the functionalities of the openPrimeR package, openPrimeR is automatically installed when openPrimeRui is installed. Note, however, that openPrimeR requires external tools for some of its functionalities; you can learn more about the dependencies in the package’s vignette.

In case that external tools are missing, the Shiny application automatically creates a pop-up informing you about any missing dependencies. Rows in the table with blue-colored cells indicate installed external tools, while red-colored cells indicate dependencies that are not available. Each row in the table is annotated with the functionality that is provided by the corresponding dependency such that it is easy to see, which features are not available in case of missing dependencies.

Overview of installed third-party tools. In this case, all required tools are installed as indicated by the blue background colors.

Starting the Shiny app

openPrimeRui exports only a single function, startApp(), which is used to open the shiny application:

library(openPrimeR)
if (interactive()) {
    startApp()
}

After calling startApp(), the Shiny application should open as a new tab in your default browser. If this is not the case, please consider the console output and manually open the displayed URL (a certain port on localhost) in your preferred web browser.

Overview of the user-interface

The user interface of the app is based on a two-column layout. The shaded panel on the left hand side is intended for performing actions such as loading data and performing analyses, while the right hand side shows information on the loaded data and the analysis results. Therefore, in the following we will refer to these two panels as the action panel and view panel, respectively.

Overview of the user interface. The action panel (grey background) is on the left-hand side of the screen, while the larger view panel is on the right-hand side of the screen.

General navigation is possible through the symbols shown in the top-right corner of the screen, where three icons are shown: the factory icon, the refresh icon, and the power-off icon. With the factory icon, you can open the overview of third-party tools, which is shown at startup if there are missing dependencies. Using the refresh icon, you can reset the current session and clicking on the power-off button closes the application.

The navigation buttons shown in the top-right of the screen: the factory, refresh, and power-off button.

To the right of the openPrimeR logo and above the view panel, there are two navigation selectors.

The navigation selectors determining the analysis mode and the currently selected type of primer set.

The selector on the left side is used to select the analysis mode of the tool, while the selector on the right side determines the data that are shown. With the analysis selector, you can select one of three modes of analysis:

By default, the evaluation mode is selected. For the set selector, there are also three possible choices, which determine the data you are currently viewing:

By default, all of the loaded data are displayed. The set selector can be a useful tool to compare the properties of a primer set before and after filtering. When using the data selector, note that only available data can be shown. For example, information on a filtered set of primers can only be shown after a filtering operation has been performed. In many cases, it is not necessary to manually change the selected data set because operations such as filtering an designing primers will automatically select the corresponding data sets.

Next, let us take a look at how you can navigate through the tool when conducting an analysis, starting with the action panel. Independent of the type of analysis, the action panel takes you through a sequence of four steps, which are indicated by the elements at the top of the panel:

The four stages for performing an analysis

We require that each navigation step is performed in the displayed sequence. For example, in the first stage, you are required to upload the template sequences and you can only go to the second step (the primers stage) after you have provided the templates. Before providing more detail on the individual steps along the analysis sequence, let us take a look at the view panel.

In contrast to the action panel, the view panel can be navigated freely without any restrictions on the order in which elements must be selected. The view panel has the following elements:

The navigation elements of the view panel

At any point in time during an analysis, you can use the view navigation panel to retrieve the results you are interested in. For example, after you have determined the coverage of the templates, you can select the coverage tab to view information on the coverage.

With this, we have covered the core elements of the user interface, which do not change dynamically. We will now move on to the required steps for each analysis mode. Note that, in the following, we will not cover all available elements of the user interface due to the complexity of the tool.

Templates

All analyses start with the upload of a set of templates. You can either load one of the supplied sets of templates or you can provide your own template sequences. You can select your choice via the the template source selector:

The template source selector

Loading supplied template sequences

If you are loading a supplied set of templates, you can simply specify the type of template sequences to load. For example, to load immunological template sequences, you can select Immunology in the template type selector and then select the species, locus, and function of the immunoglobulin sequences you would like to retrieve with the Retrieve templates button.

Input of supplied immunological templates

Loading personal template sequences

Loading personal templates is possible in two ways: by supplying a FASTA file containing the template sequences or by loading a CSV file containing a set of templates that was loaded via openPrimeR. For FASTA input, it may be beneficial to load the metadata encoded in the FASTA headers. In particular, if you want to interpret the analysis results with respect to groupings of the templates, you should make sure that you specify how information on the template grouping is encoded in the FASTA headers. For this, the GROUP field should be defined correctly.

For a better understanding, let’s consider the following FASTA header:

>K03455_SubtypeB_HIV-1

This sample has a header structure consisting of ACCESSION, GROUP, and SPECIES, where each field is delimited by an underscore (_). Hence, you would define the following header structure in the tool such that the metadata can be loaded correctly:

Defining the structure of the FASTA header

Having defined the header structure, you can upload the templates via the template file selector:

The template file selector

Defining the target binding regions

Having provided a set of template, you should define the target binding regions of the primers in the templates. This is done through the Allowed regions panel. Here, you can either provide template-specific binding regions or uniform binding ranges. To define individual template binding regions, you can supply FASTA files providing the binding regions for forward and reverse primers, respectively. When providing the files, please ensure that the headers of the FASTA files match the headers of the templates and that the provided sequences are subsequences of the templates.

Specifying individual binding regions

Uniform binding ranges are specified in the form of intervals relative to the 5’ end for forward primers and relative to the 3’ end for reverse primers. For example, a forward binding interval of [1,30] indicates the the forward primers should bind to the first 30 bases of the templates, while a reverse binding interval of [1,40] indicates the the reverse primers should bind in the last 40 bases of the templates. Your adjustments come into effect when the Update binding regions button is pressed.

Specifying uniform binding ranges

Loading templates for comparison

For comparing primer sets, the input of templates is slightly different to the other modes. Again, you can choose to either load supplied or personal templates. This time, however, the template sequences have to be provided as CSV files representing sets of templates that have been previously loaded by openPrimeR. This ensure that the binding regions are already defined. You can obtain a CSV file for a set of loaded template sequences using the download tab by selecting Templates as the data set, selecting the Raw output format, and then clicking on the Download button.

Downloading template sequences

If you should ever need to, you can also download the templates in FASTA format, by switching from Raw to the Formatted output in the download panel.

With regard to comparing primer sets, the input of the templates is dependent on whether you would like to compare primer sets targeting the same templates or different sets of templates. If all the primer sets relate to the same set of templates, then it is sufficient to provide a single template set for all primers. If, however, the primer sets relate to different template sets, you should provide one set of templates for every set of primers you would like to consider.

The templates tab

After you have uploaded a set of templates in the evaluation/design modes, you can use the templates tab that the correct data haven been loaded. Apart from the basic information on the templates such as their identifiers and sequences, you can also find annotations of the target binding regions. For example, the columns Allowed Binding Range (fw) and Allowed Binding Range (rev) provide the defined binding ranges of forward and reverse primers, respectively. You can view additional information on the templates by clicking on the green + icon. Note that the templates table is annotated with information on the coverage, once an analysis has been performed.

Excerpt of the templates table

Primers

The content of the primers panel considerably depends on the analysis mode. Hence, we will cover the contents of the primers panel for every analysis mode individually.

Primers: evaluation

If you choose to load a supplied set of primers, you can either load the primers in their evaluated form (i.e. annotated with analysis results) or in their raw form. Analogously, you can provide your own sets of primers either in FASTA format (raw) or in CSV format (evaluated) if you have already evaluated the primer set previously and would like to review the results.

When you choose to upload the set of primers as a CSV file, which was stored using the app’s download panel, you do not need to provide any additional inputs. For FASTA input, on the other hand, you should define identifiers for the directionalities of the primers beforee uploading a file. In the following screenshot, the annotation means that all forward primers contain the keyword *_fw* in their FASTA headers, while all reverse primers contain the keyword *_rev* in their headers. Pairs of primers can be identified by providing two oligomers whose headers match when removing the directionality keywords.

When providing a FASTA file as the input, you can also specify how IUPAC how ambiguities in the primers are to be treated. By default, ambiguous IUPAC bases are loaded as they are, but you can also choose to merge primers using ambiguous bases or disambiguate the input oligomers, if possible.

Upload of personal primers

After uploading a set of primers , information on the primers is shown in the primers tab.

The primers tab

The primers tab shows all information pertaining to the loaded primers. The directionalities of the primers are color-coded such that forward primers, reverse primers, and pairs of primers can be distinguished easily.

The Coverage mode indicator, which is found in the bottom-right corner of the screen, shows how the coverage of the templates is computed. If primers of both directionalities (forward and reverse) are provided, the coverage mode is both meaning that a template is considered to be covered if there is at least one forward and at least one reverse primer covering the template. Otherwise, if only primers of a single directionality (either only forward or reverse primers) are provided, a single primer covering a template is sufficient.

Once the coverage of the primers has been computed, you can switch between viewing the coverage for groups of template and viewing the coverage of individual templates via the Show individual primer coverage selector. More information on the primers can be retrieved by clicking on the green + in front of each row in the table.

The primers tab

Primers: design

When designing primers, the primers panel is used to specify the desired properties of the primers. The two most important considerations are the following:

Specifying the primer properties for primer design. In this example, degenerate primers of both directionalities will be designed.

Primers: comparison

Primer sets for comparison can be supplied only in their evaluated form in terms of a CSV file. You can load several sets of primers by either successively loading individual CSV files or selecting multiple CSV files at once. Once you have uploaded a set of primers, the comparison tab provides an overview of all loaded template and primer sets by providing the coverage of each set.

Overview of loaded primers and templates for comparison

As stated earlier, a single set of templates suffices in case that all primer sets relate to the same set of templates. Otherwise, there should be a one-to-one mapping between primer sets and sets of templates.

Settings

Having supplied both templates and primers, the next step is the definition of the analysis settings. These settings define which primer properties are considered and how they are computed. The first choice you have to make is whether you want to load one of the provided default analysis settings or whether you would like to load your personal settings.

Loading the analysis settings

Personal settings can be provided as XML files, which can be retrieved using the app’s download panel. Having loaded a settings file, an overview of the currently active settings is shown in the settings tab (view panel).

Coverage conditions

The coverage conditions define under which circumstances a template sequence is considered to be covered by a primer. We differentiate between basic and extended coverage conditions.

Basic coverage conditions

With the basic coverage conditions you can define where the primers should bind and how many mismatches between primers and templates are allowed. By default, the allowed off-target coverage ratio is set to 100% such that the coverage of primers is evaluated across the full template sequences (i.e. independent of the annotated binding regions). To consider only coverage events in the target regions, you can set the ratio of allowed off-target binding events to 0%. Independent of this selection, the specificity of the primers is evaluated with respect to the number of primers binding the target region vs those binding in other regions.

The other important parameter is the maximal number of allowed mismatches between primers and templates. This setting limits the potential coverage events that can be detected. For example, if you set the number of allowed mismatches to 0, it is only possible to identify all binding modes where templates and primers are 100% complementary. To capture also mismatch binding events, a larger number of allowed mismatches is required. For example, if the maximal number of allowed mismatches is set to 7, according to the basic coverage conditions, all binding events with less or equal to 7 mismatches would yield valid coverage events.

The basic coverage conditions

Obviously, a coverage definition allowing for many mismatches would be problematic because it is well known that the efficiency of amplification decreases with the number of mismatches between primers and templates. Hence, when evaluating coverage with allowed mismatches, another criterion is required. This is where the extended coverage conditions come into play. The purpose of these criteria is to select only those coverage events that are likely to represent actual amplification events and to postulate further constraints on the binding modes of the primers.

Extended coverage conditions

When allowing for multiple mismatches between primers and templates it is crucial that suitable extended coverage conditions are chosen in order to call only coverage events representing actual amplification events rather than false alarms. The extended coverage conditions can be divided into two groups: conditions that are associated with the success of amplification (binding conditions) and conditions posulating additional requirements for calling coverage events(codon design). The following binding conditions are available:

Primer binding conditions

You can activate or deactivate an extended coverage condition by switching the corresponding radio button to On or Off. You can think of each binding conditions as a filter on the called coverage events. The more stringent the binding crtieria are, the fewer false positive coverage events are called, however, at the risk of also discarding some actual amplification events.

For example, the free energy of annealing provides the energy that is released when a primer and a template form a duplex. Hence, the lower this energy is, the ore likely it becomes that the primer and the template are present in a duplex. By selecting a cutoff on the free energy of annealing between primers and templates, you can either more stringently select binding events (small cutoff, e.g. -10 kcal/mol) or less stringently (high cutoff, e.g. -5 kcal/mol).

Since the success of amplification also depends on the binding of the polymerase, it is important to consider terminal mismatches as well. For this purpose, you could add the 3’ Mismatches criterion (e.g. to remove coverage events exhibiting mismatches in terminal hexamers) or you could choose a model that takes into account both, the likelihoods of of binding and elongation. Amplification efficiency provides the thermodynamic model of DECIPHER, while Coverage model is based on a novel logistic regression model that estimates the false positive rate (FPR) of called coverage events. For example, at an FPR cutoff of 5%, the percentage of falsely called coverage events should be at most 5%.

The codon design options specify under which conditions mismatch binding events are allowed. For example, it is possible to exclude mismatch binding events that would introduce stop codons or other mutations into the amino acid sequence corresponding to the amplicons.

Constraints

Using the constraints panel, you can select which primer properties are computed and you can define constraints on each property, which define the desired target values for a property. The Setting column defines the desired values for every property such that a primer is considered to pass a constraint if its property values are within the specified range; otherwise the primer is considered to fail the constraint. The Limit column is important for the primer design procedure where the defined constraint ranges may be adjusted in order to reach the target coverage. Let us consider the setting for the GC clamp in the following screenshot to obtain a better understanding of such a relaxation:

Excerpt of the available constraints

Since the GC clamp target range is [1,3] and its limit is set to [0,4], the design procedure would adjust the target range from [1,3] to [0,4] in the first relaxation, from [0,4] to [0,5] in the second relaxation, and so on. Hence, the difference between the target range and its limit defines the step size during individual relaxations. You can prevent the relaxation of individual constraints in the design procedure by setting the constraint limit to the same value as the target range. Properties for which no limits can be specified are never relaxed (e.g. primer length).

PCR conditions

The PCR conditions should match the conditions under which the PCR is to be performed in the laboratory. Specifying the PCR conditions correctly is important because the thermodynamic computations that are required for some primer peropties require the concentrations of the ions that are used for PCR. If you do not specify an annealing temperature, openPrimeR will automatically select suitable annealing temperatures for evaluating the primers.

Specifying the PCR conditions

Evaluation of a set of primers

When evaluating a set of primers, the two most important functions are computing the priemr properties and filtering the set of primers.

Computing the properties of a primer set means that the primer set is evaluated according to all active constraints. Each primer is then annotated with the constraints that it passed (within the constraints) and those constraints that it failed (outside the constraints). Filtering, on the other hand, retains only those primers fulfilling all constraints; primers breaking any of the active constraints are discarded. You can switch between the results from computing the properties of the primers and filtering by selecting All data or Filtered data in the set selector, respectively.

A basic, tabular overview of the properties of the primers can be obtained from the primers tab: