funannotate2 26.4.22

Funannotate2: eukarytoic genome annotation pipeline

funannotate2: eukaryotic genome annotation pipeline

Funannotate2 is a comprehensive eukaryotic genome annotation pipeline that provides a complete workflow for annotating eukaryotic genomes. It integrates various tools and databases to produce high-quality gene predictions and functional annotations.

Quick start: Installation

Docker (recommended)

A pre-built image with all bioconda tooling (augustus, minimap2, miniprot, snap, glimmerhmm, diamond, trnascan-se, table2asn, …), funannotate2, funannotate2-addons, helixerlite, and pre-downloaded databases is published to Docker Hub and GHCR on each tagged release.

# pull the latest image (~8 GB; databases are baked in)
docker pull nextgenusfs/funannotate2:latest
# or from GHCR
docker pull ghcr.io/nextgenusfs/funannotate2:latest

# quick sanity check
docker run --rm nextgenusfs/funannotate2:latest funannotate2 --version
docker run --rm nextgenusfs/funannotate2:latest funannotate2 install -s

# run against a local data directory, persisting the BUSCO cache across runs
mkdir -p $PWD/data $PWD/busco_cache
docker run --rm -it \
    -v $PWD/data:/data \
    -v $PWD/busco_cache:/opt/busco_cache \
    -e BUSCO_DOWNLOAD_PATH=/opt/busco_cache \
    nextgenusfs/funannotate2:latest \
    funannotate2 predict -i /data/genome.fa -o /data/out --species "My species"

Notes:

• The image is linux/amd64 only; on Apple Silicon it runs under Rosetta 2 emulation (Docker Desktop handles this automatically).
• BUSCO lineages are not bundled (~90 GB uncompressed) — mount a host directory as shown above so they download once and are reused.
• GeneMark is not included (license-restricted); install it locally and mount into the container if you need it.

Using pixi

If you prefer a native install without Docker, the repo ships a pixi workspace (pixi.toml / pixi.lock) that resolves the full environment on linux-64:

# install pixi once (see https://pixi.sh/latest/#installation)
curl -fsSL https://pixi.sh/install.sh | bash

# clone and install the locked environment
git clone https://github.com/nextgenusfs/funannotate2.git
cd funannotate2
pixi install --locked

# activate and install databases
pixi shell
export FUNANNOTATE2_DB=/path/to/funannotate2-db
funannotate2 install -d all

The pixi environment is currently defined for linux-64 only. macOS users should use Docker.

Linux systems (conda)

Until this gets pushed to bioconda, can try this:

mamba create -n funannotate2 gfftk gapmm2 minimap2 miniprot snap "augustus==3.5.0" glimmerhmm diamond trnascan-se table2asn gb-io buscolite
conda activate funannotate2
python -m pip install git+https://github.com/nextgenusfs/funannotate2.git

Apple Silicon (M series)

Installation on apple silicon (M series) is a little bit more involved due to some dependency issues and non-native builds of some software. I've not been able to find or build a version of augustus that will run, so instead I've been running augustus and genemark locally with Docker. I've setup two repos with instructions on how to get this working (Need Docker Desktop installed) and then will need to put the bash wrapper files in your PATH to mimic the CLI interface.

https://github.com/nextgenusfs/dockerized-augustus

https://github.com/nextgenusfs/dockerized-genemark

Once that is working, you can then install most of the remaining dependencies with conda, although we need to leave out both buscolite and funannotate2 because they have augustus as a dependency, instead we will install those python packages with pip. The conda mkl<2022 is to avoid an annoying warning on apple silicon with the intel mkl package.

# first install most of the dependencies
mamba create -n funannotate2 --platform osx-64 "python>=3.7,<3.13" gfftk gapmm2 minimap2 miniprot snap glimmerhmm diamond trnascan-se gb-io pyhmmer pyfastx requests json-repair pytantan "mkl<2022"

# we can then add the required FUNANNOTATE2_DB env variable to the conda environment, note need to reactivate to use it
conda activate funannotate2
conda env config vars set FUNANNOTATE2_DB=/path/to/funannotate2-db
conda env config vars set AUGUSTUS_CONFIG_PATH=/path/to/augustus-3.5.0/config
conda deactivate

# now reactivate environment, and install the remaining python dependencies with pip
conda activate funannotate2
python -m pip install buscolite git+https://github.com/nextgenusfs/funannotate2.git

# now we can install the databases
funannotate2 install -d all

Other/Manual Installation

Additional tools like genemarkHMM must be installed manually due to licensing.

funannotate2 is a python package, to install release versions use the pip package manager, like so:

pip install funannotate2

Or to install the bleeding edge version from github repo:

python -m pip install git+https://github.com/nextgenusfs/funannotate2.git

Development

Testing

Funannotate2 includes both unit tests and integration tests to ensure the code works correctly.

Running Tests

To run the tests, you need to install pytest and the package in development mode:

# Install pytest and coverage tools
pip install pytest pytest-cov

# Install funannotate2 in development mode
pip install -e .

# Run all tests
pytest

# Run with coverage report
pytest --cov=funannotate2

# Generate HTML coverage report
python scripts/run_coverage.py

For more information about testing, see the TESTING.md file.

Development Dependencies

To work on funannotate2 development, you'll need to install the development dependencies:

pip install pytest pytest-cov

Documentation

Funannotate2 includes comprehensive documentation that covers installation, usage, API reference, and more. To build the documentation:

# Install Sphinx and the theme
pip install sphinx sphinx_rtd_theme

# Build the documentation
cd docs
make html

The built documentation will be in the docs/_build/html directory.

For more information about the documentation, see the docs/README.md file.

Running Tests

After installing the development dependencies, you can run the tests with:

python -m pytest

To run tests with coverage reporting:

python -m pytest --cov=funannotate2 --cov-report=term-missing

Or use the provided script to generate an HTML coverage report:

python scripts/run_coverage.py

To install the most up to date code from this repo, you can run:

python -m pip install git+https://github.com/nextgenusfs/funannotate2.git --upgrade --force --no-deps

Citation

Funannotate2 includes a CITATION.cff file that provides citation information for the software. The version and release date in this file are automatically updated when a new release is created.

To cite funannotate2 in your work, you can use the citation information from the CITATION.cff file or generate a citation in your preferred format using tools like citeas.org.