virtualPCR

In silico PCR for simple and complex tasks

---

Table of Contents

• Overview
• What Changed
• Citation
• Requirements
• Installation
• Quick Start
• Configuration File
• Option Reference
• Input Formats
• Output
• Examples
• Troubleshooting
• License
• Author & Contact

---

Overview

virtualPCR is a versatile tool for in silico PCR analysis, designed to ensure primer/probe specificity across a wide range of applications. It enables researchers to predict primer/probe binding sites, assess mismatch tolerance, evaluate DNA duplex stability, and perform genome-wide searches.

Applications

• Gene discovery via homology analysis
• Molecular diagnostics and primer validation
• Genome profiling and repeat sequence identification
• CRISPR-Cas gRNA target evaluation
• miRNA and probe specificity testing

Key Capabilities

• Genome-wide primer/probe specificity analysis
• Linear and circular DNA support (plasmids, mitochondria, plastids)
• Linked search mode for complex primer arrangements
• Degenerate nucleotides (IUPAC), LNA, and inosine support
• Batch file processing and automation

---

What Changed

Reports produced by this version are not directly comparable with those from earlier ones. The differences that matter scientifically:

Change	Effect on your results
Melting-temperature formula	A length-dependent divalent-cation term was computed in integer arithmetic and was therefore always zero. With it restored, every reported Tm and Ta is about 1 °C lower than before. Binding sites and products are unaffected.
Sites at the start of a sequence	A binding site beginning at position 1 of a sequence was scored short and could be rejected. Such sites are now found — relevant mainly for multi-entry FASTA files.
Overlapping repeats of one primer	When two sites of the same primer overlapped, the nearer one could suppress the other entirely, before any alignment. Both are now reported.
Circular templates	Amplicons spanning the origin were reported one base short; their coordinates were clipped to the ends of the molecule instead of wrapping; and a primer pair that already had a valid product could also emit a spurious product running the whole way round. All three are corrected.
Circular templates shorter than 23 nt	Previously aborted the run with an error.
Order of blocks in the report	The internal sort key was not a total order. Fixing it changes the order in which sites and products appear. The set of results is unchanged.
CTconversion removed	The option was documented and parsed but never implemented — no conversion was ever applied. It has been removed rather than left misleading; a configuration containing it now prints a warning.

Configuration files are read more strictly and more helpfully — see Configuration File. Large runs are also considerably faster and use less memory, but produce identical output.

---

Citation

If you use virtualPCR in your work, please cite:

Kalendar R, Shevtsov A, Otarbay Z, Ismailova A. (2024). In silico PCR analysis: a comprehensive bioinformatics tool for enhancing nucleic acid amplification assays. Frontiers in Bioinformatics, 4:1464197. DOI:10.3389/fbinf.2024.1464197

---

Requirements

Requirement	Details
Java	Version 26 or higher
OS	Windows, Linux, or macOS
RAM	Default JVM heap is sufficient for most tasks; increase for whole-genome analyses (see Large Genomes)

• Download Java: https://www.oracle.com/java/technologies/downloads/
• Set Java Path: https://www.java.com/en/download/help/path.html

---

Installation

Option 1: Direct Download

1. Download virtualPCR.jar from the dist directory of this repository.
2. Place it in your preferred location.
3. Ensure Java 26+ is installed and available in your PATH.

Verify Java is available:

java -version

Option 2: Install Java via Conda

# Add conda-forge channel and set priority
conda config --add channels conda-forge
conda config --set channel_priority strict

# Create environment with OpenJDK 26
conda create -n java26 openjdk=26

# Activate environment
conda activate java26

# Verify installation
java -version

Genome Downloads

Download individual chromosome FASTA files from NCBI Datasets. For example, the human genome (T2T-CHM13v2.0) is available at NCBI.

---

Quick Start

# Basic usage
java -jar virtualPCR.jar config.file

Getting Help

Run with no arguments — or with a help flag — to print usage and the full list of configuration options:

# Show help (any of these are equivalent)
java -jar virtualPCR.jar -help
java -jar virtualPCR.jar /?

Recognized help flags (case-insensitive): -help, --help, -h, --h, /help, /h, /?, -?, ?, and the bare word help. A help flag is honoured wherever it appears in the command line, and running with no arguments prints the same screen.

Large Genomes

For genome-wide analyses, allocate additional memory using JVM flags:

# Linux / macOS
java -Xms4g -Xmx16g -jar virtualPCR.jar config.file

# Windows
java -Xms4g -Xmx16g -jar C:\virtualPCR\dist\virtualPCR.jar C:\virtualPCR\test\config.file

• -Xms — initial heap size (memory allocated at startup)
• -Xmx — maximum heap size (upper memory limit)

Increase -Xmx if you see OutOfMemoryError. A good rule of thumb for vertebrate genomes is -Xmx16g or higher.

