Skip to content

Install Whiscy

Below we will go into a step-by-step guide on how to install Whiscy. Instructions are provived for Ubuntu Linux, in other systems the installation process may vary.

WHISCY is not distributed on PyPI. Use the Docker image, or install it from this repository.

Docker

The image includes WHISCY and its third-party software (FreeSASA and Protdist). Each release is published at ghcr.io/haddocking/whiscy:<tag>, e.g.:

docker pull ghcr.io/haddocking/whiscy:v1.6.0
docker run --rm -v "$PWD":/data -w /data \
  -e WHISCY_EBI_EMAIL=your.name@example.org \
  ghcr.io/haddocking/whiscy:v1.6.0 whiscy_setup 1ppe.pdb E

The current directory is mounted as /data, where the commands read and write their files.

From the repository

Third-Party

Whiscy depends on the following third-party software:

  • FreeSASA
  • Protdist

The installation of these dependencies is described in the THIRDPARTY.md file.

Whiscy

Install it with pip from a clone of the repository (Python 3.11 or later):

git clone https://github.com/haddocking/whiscy.git
cd whiscy
pip install .

Check the installation:

$ whiscy -h
usage: whiscy [-h] [-o output_file] [--version]
              surface_list conversion_table alignment_file distance_file

positional arguments:
  surface_list          Surface list
  conversion_table      Conversion table
  alignment_file        Alignment file
  distance_file         Distance file

options:
  -h, --help            show this help message and exit
  -o output_file, --output output_file
                        If set, output prediction to this file
  --version             show program's version number and exit

Environment variables

WHISCY reads these environment variables:

Variable Required Purpose
FREESASA_BIN yes Path to the freesasa binary
PROTDIST_BIN yes Path to the protdist binary
WHISCY_EBI_EMAIL no Contact email for EBI BLAST (see below)
WHISCY_SEARCH_TIMEOUT no Time limit per search service, in s (3600)

Without an alignment, whiscy_setup searches for homologs with ColabFold MMseqs2, and with EBI BLAST when ColabFold fails or finds fewer than 10 usable homologs. The EBI requires a contact email; without WHISCY_EBI_EMAIL this fallback is skipped. See USAGE.md.

export FREESASA_BIN=$HOME/software/freesasa-2.0.3/bin/freesasa
export PROTDIST_BIN=$HOME/software/protdist/protdist
export WHISCY_EBI_EMAIL=your.name@example.org

Troubleshooting

If you get an error such as ValueError: FREESASA_BIN not found in system variables, make sure you have followed the steps in THIRDPARTY.md to install the third-party dependencies.