User Guide

PAVI — Protein Annotation & Variant Inspector

Align protein sequences across model organisms and overlay their variants — from picking a gene to reading the alignment. This guide walks through every part of the tool, with screenshots of what you’ll see.

Alliance of Genome Resources
Alignment by Clustal Omega
Viewer built on Nightingale

Start here

What PAVI does

PAVI compares the same protein across different organisms — or several transcripts of one gene — and shows you where the sequence is conserved and where known variants land.

You give PAVI one or more genes; it retrieves the matching protein sequences, aligns them with Clustal Omega, and presents an interactive alignment with variant annotations mapped on. Everything is built from public Alliance of Genome Resources data.

Supported organisms

Human
Mouse
Rat
Zebrafish
Frog (X. tropicalis)
Fruit fly
Nematode (C. elegans)
Yeast (S. cerevisiae)

How input works

You choose sequences by searching for a gene — by symbol (e.g. SOD1) or ID (e.g. HGNC:620) — then picking its transcripts. The species comes from the gene you select. Alignments need at least two sequences.

The job lifecycle

Submit→Progress→Result

After you submit, PAVI tracks the job on a live progress page, then opens the result automatically. Every job has a unique ID, and result pages are shareable by URL — send the link and the recipient sees the same alignment.

In a hurry

Quick start

Open Submit Job
From the top navigation, choose Submit Job. New to PAVI? Click Load Example to fill the form with a ready-made dataset.
Pick a gene
Type a symbol or ID in the Gene field and select a suggestion. Add more with Add Another Gene for cross-species comparisons.
Choose transcripts
Select one or more transcripts per gene — at least two sequences total across the form.
(Optional) Add variants
Open the Alleles box to include variants; paste a full HGVS to add a specific one.
Submit and read the result
Click Submit Job, watch the progress page, and explore the alignment when it opens.

The main workflow

Submitting a job

The Submit Job page builds an alignment from one or more gene entries. Each entry has a gene, its transcripts, and optional variants.

The PAVI Submit Job page: a Create a New Alignment card explaining the three steps, a Load Example button, and one alignment entry with Gene, Transcripts, View transcripts, and Alleles controls. — **The Submit Job page.** Each row is one gene entry — Gene, Transcripts, an optional View transcripts preview, and the optional Alleles box. Use **Add Another Gene** to compare more.

Finding a gene

Type into the Gene field (placeholder e.g. HGNC:620). PAVI searches by both ID and symbol and shows suggestions as SYMBOL (species). If a search finds nothing you’ll see “Failed to find gene, correct input and try again.”

Loading an example

Click Load Example to open the dataset picker, filter by Basic / Cross-Species / Advanced, and choose a card — each shows its genes and variant count. Loading replaces whatever is in the form.

Comparing several genes

The form starts with one entry; Add Another Gene appends more — this is how you build ortholog or multi-gene comparisons. Extra entries get a remove button.

Selecting transcripts

The Transcripts box lists the gene’s transcripts; each shows the transcript name and, where available, its protein accession. Select as many as you want to align.

The View transcripts dialog titled Transcripts — Pax6, showing an interactive diagram of many isoform models drawn along a genomic position axis. — **The View transcripts dialog.** A read-only diagram of the gene’s isoforms along its genomic locus — a reference for deciding what to align. You don’t pick transcripts here; tall genes scroll inside the dialog.

Adding variants (the Alleles box)

The Alleles (optional) box adds known variants. It loads the gene’s variant-bearing alleles the first time you open it; each option shows the allele name, its ID, and the variant name or a “{n} variants” badge.

Not every variant is listed

For heavily-annotated genes, PAVI loads only about the first 100 alleles (ordered by genomic position). A variant beyond that won’t appear until you look it up by HGVS — see the next section.

Filtering the allele list

The funnel icon opens Filter alleles. Narrow by molecular consequence, impact (HIGH/MODERATE/LOW/MODIFIER), transcript, SIFT, PolyPhen, and has disease / has phenotype. Quick presets — Missense only, High impact, Disease — set these in one click; Clear resets. Selecting transcripts also auto-filters alleles to those affecting them.

Submitting

Submit Job stays disabled until every entry is valid (a gene plus at least one transcript) and you have at least two sequences. On success the job is saved to your local history and the progress page opens.

Featured task

Adding a specific variant

The Alleles box does more than browse — you can pull in an exact variant even when it isn’t in the loaded list. Typing there does three things automatically, with a live status beside the label:

The one rule

To add a specific variant, paste its full HGVS — e.g. NC_000068.8:g.105521966G>T — not just the position number.