---

Configuration File

All parameters are specified in a plain-text configuration file (e.g., config.file), one key=value per line. Boolean options accept true or false.

# --- Paths ---
targets_path=C:\virtualPCR\test\ch02.fasta
primers_path=C:\virtualPCR\test\rt.txt
output_path=

# --- Search mode ---
type=primer
molecular=linear
linkedsearch=false
FRpairs=false

# --- Filters ---
minlen=200
maxlen=500
number3errors=1

# --- Output control ---
primerstatistic=true
SequenceExtract=true
flanks=100
ShowPrimerAlignment=true
ShowPCRProducts=true
ShowOnlyAmplicons=false
ShowPrimerAlignmentPCRproduct=false

How lines are read. Each line is split at its first =. The key is matched exactly (case-insensitive, so linkedsearch and LinkedSearch are equivalent), and surrounding spaces are ignored — minlen = 200 works. Values keep their original case, which matters for paths.

• # starts a comment where it cannot be part of a value: before the =, or preceded by a space. So # minlen=200 is ignored, and minlen=200 # note reads as 200. A # inside a path is left alone.
• Unrecognised keys are reported, not silently skipped: a typo such as min_len=100 prints Warning: unknown option ignored: min_len=100 and the run continues on defaults for that setting.
• Values that are not plain numbers are reported too. maxlen=2,000 prints a note showing it was read as 2, rather than failing silently.
• Every recognised option is echoed to the console, which remains the quickest way to confirm what was applied.

⚠️ Earlier versions had none of this: # did not disable anything, spaces around = silently switched an option off, and misspelled keys were ignored without a word. If you are reusing an old configuration file, check the console echo once.

Paths

Parameter	Description
targets_path	Path to the target FASTA file, or to a directory of FASTA files.
primers_path	Path to the primer/probe file (FASTA or tab/space-delimited).
output_path	Output directory. Leave empty to write results next to the input.

---

Option Reference

Summary

Option	Values	Default	Purpose
type	primer, probe	primer	Search mode
molecular	linear, circle	linear	Template topology
linkedsearch	true, false	false	Enable linked/associated search
FRpairs	true, false	false	Restrict analysis to defined F/R pairs
minlen	integer (bp)	30	Minimum amplicon length (inclusive)
maxlen	integer (bp)	3000	Maximum amplicon length (inclusive)
number3errors	integer	1	Allowed mismatches near the 3′ end
threads	integer	1	Target files processed at once (directory mode only)
primerstatistic	true, false	true	Print per-primer summary statistics
SequenceExtract	true, false	false	Extract amplicon sequences into output
flanks	integer (bp)	0	Extra template bases kept on each side of every extracted amplicon; implies SequenceExtract=true
ShowPrimerAlignment	true, false	true	Show all primer-to-target alignments
ShowPCRProducts	true, false	true	Report predicted PCR products
ShowOnlyAmplicons	true, false	false	Report amplicon lengths only (no alignments)
ShowPrimerAlignmentPCRproduct	true, false	true	Restrict alignments to those forming products

type — Search Mode

Value	Description
primer	Standard PCR primer search (default).
probe	Search for binding sites of primers, probes, and short sequences — TaqMan, Molecular Beacons, miRNA, CRISPR-Cas gRNA, microarray oligos, etc. Recommended when primer binding sites are not found, or when complementarity is expected for only part of the sequence (e.g., Molecular Beacon stems).

molecular — Template Topology

Value	Description
linear	Linear DNA (default).
circle	Circular DNA (plasmids, mitochondrial/plastid genomes). A primer pair yields one product, which may span the origin; such products are reported with wrapping coordinates (for example 2 951-120).

minlen / maxlen — Amplicon Size Filter

Defines the expected PCR product size range (in bp). Amplicons outside this range are filtered out.

• Default: minlen=30, maxlen=3000. Both bounds are inclusive; the valid range is 20–50000 bp.
• Example: minlen=200 and maxlen=500 restricts output to 200–500 bp products.
• The two are reconciled after the whole file is read, so their order in the file does not matter. If maxlen ends up below minlen, it is raised to minlen and the adjustment is printed.

threads — Parallel Batch Processing

Only affects directory mode; a single target file is unaffected. With threads=N the tool works on N target files at a time, in batches, and writes the results in file order.

• Default threads=1 — the behaviour is exactly as before.
• The value is clamped to the number of available processors.
• Output does not change. The combined report, the per-primer statistics and the console log are identical whatever threads is set to — only the Time taken: line of each file differs, since it measures wall-clock time and files now share the CPU.
• Memory scales with it. Every file being worked on holds its whole template and its whole report. In one measurement — four targets producing 57 MB reports each — threads=1 completed in 200 MB of heap while threads=4 needed 400 MB. Raise -Xmx along with threads, or lower threads.
• Speed-up is bounded by disk and by the serial write: on eight large targets across four cores, wall time fell by roughly a quarter to a third.

