pLannotate is a CLI tool, Python library, and web server for automatically annotating engineered plasmids and other engineered DNA.

Visit http://plannotate.barricklab.org/ for web server.

Local Installation

To use pLannotate from Python or the command line, follow the instructions below.

Quick install

The easiest way to install is with mamba (a fast, drop-in replacement for conda; the lightweight micromamba works too — just swap in micromamba):

mamba create -n plannotate -c conda-forge -c bioconda plannotate

Then activate the environment and proceed with using pLannotate (see Using pLannotate locally below):

mamba activate plannotate

Installing from source / pip

Installing from source uses conda-forge/bioconda for the external BLAST, DIAMOND, and Infernal executables. Clone or unpack the repository, navigate into the pLannotate folder, then create and activate the environment:

mamba env create -f environment.yml
mamba activate plannotate

This installs the package in editable mode with the test and lint extras. To install the package directly instead (from PyPI or a source checkout), use pip:

pip install plannotate            # core CLI + Python API
pip install 'plannotate[plot]'    # add HTML / notebook plots

pLannotate requires Python 3.10 or newer.

After installation, download the annotation databases:

plannotate setupdb

Note

pLannotate is not currently hosted on PyPi in order to reduce installation confusion. Because the 3rd party, non-python dependencies are critical for use, a PyPi release is of limited use. If you would like to pip install for whatever reason, you can use this repo as your package source and build the wheel manually.

Optional dependencies

The core install is deliberately lean. Extra features live behind package extras, so you only pull in what you need:

extra	pip install 'plannotate[...]'	what it adds
plot	plannotate[plot]	Bokeh, for interactive --html maps and notebook plots
server	plannotate[server]	Streamlit web app (plannotate streamlit), plus Bokeh
databases	plannotate[databases]	Snakemake pipeline for rebuilding the database bundle
test	plannotate[test]	test suite dependencies
lint	plannotate[lint]	ruff, mypy, pyright, and other static-analysis tools

Extras combine, e.g. pip install 'plannotate[plot,server]'. The external search tools (BLAST, DIAMOND, Infernal) are not pip packages — install them via conda-forge/bioconda as shown above, or otherwise put them on your PATH.

Using pLannotate locally

Command Line Interface (batch mode)

To annotate FASTA or GenBank files and generate the interactive plasmid maps on the command line, follow the above instructions to install pLannotate.

Run plannotate batch --help for the complete, version-accurate option list.

Example usage:

plannotate batch -i ./plannotate/data/fastas/pUC19.fa --cores 4 --html --output ~/Desktop/ --file-name pLasmid

Each configured database is an independent search. --cores 4 allows BLAST, DIAMOND, and Infernal searches to run concurrently.

Core performance on an M1 Macbook Pro (...which only has 8 cores... oops):

Running independent database searches concurrently gives a median ~4.6x speedup on ten cores over a single core across those ten plasmids (per-plasmid range roughly 3.6x-5.1x), with larger, feature-rich plasmids benefiting most.

Fast mode

--fast runs a reduced search using only the SnapGene and FPbase databases, skipping the slower Swiss-Prot (DIAMOND) and Rfam (Infernal) searches. It also avoids doubling circular queries, instead stitching together the few features that span the origin, so seam-spanning hits are still recovered. This trades coverage (no RNA families, reduced protein coverage) for speed.

Because fast mode runs only two lightweight searches, extra cores barely help. Some speed gains may be had when batching large numbers of plasmids in fast mode, however.

Origin-of-replication rotation

Passing --rotate (or Construct(rotate=True) in Python) re-frames a circular plasmid so its origin of replication starts at base 1 on the forward strand, giving a canonical, input-independent layout. The origin is chosen from a curated, prevalence-ranked list of bacterial origins; if none is found, the sequence is placed in a deterministic, rotation- and strand-invariant frame so the same plasmid always yields the same output. Linear sequences are left untouched.

Rotation is a framing step, not a speed optimization: it adds a small detection search up front, and annotation itself is unchanged (circular sequences are always fully doubled so origin-spanning features are never missed).