The Alleles box with a full HGVS pasted into the filter; the status reads Added — select it below, and an option for Pax6Sey with its MGI ID and HGVS appears in the dropdown. — **Pasting a full HGVS.** PAVI resolves it directly, confirms it belongs to the gene, and adds it — here `NC_000068.8:g.105521966G>T` becomes the selectable **Pax6^Sey** allele. Tick its box to include it.

What you type	What PAVI does	Status
A full genomic HGVS `NC_000068.8:g.105521966G>T`	Looks it up directly; if it belongs to your gene, adds it as a selectable option.	Added — select it below
Other text, 3+ characters (part of an allele name)	Runs a best-effort variant search for the gene and merges matches.	{n} match(es) added / No matches
A bare position number `105521966`	Can’t be resolved alone, so PAVI prompts for the full HGVS instead of searching in vain.	Enter the full HGVS…

Where to get the HGVS

On the Alliance gene page, open “Alleles and Variants”. Copy the whole genomic HGVS, including the accession prefix and the change: NC_000068.8:g.105521966G>T.

Common pitfalls

“No match for this gene” — the HGVS belongs to a different gene, or the wrong species is selected. Confirm the gene, then paste again.

No results — you may have typed only the position number. Copy the complete HGVS (accession + change), verbatim.

Good to know

A variant you add this way stays visible and selectable even with a transcript or impact filter active — and it’s submitted just like any listed variant.

One gene, many species

Ortholog alignment

The Ortholog Alignment page is a shortcut for the most common comparison: one gene against its orthologs across model organisms — no manual transcript picking.

Pick a focus gene
Search for one gene (placeholder e.g., SOD1, TP53, PITX2). PAVI confirms symbol, species, and ID.
Review the orthologs
PAVI auto-fetches the orthologs into a checklist. The source gene is marked SOURCE; orthologs in the core Alliance species are pre-checked. Use All, AGR Species, or None to adjust the set.
Submit the alignment
With at least two sequences ticked, click Submit Alignment. PAVI picks each gene’s canonical transcript; genes with no usable protein are dropped and reported.

Ortholog jobs don’t include variant selection — for variant work, use the main Submit Job page.

Many genes at once

Bulk upload

The Bulk Upload page pre-fills the submit form from a file, so you don’t enter genes one by one.

File format

Upload a CSV, TSV, TXT, or .xlsx file with a header row. Delimiters are detected automatically; spreadsheets read the first sheet.

Column	Required?	Notes
`species`	Yes	e.g. Mus musculus
`gene_symbol`	Yes	Aliases: `symbol`, `gene`
`transcript`	Optional	Blank → PAVI picks the canonical transcript
`variants`	Optional	Allele IDs separated by `;` or `,`

Click Download template for pavi-bulk-genes-template.csv — a working example (mouse and rat Sod1) to edit.

What happens on upload

PAVI resolves each row to a gene by symbol + species, best-effort: exact matches load; the rest are skipped and listed with a reason (missing species/symbol, no gene found, ambiguous, duplicate, or lookup failed) — e.g. “Loaded 5 genes · skipped 2 rows.” Loaded genes drop into an editable, pre-filled submit form.

While it runs

Tracking progress

After you submit, the progress page opens with your job ID and refreshes every few seconds.

Pipeline timeline — five stages from Job Submitted through Sequence Retrieval and Alignment (Clustal Omega) to Finalizing Results, each with a live status and timestamp.
Pipeline log — a running, colour-coded console of what the pipeline is doing.

On completion you’ll see Alignment Complete! and PAVI opens the result. On failure, an error box explains what happened and offers Submit New Job. Typical runtimes: 2–5 seq ~30 s–2 min · 5–10 ~2–5 min · 10+ ~5–15 min.

The payoff

Reading your results

The result page centres on an interactive alignment, with a summary above it and downloads in the header.

The interactive alignment viewer: a position ruler with variant markers across the top, sequence names down the left, and a colour-coded multiple sequence alignment grid of amino-acid residues. — **The interactive alignment viewer.** Sequences (labelled by name and species) align column-by-column with residues coloured by scheme; the ruler carries variant markers, and clicking a column or a variant card zooms straight to it. Example: a nematode/insect ortholog set.

The summary

The Alignment Results bar shows sequence count, alignment length, and variant count at a glance. Expand it for conservation and gap-content bars, identical positions and the longest conserved block, a colour-graded pairwise identity matrix (green = high, red = low), the species list, and job details.

Variant warnings

If a selected variant produced no protein change on the aligned transcript, the summary explains why and lists the skipped IDs — variant effects are transcript-specific.

Display modes

Interactive (Virtualized)

The full Nightingale viewer — the default, shown above. Handles large sets smoothly.

Interactive (Legacy)

An earlier interactive renderer, kept as a fallback.

Text

A plain monospace alignment to read or copy directly.

Colour schemes

