# Install Harpy

method	considerations
conda or mamba	If using conda, we strongly recommend using version `23.10` or later. If using mamba, replace `conda` with `mamba` in the instructions below.
pixi	Relatively new kid on the block-- think of it as the next-gen of conda. It's a little different, but it's lightning fast and very sensible to use.
docker or apptainer	Clunkier to use, but best system compatibility and might be what your sysadmins prefer.
pip	Should be considered your last resort if the other methods don't work.

Harpy is hosted on Bioconda, which means you just need to have either conda or pixi (or docker) on your Unix-like system to install it.

It's best to create a new environment for a harpy installation. The code below creates a new conda/mamba environment called harpy (via -n harpy) and installs harpy into it. You can name this environment whatever you like using the -n somename argument.

conda create -n harpy -c bioconda -c conda-forge harpy

Once conda/mamba finishes, activate the harpy conda/mamba environment with:

conda activate env_name

where env_name is the name of that environment. After doing so, the harpy executable should be callable from your path.

Alternatively, you can create the environment locally within a specific project folder, just swap -n harpy for -p path/to/workdir/harpy, which creates the environment in that specific folder (e.g. potato_blight/harpy).

conda create -p path/to/workdir/harpy -c bioconda -c conda-forge harpy

If you wish to install harpy and its dependencies into an existing environment, activate that environment and execute this installation code:

conda activate env_name
conda install -c conda-forge bioconda::harpy

Or provide -n env_name to install it into an existing environment named env_name

conda install -n env_name -c conda-forge bioconda::harpy

Activate the environment and run conda update:

conda update -c conda-forge bioconda::harpy

# ⚡ Conda Usage

Activate the conda environment with Harpy and call harpy or harpy --help on the command line to get started

activate the environment
conda activate harpy_env

# or, if installed locally
conda activate path/to/harpy_env

call harpy
harpy

If you prefer Pixi (it's pretty good, you should try it), you can install Harpy to be accessible in your PATH, i.e. a "global" installation:

pixi global install -c conda-forge -c bioconda harpy

add pixi to PATH

Make sure ~/.pixi/bin is in your PATH:

~/.zshrc or ~/.bashrc (or equivalent)
export PATH=~/.pixi/bin:$PATH

Likewise, you can do an installation into a local project directory:

pixi init -c conda-forge -c bioconda projectname && cd projectname
pixi add harpy

If installed via Pixi, you can update Harpy with pixi update:

# global install
pixi global update harpy

# local install
# project dir has the pixi.toml file
cd path/to/projectdir
pixi update harpy

# ⚡ Pixi Usage

If installed globally, just call harpy or harpy --help on the command line, otherwise navigate to the directory with the pixi environment and call harpy from within it:

call harpy if installed globally
# installed globally
harpy

call harpy if installed locally
# navigate to project directory
cd path/to/workdir

# activate the pixi environment and run harpy
pixi shell
harpy

# or prepend `pixi run` to it without activating the environment
pixi run harpy

If you didn't know, packages on Bioconda are automatically built as containers too! Use one of the two approaches below then proceed to use containerized-Harpy however you are used to using containers on your system.

Works on Windows, macOS, and Linux.

docker pull quay.io/biocontainers/harpy

Apptainer is Linux-only, but can be used inside a Windows WSL. Find the most recent tag here and replace $TAG with it or use the TAG=$(curl ...) part below to pull the latest version name using the repository's API.

TAG=$(curl -s "https://quay.io/api/v1/repository/biocontainers/harpy/tag/" | cut -d'"' -f6)
apptainer pull docker://quay.io/biocontainers/harpy:$TAG

This is the "all else fails" solution and generally not recommended. You can install Harpy locally via pip, however, it can only get so far as installing the Python package dependencies and not the other software, which you will need to install manually if it's not already on your system.

The problem is, if you get Harpy installed this way, you will need to use --container for the workflows, since otherwise it would use Conda, which we're assuming isn't available to your system (otherwise you would have installed Harpy using it). If you're on a Linux system, that should be fine. However, if you're on a macOS system, the container software, Apptainer, isn't available for macOS (or Windows), meaning you won't be able to use most of Harpy.

The latest release can be found here. You will want to download the latest tarball, which will be named harpy.VERISON.tar.gz. Something like https://github.com/pdimens/harpy/releases/download/2.5.0/harpy.2.5.0.tar.gz.

# change the version number to the latest release!
wget https://github.com/pdimens/harpy/releases/download/2.5.0/harpy.2.5.0.tar.gz
tar xvfz harpy.2.5.0.tar.gz
cd harpy.2.5.0

python -m pip install .

If for some reason it's fussing when you try that command, you can attempt this method:

python3 -m pip install --upgrade build && python3 -m build && \
    pip install dist/*.whl

Harpy needs all the scripts in the harpy/bin folder installed too. You will need to copy them into some kind of folder on your PATH (e.g. /usr/local/bin or ~/.local/bin). If you don't understand what that means, see this resource.

chmod +x harpy/bin/*
cp harpy/bin/* path/to/the/folder

Unfortunately, you will still need to install the remaining non-Python software, listed below with their minimum version numbers in parentheses. With any luck, your system might have one of more of them already installed!

bcftools (>=1.22)
htslib (>=1.22)
samtools (>=1.22)

All three of bcftools, samtools, and htslib can be installed as described here.

seqtk

git clone https://github.com/lh3/seqtk.git;
cd seqtk; make

Updating Harpy installed this way would require repeating the steps with a different Harpy version.

# ⚡ Pip Usage

You should be able to call harpy from your command line:

harpy