targets_path=genomes/
primers_path=primers/its.txt
threads=4

If a file runs out of memory the whole run stops with a non-zero exit code rather than skipping that file — a truncated report must not look like a successful one. Lower threads or raise -Xmx and re-run.

number3errors — 3′ Mismatch Tolerance

Maximum number of mismatches allowed within the 3′ region of each primer. Lower values give stricter (PCR-realistic) specificity; higher values broaden the search.

FRpairs — Restrict to Defined Primer Pairs

When true, only the explicitly defined forward/reverse primer pairs are analyzed (no cross-pairing). Each line in the primer file defines one pair:

1020	aggcctgtgatgctgatgat	cccaacaccaaagaggaaag
1021	gctctgacctattgtctgtctgtct	cagtctccacagcagcagag
1022	gtcctgctgacacacaccact	cgcaggagtagaagaaaga

A single forward primer can be paired with multiple reverse primers (and vice versa) by listing additional columns on the same line.

linkedsearch — Linked/Associated Search

A programmable search mode that locates binding sites for linked sequences within a specified distance. Supports tasks ranging from conventional sequence matching to in silico PCR with approximate matching.

Syntax: the first sequence is followed by the expected distance [min-max] and the second sequence:

>RT+(QMDVK)_RT-(YVDDML)
CARATGGAYGTNAARAC[200-300]TAYGTNGAYGAYATG

The header RT+(QMDVK)_RT-(YVDDML) references conserved reverse-transcriptase protein motifs (QMDVK and YVDDML) used to derive the degenerate nucleotide primers.

Variants:

# Fixed distance (no range)
CARATGGAYGTNAARAC[300]TAYGTNGAYGAYATG

# Force the second sequence to be reverse-complemented (@ prefix)
CARATGGAYGTNAARAC[300]@CATRTCRTCNACRTA

Rules:

• Each element of the pattern must be at least 12 nt; shorter fragments are ignored.
• @ marks the element it belongs to for reverse-complementing. It is recognised anywhere inside that element, not only at the front, so keep it at the start to avoid surprises.
• Any number of elements may be chained: seq1[1-100]seq2[1-50]seq3.

Output-control Options

Option	Effect when true
primerstatistic	Prints a per-primer table (ID, sequence, binding-site hit count) sorted by frequency, plus a consolidated cross-file table and a companion *.stats.tsv file — see Output.
SequenceExtract	Writes extracted amplicon sequences into the output file.
flanks=N	Keeps N additional template bases on each side of every extracted amplicon, in lower case, with the amplicon itself in upper case. Setting it turns SequenceExtract on automatically. On a circular template the flanks wrap around the origin and are trimmed so they cannot run into the amplicon from the other side.
ShowPrimerAlignment	Displays all stable primer-to-target alignments, including binding sites that may not produce PCR products. Useful for examining site stability, orientation, and coordinates.
ShowPCRProducts	Outputs predicted PCR products. Set to false to report binding sites only, without amplicon prediction.
ShowOnlyAmplicons	Outputs only amplicon lengths without detailed alignment analysis. Recommended for genome-wide in silico PCR with highly abundant repeat-based markers (iPBS, IRAP, ISSR, RAPD).
ShowPrimerAlignmentPCRproduct	Restricts alignment output to only those primer binding sites that contribute to predicted PCR products. This is the default; set it to false to keep every stable alignment in the report, including sites that form no product.

---

Input Formats

Target Sequences

Targets must be in FASTA — single-entry or multi-entry. Every entry must begin with a > header line; a file containing bare sequence with no header is rejected with a message saying so. No specific file extension is required, and template length is not limited (other than by available memory).

FASTA format consists of a header line starting with > followed by one or more lines of sequence:

>sequence_id Optional description
ATCGATCGATCGATCGATCG...

Primer/Probe Files

Primers can be provided in tab-delimited, space-delimited, or FASTA format. In delimited formats the first column is the primer ID and all subsequent columns are sequences belonging to that ID (one or more).

Two-column tab-delimited:

ITS1	TCCGTAGGTGAACCTGCGG
ITS2	GCTGCGTTCTTCATCGATGC
ITS3	GCATCGATGAAGAACGCAGC
ITS4	TCCTCCGCTTATTGATATGC

Multi-column tab-delimited (e.g. defined F/R pairs for use with FRpairs=true):

1020	aggcctgtgatgctgatgat	cccaacaccaaagaggaaag
1021	gctctgacctattgtctgtctgtct	cagtctccacagcagcagag
1022	gtcctgctgacacacaccact	cgcaggagtagaagaaaga

FASTA:

>ITS1
TCCGTAGGTGAACCTGCGG
>ITS2
GCTGCGTTCTTCATCGATGC
>ITS3
GCATCGATGAAGAACGCAGC
>ITS4
TCCTCCGCTTATTGATATGC

Rules:

• Primer names may contain any characters, including spaces. Names need not be unique.
• Sequences must not contain spaces or non-nucleotide characters.
• Sequences shorter than 12 nt are skipped.
• File format (FASTA, tab, or space) is auto-detected.
• The file is read as UTF-8, falling back to an 8-bit encoding (Windows-1251, Latin-1) if that fails, so a hand-edited list with non-ASCII identifiers still loads. Non-ASCII identifiers in an 8-bit file may appear garbled in the report; the sequences themselves are unaffected.

Supported Nucleotide Codes

Code	Bases
A	Adenine
C	Cytosine
G	Guanine
T	Thymine
U	Uracil (read as T)
I	Inosine (read as G)
R	A / G
Y	C / T
M	A / C
K	G / T
S	G / C
W	A / T
B	C / G / T
D	A / G / T
H	A / C / T
V	A / G / C
N	A / G / C / T

LNA (Locked Nucleic Acid) codes: dA = E, dC = F, dG = J, dT = L

---

Output

Results are saved as tab-delimited, UTF-8 plain-text files, containing (depending on options enabled):

• Primer binding-site coordinates and orientations
• Primer-target alignment details and mismatch analysis
• Predicted PCR product sizes
• Extracted amplicon sequences
• Per-primer summary statistics (when primerstatistic=true)

When a directory of target files is processed, all per-file reports are written to a single combined output file, followed by the global statistics described below.

The console shows progress and, for a single target, the first 8 KB of the report; the full text always goes to the output file, whose path is printed when the run finishes.

Per-primer statistics

With primerstatistic=true, each report ends with a per-primer table sorted by hit count (PrimerID, Sequence, Hits), followed by a consolidated global table that sums each primer's occurrence across every analyzed sequence and file:

Column	Meaning
Hits	Total binding sites found
Sequences	Number of sequences in which the primer occurs
Files	Number of files in which the primer occurs

When a directory of targets is processed, this table aggregates the whole batch. It is written both at the end of the main report and to a separate companion <report>.stats.tsv file (tab-separated, UTF-8) for direct import into spreadsheets or R.

---

Examples

1. Standard primer screen against a chromosome

targets_path=test/ch02.fasta
primers_path=test/its.txt
type=primer
molecular=linear
minlen=100
maxlen=2000
number3errors=1
ShowPrimerAlignment=true
ShowPCRProducts=true

2. Genome-wide repeat-marker scan (iPBS / IRAP / ISSR)

targets_path=genome/chm13v2.fasta
primers_path=primers/ipbs.txt
type=primer
maxlen=5000
ShowOnlyAmplicons=true

Run with extra memory:

java -Xms4g -Xmx32g -jar virtualPCR.jar config.file

3. Probe / gRNA specificity check

targets_path=genome/hg38.fasta
primers_path=probes/grna.fasta
type=probe
ShowPCRProducts=false
ShowPrimerAlignment=true

4. Amplicons with flanking regions extracted

targets_path=test/plasmid.fasta
primers_path=test/pr.txt
type=primer
molecular=circle
minlen=100
maxlen=3000
SequenceExtract=true
flanks=100

Each extracted record carries 100 template bases on either side of the amplicon, in lower case, with the amplicon in upper case.

---

Troubleshooting

Symptom	Likely cause / fix
UnsupportedClassVersionError	Java version is older than 26 — the JAR is compiled for class-file version 70. Install Java 26+ and verify with java -version.
OutOfMemoryError	Increase JVM heap with -Xmx, e.g. -Xmx16g. If you set threads above 1, each file in flight needs its own memory — lower it or raise -Xmx in proportion.
No products reported	Try type=probe, increase number3errors, or widen minlen/maxlen.
Too many products on a genome	Tighten number3errors, narrow the amplicon size window, or switch to ShowOnlyAmplicons=true for compact output.
No usable primers in ...	The file opened but nothing in it parsed as ID + sequence. Ensure sequences are ≥ 12 nt and that ID and sequence are separated by a tab or space.
No '>' header line found in ...	The target is not FASTA. Add a > header line above the sequence.
Warning: unknown option ignored: ...	The key is misspelled or no longer exists (for example CTconversion). Fix or delete the line — that setting is running on its default.
An option in the file seems to have no effect	Check the console echo: every recognised option is printed back. If yours is missing, it was not recognised.
Not sure which options exist	Run java -jar virtualPCR.jar -help (or with no arguments) to print usage and all configuration options.

---

License

Released under the GNU General Public License v3.0. See LICENSE.txt for the full text.

---

Author & Contact

Ruslan Kalendar 📧 ruslan.kalendar@helsinki.fi

Online version: https://primerdigital.com/tools/epcr.html