The colour dropdown groups many schemes: Recommended (Clustal2, Conservation), Physical properties (Hydrophobicity, Charged, Polar…), Structural (Buried index, Helix/Strand/Turn propensity), and Classic (Taylor, Zappo, Lesk, Cinema, Mae).

Variants on the alignment

With Variant Locations on (default), affected residues are boxed with a red outline and appear as numbered markers on the variants track. Filter shown variants by Type, Consequence, and Disease / Phenotype. The collapsible Variant Information panel gives a card per variant — impact, ID, species, the ref→alt change, positions, protein HGVS, consequence, and disease/phenotype badges. Click a coding variant’s card to jump and zoom to it.

Inspecting a position & sequences

Click any column to open the Position Info panel: position number, conservation, gap count, consensus residue, and residue distribution. Click a sequence chip to promote it to the reference (top) row, or use its eye toggle to hide that sequence’s variants.

Navigating & zooming

Keys	Action
`←` `→`	Pan left / right
`↑` `↓`	Scroll through sequences
`+` `=` / `-` `_`	Zoom in / out
`Home` `End`	Jump to start / end
`Esc`	Close full-screen view

You can also drag-zoom on the ruler; the viewer auto-zooms to the first variant on load. Full Screen opens a full-window version in a new tab.

Saving & sharing

Option	What you get
Download (summary)	The alignment as a FASTA file
Download .db (card header)	The full per-job SQLite database — inputs, alignment, and sequence info
Share	Copies the result URL — anyone with the link sees the same alignment

What’s inside the .db

The download is a standard SQLite file (pavi-job-<id>.db) you can open in any SQLite client — DB Browser for SQLite, the sqlite3 command line, or Python’s sqlite3 / pandas. It is self-contained: one file holds the whole job, in three tables.

Table	Holds
`metadata`	Job info as key/value — `job_id`, `completed_at`, `input_count`, and schema version.
`input_seq_regions`	The original request — one row per input sequence region, stored as JSON (`region_json`).
`results`	The outputs as named blobs: `alignment` (the Clustal alignment, `text/plain`) and `seq_info` (the aligned sequence & variant info, `application/json`).

So the same file that reproduces your alignment also carries the exact inputs and the per-residue variant mapping — useful for scripting, re-analysis, or archiving.

Need an image?

There’s no built-in image export — use Full Screen and take a screenshot for figures and slides.

Your history

My Jobs

The My Jobs page keeps a history of jobs you’ve run in this browser, with counts of Total, Completed, In Progress, and Failed at the top.

Each row shows the job ID, status (Completed In progress Failed), genes, transcript count, date, and duration — sortable, searchable, paginated. Per-row actions: Star, View (opens result or progress), Copy Link (completed jobs), Resubmit (failed jobs), and Delete.

Moving between browsers

Because history is local, use Add by UUID to bring in a job you ran elsewhere or received as a shared link. Results are retained for 30 days.

When something’s off

Tips & troubleshooting

Symptom	What to try
Can’t find a gene	Use a valid ID (`HGNC:620`, `MGI:87866`) or the exact symbol; confirm the species is one of the eight supported organisms.
A specific variant isn’t listed	Paste its full HGVS into the Alleles box — see Adding specific variants. Only ~100 alleles preload.
Submit stays greyed out	Every entry needs a gene and a transcript, and you need at least two sequences total.
Job failed	Often an invalid gene ID, or a transcript with no coding sequence — try another transcript. Very large jobs can time out; reduce the sequence count.
Job is slow	Runtime scales with sequence length and count (alignment ≈ O(n²)) and current load.
A selected variant “did nothing”	Its effect is transcript-specific and may be silent on the aligned transcript — the summary lists these.

Still stuck? Report issues on the project’s GitHub tracker (linked from the app’s Help center), and browse the in-app Help tab for FAQs and a glossary.

Reference

Glossary

Alignment	Lining up sequences so equivalent residues share a column.
Allele	A specific version of a gene, often carrying one or more variants.
CDS	Coding sequence — the part of a transcript translated into protein.
Clustal Omega	The multiple-sequence-alignment algorithm PAVI uses.
Conservation	How similar a column is across the aligned sequences.
HGVS	Standard variant naming, e.g. `NC_000068.8:g.105521966G>T`.
MSA	Multiple sequence alignment — more than two sequences aligned together.
Nightingale	The EMBL-EBI component library powering PAVI’s viewer.
Ortholog	The “same” gene in another species, from a common ancestor.
Transcript	One RNA product of a gene; a gene can have several.
Variant	A difference from the reference sequence at a genomic position.

PAVI — Protein Annotation & Variant Inspector · a tool of the Alliance of Genome Resources. This guide describes the shipped web application; in-app wording may change between releases.