This is a repository for Aggrescan3D standalone application developed by the Laboratory of Computational Biology at University of Warsaw in cooperation with the Laboratory of Protein Folding and Conformational Diseases at Univesity of Barcelona.

Detailed instructions and tutorials are provided on Aggrescan3D WIKI PAGE

---

Table of contents

1. Introduction

2. Windows installation guide

3. Linux installation guide

4. macOS installation guide

5. Docker image

---

Introduction

Aggrescan3D can be installed on Linux, macOS or Windows. This comprehensive tutorial is aimed to guide users through the installation process and is split into three parts for corresponding systems.

Aggrescan3D is a python package using Python 2.7 version. We highly recommend that you use the scientific Anaconda distribution that comes with pre-installed packages and conda package manager which allows for an easier and less error prone installation. If you choose to use Anaconda simply go to their web page and download a Python 2.7 installation for your target operating system (the installer will suggest installing only for current user for Windows systems we also advise that as managing an all-user install can be more challenging and this guide assumes that the user chooses the recommended option). Further steps will give specific instructions for conda users as well as for vanilla python.

Tips for users who are not familiar with Python or using command prompt/terminal:

• Python3.X is NOT the latest version of Python2.7 and you should always use Python2.7 to run Aggrescan3D.
• Throughout this tutorial a PATH will be frequently mentioned. PATH is a variable that tells the system where to look for your installed programs when you issue commands. Detailed instructions on how to modify it will be given in appropriate parts of this guide.
• Most sections of this guide contain a correctness test step which can be executed to see wether or not the isntallation was successful. When in doubt run the test.
• While this tutorial attempts to covers much ground as possible if something goes wrong please contact us for assistance this will also help us improve our software and this guide too!

---

Windows users

1. Python 2.7

Anaconda distribution

If you have chosen to use Anaconda this step is already done.

• Please do note that at this point you should always use the Anaconda Prompt available in the start menu under that name instead of the regular command prompt.

Vanilla Python distribution

• Follow instructions on python.org. During the installation process select to include pip and setuptools as those will be necessary.
• Add Python27/Scripts (by default under C:\Python27\Scripts) folder to your PATH. This folder contains pip which will install Aggrescan3D as well as it is the folder which will contain the Aggrescan3D program once its installed.

Follow the steps described in GFortran section. The folder should be located at C:\Python27\Scripts by default so either follow the steps in the Control Panel or type:

set PATH=%PATH%;C:\Python27\Scripts

• Note that you have to re-type that in each command prompt in which you want to use pip or Aggrescan3D.

pip not installed with Python

If you chose not to install pip with your Python installation you need to do that manually. Assuming you've already made Python2.7 accessible under command "python", download this script, change to the directory with downloaded script and run:

python get-pip.py

Correctness test

To check if pip (hence also Python) are working open a command prompt (press cmd + R; enter "cmd"; hit enter) and run the following command:

pip freeze

This should list all the packages that you have currently installed.

If you wish to check that you have the correct Python version add the Python binary (python.exe) replacing the example path with your respective one:

set PATH=%PATH%;C:\Python27

And then type:

python --version

Minimum recommended python version for Aggrescan3D is 2.7.12 but as low as 2.7.6 should work. We recommend that you download the latest version from python.org.

2. FoldX (optional)

In order to run stability calculations or mutant calculations FoldX has to be present on the system and PATH to it provided to the program upon running a calculation.

FoldX is free for academic use and the licence can be obtained at http://foldxsuite.crg.eu/

3. CABS-flex (optional)

In order to run the dynamic mode (highly recommneded) one has to install CABS-flex. Detailed instructions how to do so can be found here

4. Aggrescan3D

Anaconda users

In your Anaconda Prompt type:

conda install -c lcbio aggrescan3d

Vanilla Python

In the regular command prompt type:

pip install aggrescan3d

Correctness test

Run a simulation of lcbio's favorite 2gb1 with:

aggrescan -i 2gb1 -w test_run -v 4

• If the result is 'aggrescan3d' is not recognized as an internal or external command, operable program or batch file. it means that your Python's Scripts folder is not on the PATH variable.
• If you see a Simulation completed successfully message, congratulations you have completed your first aggrescan3d simulation.

To check if the server app works:

a3d_server

