Amplicon Analyzer User Guide

Amplicon Analyzer converts amplicon FASTQ files into QC summaries, mutation calls, heatmaps, allele tables, and report files.

Quick Start

Open the analyzer.
Enter the site name and full reference amplicon sequence.
Select Custom, Cas / CRISPR, or TALE / TALEN setup and exact target positions.
Add FASTQ files or choose a folder.
Review the preflight summary.
Run the analysis.
Export CSV, JSON, SVG, PNG, Markdown, or HTML results.

Inputs

Input	Description
`.fastq`, `.fq`	Plain FASTQ files.
`.fastq.gz`, `.fq.gz`	Gzip-compressed FASTQ files.
`.fastjoin`, `.fastqjoin`, `.fqjoin`, `.join`, `.txt`	Joined FASTQ-style text files.
Site name	Label used in figures, reports, and site-specific filenames.
Reference amplicon	Full expected PCR amplicon sequence.
Setting CSV	Optional run configuration.

R1/R2 filenames are grouped by inferred sample name. Raw pairs are converted to overlap-consensus reads when a high-confidence overlap is found. Unjoined pairs remain visible in QC exports.

If joined and raw files are provided for the same sample, joined files are used for that sample.

Read limit per sample is optional. Leave it blank, or enter 0, to process every read. Numeric limits are intended only for quick validation runs because read counts and allele frequencies are then calculated from the limited subset.

Target Setup

Mode	Target handling
Custom	Uses the 1-based target positions entered in the app.
Cas / CRISPR	Finds the spacer, checks the PAM pattern when available, and maps the spacer window to amplicon coordinates.
TALE / TALEN	Finds left and right TALE binding sites and annotates the intervening spacer as a targetable region.
Prime Editor	Separates intended edits from unwanted edits using an edited amplicon sequence, intended edit list, and optional ignore regions.

The reference is the full alignment target. Exact target bases are taken from the target-position field. TALE / TALEN spacer annotations are shown separately from exact target bases.

Setting CSV

The app can export a template with one row per amplicon site:

site_name,reference_amplicon_sequence,target_positions,assay_type,spacer_sequence,pam_sequence,spacer_window,tale_left_sequence,tale_right_sequence,tale_spacer_sequence,tale_padding,prime_edited_amplicon_sequence,prime_intended_edits,prime_ignore_regions,expected_edit,sample_start,sample_end,expected_sample_count,preferred_input,notes

Blank fields are ignored. Filled PAM fields infer Cas / CRISPR. TALE binding-site fields infer TALE / TALEN. Prime Editor fields infer Prime Editor mode. Target positions alone use Custom mode.

Prime Editor intended edits can be supplied as a full edited amplicon sequence or a compact list such as C45T,52insA,del61. Ignore regions remain in raw output but are excluded from Prime Editor unwanted edit signal.

Multi-Site Analysis

Add extra rows in Additional sites:

site_B, ACGTACGT..., 16-23
site_C, ACGTACGT..., 12,18,22

FASTQ files are parsed once per sample group, then each site reference is aligned and summarized separately.

Exports

File	Contents
`processed_mutation_table.csv`	Position-level mutation counts, intended/unwanted edit counts, and edit rates.
`target_window_table.csv`	Target-window rows from the mutation table, including Prime Editor intended/unwanted columns.
`substitution_matrix.csv`	Reference-to-observed substitution counts.
`allele_spectrum_table.csv`	Unique allele sequences and edit signatures.
`allele_report_<site>_<sample>.svg`	Publication-style allele spectrum report for the selected sample.
`allele_spectrum_<site>_<sample>.csv`	Allele spectrum CSV for the selected sample.
`qc_read_counts.csv`	Filtering, alignment, and paired-end join summary.
`amplicon_run_summary.json`	Run settings and top-level summaries.
`amplicon_mutation_heatmap.svg`	Editable vector heatmap.
`amplicon_mutation_heatmap.png`	Full heatmap PNG.
`amplicon_mutation_heatmap_visible.png`	Current heatmap viewport PNG.
`amplicon_run_report.md`	Markdown run report.
`amplicon_run_report.html`	Self-contained HTML report.

Calculation

edit percentage = selected signal reads at position / position-level covered reads * 100

Coordinates are 1-based amplicon positions. Reads below the minimum alignment identity are excluded from mutation calling.

Prime Editor unwanted signal excludes edits matching the intended edit set and edits inside the configured ignore regions. Raw substitution, insertion, and deletion counts remain available in the processed table.

When an expected base edit is selected, expected-edit percentages are calculated only across editable bases inside the current target positions. Changing target positions changes this target-specific summary by design; whole-amplicon QC and alignment counts do not depend on the target window.

Validation

node tools/amplicon-analyzer-benchmark.mjs benchmarks/public/crispresso2_base_editor/config.json
node tools/validate-paired-end.mjs

The first command runs the public FASTQ benchmark. The second checks raw R1/R2 analysis against a matched joined FASTQ fixture.