PRIMERVIEW 4.0.0

PRIMERVIEW designs PCR primer pairs with primer3_core and creates clear, scalable maps showing where each primer binds to every FASTA sequence.

Version 4 is a substantial reliability update. It uses Primer3's structured Boulder-IO output, produces SVG graphics directly, and no longer requires BioPerl or MUSCLE.

Features

• Multi-record FASTA input
• Primer3 Boulder-IO integration
• One combined primer map per sequence
• One detailed SVG per primer pair
• Tab-separated primer report (primers.tsv)
• Machine-readable run summary (summary.json)
• Safe handling of spaces and special characters in paths
• Collision-safe output names for duplicate or unusual FASTA identifiers
• Temporary files isolated in the selected output directory
• No shell command construction and no wildcard deletion

Requirements

• Perl 5.14 or newer
• primer3_core available in PATH, or supplied with --primer3

PRIMERVIEW now uses only Perl core modules. MUSCLE and BioPerl are not required.

Installation

perl Makefile.PL
make
make test
make install

A local installation can be used without administrator access:

perl Makefile.PL INSTALL_BASE="$HOME/perl5"
make
make test
make install

Install Primer3 separately through your operating system or environment package manager, then verify that the executable is available:

command -v primer3_core

Command-line usage

primerview \
  --input sample_input/test_seqs.fasta \
  --output-dir primerview_output

Useful options:

--primer3 PATH          Path to primer3_core
--num-return N          Number of primer pairs requested (default: 5)
--[no-]single-view      Enable/disable one SVG per pair
--[no-]batch-view       Enable/disable one combined SVG per sequence
--[no-]clean-up         Remove/retain raw Primer3 temporary files
--setting TAG=VALUE     Pass an additional Primer3 setting; repeat as needed

Example with custom Primer3 settings:

primerview \
  --input sample_input/test_seqs.fasta \
  --output-dir results \
  --num-return 10 \
  --setting PRIMER_PRODUCT_SIZE_RANGE=150-500 \
  --setting PRIMER_OPT_SIZE=22

PRIMERVIEW fixes PRIMER_FIRST_BASE_INDEX=0 internally so that reported and plotted coordinates are converted consistently to 1-based inclusive coordinates.

Perl API

use strict;
use warnings;
use PRIMERVIEW;

my $app = PRIMERVIEW->new(
    primer3_path => 'primer3_core',
    output_dir   => 'primerview_output',
    num_return   => 5,
    primer3_settings => {
        PRIMER_PRODUCT_SIZE_RANGE => '150-500',
    },
);

$app->load_selections(
    in_file     => 'sample_input/test_seqs.fasta',
    single_view => 1,
    batch_view  => 1,
    clean_up    => 1,
);

my $summary = $app->run_primerview;
print "Processed ", scalar @{ $summary->{records} }, " sequences\n";

Output

For a FASTA record named gene1, PRIMERVIEW can create:

gene1.primers.svg      Combined view of all returned pairs
gene1.pair_01.svg      Detailed view of pair 1
gene1.pair_02.svg      Detailed view of pair 2
primers.tsv             All primer sequences, positions, Tm, GC%, and penalties
summary.json            Run metadata, files, Primer3 explanations, and pair data

If Primer3 returns no acceptable pairs, PRIMERVIEW still creates the combined SVG and includes Primer3's explanation rather than failing or producing an empty graphic.

Testing

make test

The automated suite covers FASTA parsing, validation, Boulder-IO parsing, left/right coordinate conversion, command failures, path safety, duplicate IDs, SVG/TSV/JSON output, no-primer results, and cleanup isolation. Tests use a deterministic mock executable and therefore do not require Primer3 itself.

Safety note

Older PRIMERVIEW releases warned that cleanup could delete .fa and alignment files from the current directory. Version 4 does not do this. Cleanup is restricted to the unique temporary directory created for the current run.

License

GNU General Public License, version 2.