• Open your favourite web browser (Be warned though - Internet Explorer will not be able to provide full functionality)
• Go to localhost:5000
• ** Some of the app functionality might not work on the Windows system (namely job stopping) and the app is generally less responsive and more prone to hang should work well in most cases though **

---

Linux users

1. Python 2.7

Anaconda distribution

If you have chosen to use Anaconda this step is already done. Anaconda installer should ask you if you want it to be added to your PATH, for most users this is desirable because it means that when typing python it will call Anaconda's Python rather than regular one.

• Check if the python command refers to Anaconda Python type:

python --version

The output should be something like Python 2.7.14 :: Anaconda, Inc. . If it is not add a following line to your ~/.bashrc file (found in the user's home directory) replacing the path with your anaconda's installation path:

export $PATH="/absolute/path/to/anaconda2/bin:$PATH"

and then close and reopen the terminal or simply run:

source ~/.bashrc

Vanilla Python distribution

Python 2.7 should be present on all unix systems, to verify the version, open your terminal and type:

python --version

We recommended python version for 2.7.12 or higher but earlier releases might also work.

pip not installed with Python

pip should also be installed by default on most unix systems, verify that it works issuing the following command:

pip freeze

This should return a list of installed packages for your Python. if that is not the case install it using your system's package manager:

sudo apt-get install python-pip

2. FoldX (optional)

In order to run stability calculations or mutant calculations FoldX has to be present on the system and PATH to it provided to the program upon running a calculation.

FoldX is free for academic use and the licence can be obtained at http://foldxsuite.crg.eu/

3. CABS-flex (optional)

In order to run the dynamic mode (highly recommneded) one has to install CABS-flex. Detailed instructions how to do so can be found here

4. Aggrescan3D

Anaconda users

Simply type:

conda install -c lcbio aggrescan3d

Vanilla Python

Simply type:

pip install aggrescan3d

Troubleshooting

• If pip install fails due to writing rights do not use sudo pip install.

• Depending on your privileges and the way your system is managed you might want or need to install Aggrescan3D just for the current user:

pip install --user aggrescan3d

• When using the --user flag the binary is placed in a folder that is usually not on your PATH. Usually it is located in your $HOME/.local/bin but check if that is the case before continuing. Once you located the binary add its location to your path via editing your .bashrc folder in home directory. Add the line:

export PATH="$HOME/.local/bin:$PATH"

Correctness test

Run a simulation of lcbio's favorite 2gb1 with:

aggrescan -i 2gb1 -w test_run -v 4

• If the result is 'aggrescan3d' is not recognized as an internal or external command, operable program or batch file. it means that your Python's Scripts folder is not on the PATH variable.
• If you see a Simulation completed successfully message, congratulations you have completed your first aggrescan3d simulation.

To check if the server app works:

a3d_server

• Open your favourite web browser
• Go to 0.0.0.0:5000 (if the server is not responding depending on the loopback settings localhost:5000 might work)

---

macOS users

1. Python 2.7

Anaconda distribution

If you have chosen to use Anaconda this step is already done. Anaconda installer should ask you if you want it to be added to your PATH, for most users this is desirable because it means that when typing python it will call Anaconda's Python rather than regular one.

• Check if the python command refers to Anaconda Python type:

python --version

If the result doesnt include the word Anaconda it means your system is using other Python version by default this can be changed by prepending Anaconda to your PATH.

• Move into home directory
• Create a .bash_profile file using a text editor (like nano) nano .bash_profile
• Add the line export PATH="/absolute/path/to/anaconda2/bin:$PATH" with your respective path to anaconda2 installation
• Save the file and relaunch the terminal

Vanilla Python distribution

macOS comes with Python2.7 already installed. To check if you have the correct Python version open the Terminal.app and type:

python --version

If you get the message: bash: python: command not found it may mean that your system doesn't have Python installed, or Python's binary is not in the system PATH. To check this run in the Terminal.app the following command:

/Library/Frameworks/Python.framework/Versions/2.7/bin/python --version

If you still get the message: bash: python: command not found you need to install Python2.7. Otherwise add Python's binary to the system's PATH by running in the Terminal.app the following command and then reopen the terminal:

echo "export PATH=/Library/Frameworks/Python.framework/Versions/2.7/bin/:$PATH" >> ~/.bash_profile

pip not installed with Python

Assuming you've already installed Python2.7 and made it accessible under command "python" simply install pip via setuptools by:

sudo easy_install pip

2. FoldX (optional)

In order to run stability calculations or mutant calculations FoldX has to be present on the system and PATH to it provided to the program upon running a calculation.

FoldX is free for academic use and the licence can be obtained at http://foldxsuite.crg.eu/

3. CABS-flex (optional)

In order to run the dynamic mode (highly recommneded) one has to install CABS-flex. Detailed instructions how to do so can be found here

4. Aggrescan3D

Anaconda users

Simply type:

conda install -c lcbio aggrescan3d

Vanilla Python

Simply type:

pip install aggrescan3d

For macOS "El Captian" are newer six library comes preinstalled and may cause installation erros. Try running: pip install aggrescan3d --ignore-installed six instead.

Correctness test

Run a simulation of lcbio's favorite 2gb1 with:

aggrescan -i 2gb1 -w test_run -v 4

• If the result is 'aggrescan3d' is not recognized as an internal or external command, operable program or batch file. it means that your Python's Scripts folder is not on the PATH variable.
• If you see a Simulation completed successfully message, congratulations you have completed your first aggrescan3d simulation.

To check if the server app works:

a3d_server

• Open your favourite web browser
• Go to 0.0.0.0:5000 (if the server is not responding depending on the loopback settings localhost:5000 might work)

---

Docker image

Aggrescan3D is also available as a docker image and this tutorial will guide the user through how to create a local, always available Aggrescan3D server on their PC using the Docker technology. This could also be a good workaround for users facing compatibility and installation issues.

Please note we cannot include FoldX nor Modeller software in distributed images as they require a licence to run. We however explain how to get those running easly and unlok the full potentail of Aggrescan3D inside a Docker container

• lcbio/a3d_server - conda based distribution. Included Dockerfile should allow the users to build a Docker Image with dynamic mode support

Beginner's tutorial

While we cannot provide a ground-up guide on Docker usage we do provide basic instructions and further reading material that should make it possible to use this without prior experience. This tutorial is Linux oriented but Docker is also available on Windows10 Pro.

1. Installing Docker

Please refer to the docs which contain detailed and well written guides for different systems:

We also recommend you read this starter article on the docker docs

And this post-installation tips (especially if you get permission errors and have to always run docker with sudo)

2. Using dynamic mode in the container

To do that one has to create their own image based on our conda image.

• Create a new folder and cd into it mkdir docker_build && cd docker_build
• Create a Dockerfile and copy the contents which can be found here
• Uncomment the suggested lines and replace XXXX with your Modeller licence key
• Run docker build -t image_name .
• If the process is successful the image will be available under 'image_name'

3. Get the Aggrescan3D image (skip if you did point 2)

To make the image available on your system run:

#!bash
docker pull lcbio/a3d_server

4. Running the Docker container

The basic goal of the conatiner is to provide a server-like service locally. We recommend to use a following command (explained below):

#!bash
docker run --name a3d_service -p 5000:5000 -v /your/absolute/path/to/FoldX:/home/FoldX --restart unless-stopped -d a3d_server

• The name command will assign a name to your container which will make it easier to manipulate it in the future
• The -p option exposes your container's 5000 port to your machine's 5000 port. This will mean that you can access the service from your machine.
• The -v option mounts your FoldX folder inside the container which makes it available to the service. This is necessary if you wish to use the stability calculations or mutations. Please leave the second part (after ':') unchanged and make sure you provide an absoulte path.
• The restrart unless-stopped will restart the container on system restart meaning it will be always available (Blocking port 5000 though).
• The -d options means detach - the container will run in the background

Addition interaction with the container can be performed as follows:

• To stop the service: docker stop a3d_service
• To start it again: docker start a3d_service
• To restart a running container (in case it hung, etc): docker start a3d_service
• To copy files from container to local system (results on the container are stored inside /opt/conda/lib/python2.7/site-packages/a3d_gui/computations/): docker cp a3d_service:path/inside/the/container local/path
• To delete the container (this will delete all the simulation results that were not copied to the filesystem!): docker rm a3d_service

To interact with the container's console for purposes other than the server run it via which will give access to a shell with aggrescan installed:

docker run --name my_container a3d_server /bin/bash

5. Further reading

• Running docker images explained
• We found this guide to be quite informative and well-written.