Custom databases

The easiest way to add your own database is plannotate makedb. Give it a FASTA of the features you want to detect (and, optionally, a CSV describing them) and it builds the search index, a descriptions database, and a ready-to-run YAML in one step:

plannotate makedb -i features.fasta -n mylab -m blastn -c descriptions.csv -o mylab_db/
plannotate batch  -i plasmid.fa -y mylab_db/databases.yml --csv

The FASTA holds the reference features. Use a nucleotide FASTA with --method blastn, or a protein FASTA with --method diamond. Each record's header id — the first token after > — is the feature identifier:

>ampR_promoter beta-lactamase promoter
GACTAGTGGTGAGTAACGATG...
>my_terminator
CTAGCATAACCCCTTGGGGCC...

The CSV (optional) attaches a human-readable description to each feature. It needs a header row with an id column (sseqid, id, or accession) whose values match the FASTA ids, plus any of the following columns:

column	meaning	if omitted
sseqid	feature id (required, matches the FASTA header)	—
name	the label shown on the annotation	defaults to the id
type	GenBank feature type (CDS, promoter, …)	misc_feature
blurb	free-text note / description	empty

sseqid,name,type,blurb
ampR_promoter,AmpR promoter,promoter,Promoter for the bla (AmpR) gene
my_terminator,My terminator,terminator,Custom transcription terminator

If you omit --csv entirely, these fields are taken from the FASTA headers instead: the id becomes the name and any trailing header text becomes the blurb.

By default the generated YAML layers your database on top of the builtin SnapGene/Swiss-Prot/FPbase/Rfam databases (which require plannotate setupdb). Pass --no-builtins for a standalone config that searches only your database — handy when you have not downloaded the bundle. Run plannotate makedb --help for the full option list.

Editing the YAML directly

For finer control you can edit the search configuration by hand. To dump the default YAML:

plannotate yaml > plannotate_default.yaml

Edit this configuration to point to custom databases, then pass it with --yaml-file.

The YAML contains search configuration only. To inspect the versions and checksums of the installed database bundle, run plannotate databases.

Using within Python

You can also directly import pLannotate as a Python module:

from plannotate import Construct

seq = "tgaccaggcatcaaataaaacgaaaggctcagtcgaaagactgggcctttcgttttatctgttgtttgtcggtgaacgctctctactagagtcacactggctcaccttcgggtgggcctttctgcgtttataggtctcaatccacgggtacgggtatggagaaacagtagagagttgcgataaaaagcgtcaggtagtatccgctaatcttatggataaaaatgctatggcatagcaaagtgtgacgccgtgcaaataatcaatgtggacttttctgccgtgattatagacacttttgttacgcgtttttgtcatggctttggtcccgctttgttacagaatgcttttaataagcggggttaccggtttggttagcgagaagagccagtaaaagacgcagtgacggcaatgtctgatgcaatatggacaattggtttcttgtaatcgttaatccgcaaataacgtaaaaacccgcttcggcgggtttttttatggggggagtttagggaaagagcatttgtcatttgtttatttttctaaatacattcaaatatgtatccgctcatgagacaataaccctgataaatgcttcaataatattgaaaaaggaagagtatgagtattcaacatttccgtgtcgcccttattcccttttttgcgg"

# Annotate once and export through the Construct API.
construct = Construct(seq, detailed=True, linear=True, cores=4)
hits = construct.annotations_df
seq_record = construct.to_seqrecord()
genbank_text = construct.to_genbank()
html = construct.to_html()

Local web app

The same Streamlit front end hosted at plannotate.barricklab.org can be run locally. Install the server extra, then launch it:

pip install 'plannotate[server]'
plannotate streamlit          # serves on http://localhost:8501

Pass -y/--yaml-file to point the app at a custom database config, or -p/--port to change the port.

Rebuilding the databases

To rebuild the complete database bundle from its upstream sources, install the database-build dependencies and call the top-level build API:

from plannotate import build_databases

archive = build_databases("database-build", cores=4)