Getting Started with CHAPERONg

Article included in category Documentation and series CHAPERONg Documentation

1025 words 5 minutes

/computational-tools/chaperong-banner-dir.png

Series - CHAPERONg Documentation

Contents

1. Requirement

The only essential requirement of CHAPERONg is, of course, a functional installation of the GROMACS software run on Linux (Ubuntu ) or Windows (via the Windows Subsystem for Linux, WSL). You can download and install a version by visiting the GROMACS documentation page , or you could find the latest version of GROMACS here .

CHAPERONg is compatible with recent and older GROMACS versions

CHAPERONg has been tested with GROMACS versions 2020.x, 2021.x, and 2022.x, but should generally work with GROMACS 5.x versions and later.

2. Download CHAPERONg

You can get CHAPERONg for free by visiting the CHAPERONg GitHub repository, or via this instant .

3. Installation

Note

In the instructions that follow, replace xxx with main or v0.1 as you have it in the downloaded package.

Step 1: Copy the downloaded CHAPERONg package to your preferred installation directory.

Step 2: Extract the package with:

1

tar xzf CHAPERONg-xxx.tar.gz

or with:

1

unzip CHAPERONg-xxx.zip

Step 3: Enter the extracted CHAPERONg folder:

1

cd CHAPERONg-xxx

Step 4: Run the installation binary:

1

chmod +x install_CHAPERONg.sh && ./install_CHAPERONg

Enter y or yes when prompted for permission. During installation, CHAPERONg will append the installation path to your $PATH via the ~/.bashrc file. After installation, you should see a completion message as shown below:

/chaperong-online-documentation/chaperong-installation2.png — CHAPERONg installation

At any time, you can uninstall CHAPERONg by simply, and CAREFULLY, deleting the lines that have been added your ~/.bashrc file.

4. Optional Dependencies

CHAPERONg will run the entire GROMACS simulation pipelines without additional dependencies installed. However, some other dependencies are required to run some specific analyses facilitated by CHAPERONg. The more of these additional tools you install, the more you are able to maximize the usage and functionalities that CHAPERONg offers.

Existing dependencies do not need to be re-installed

If you have been using GROMACS before, you probably have some or most of these dependencies installed already. You do not need to re-install any active packages.

There are two options by which you can install the dependencies:

installation in conda environment (recommended), or
global (system-wide) installation.

4.1. Installing dependencies with conda (recommended)

Tip

Installation in conda environment is recommended for most of the dependencies.

This approach simplifies the installation of all the optional dependencies (including python-3.8, pymol-2.5.0, imagemagick, numpy, matplotlib, networkx-2.3/networkx-2.5, md-davis, pandas, scipy, etc.), hence maximizing the usage of CHAPERONg.

Step 1: Change to your base anaconda (default) environment:

1

conda activate base

Step 2: Run the conda environment setup script conda_env_setup.sh while in the CHAPERONg folder:

1

chmod +x conda_env_setup.sh && ./conda_env_setup.sh

Note that this step requires an internet connection and could take a while to complete depending on the size of the available RAM and the stength of your connection. So, relax and give it time.

Troubleshooting errors

In case the above command terminates with the following error:

Collecting package metadata (current_repodata.json): failed
CondaHTTPError: HTTP 000 CONNECTION FAILED for url <https://conda.anaconda.org/conda-forge/linux-64/current_repodata.json>
Elapsed: -
An HTTP error occurred when trying to retrieve this URL.,
try the following sequence of commands instead, entering them in order, line-by-line: conda config --set ssl_verify false
conda_env_setup.sh
conda config --set ssl_verify true

Tip

The input parameters for the conda_env_setup.sh script are specified in the conda_dependencies.yml configuration file. Although the default parameters specified in the yaml file contained in the package as you have downloaded it are the most suited for CHAPERONg, you can however alter the specifications based on your other needs. (But do this only if you know what you are doing. 🤣 )

You should see a message like the one shown below, indicating that the chaperong environment has been set up successfully.

/chaperong-online-documentation/chaperong-env.png — CHAPERONg conda environment

Tip

You can confirm the newly created environment named chaperong with:

1

conda env list

You should see chaperong listed among your conda environments.

You can then change into the chaperong environment with:

1

conda activate chaperong

Note

If after setting up the conda environment as described above, some python modules/libraries are, for some reasons, not accessible, you can further run the commands described in system-wide Option 1 below.

4.2. Installing dependencies system-wide (optional)

4.2.1. Option 1: Batch installation

Step 1: To install all of the dependencies at once, enter the following command:

1

sudo apt install grace pymol libpng-dev libjpeg-dev ghostscript-x imagemagick-6.q16 ffmpeg

Step 2: Install/update python libraries as well as a few other packages:

1

pip3 install numpy==1.23.4 scipy matplotlib pandas networkx==2.3

If the pip package is not available

If you don’t have pip installed, you can first install it with:

sudo apt install python3-pip

And then, run the command:

pip3 install numpy==1.23.4 scipy matplotlib pandas networkx==2.3

or pip3 install numpy==1.23.4 scipy matplotlib pandas networkx==2.5

4.2.2. Option 2: One-by-one installation

1. Python3

Note

The analyses run with CHAPERONg have been tested with Python versions 3.8.x and 3.9.x.

2. Grace

1

sudo apt install grace

Note

The system-wide installation of xmgrace as above is probably more convenient and is recommended when possible.

3. PyMOL
You can install PyMOL using apt (as shown below) or visit the PyMOL page to download a distribution of your choice.

1

sudo apt install pymol

Installation in conda environment is recommended for most of the tools

4. ImageMagick

Note

The convert program needed in the ImageMagick package is often already installed in most Linux installations. You can run the convert --version command first to check before the next command below. Either way, it shouldn’t do any harm.

Step 1: Install the ghostscript interpreter and some libraries that might be missing

1

sudo apt install -y libpng-dev libjpeg-dev ghostscript-x

Step 2: Install ImageMagick

1

sudo apt install imagemagick-6.q16

Tip

Confirm that the program convert works

1

convert

or with:

1

convert --version

5. Networkx2.x

1

pip3 install numpy scipy matplotlib networkx==2.3

1

pip3 install numpy scipy matplotlib networkx==2.5

Note

If you don’t have pip installed, you can first install it with: sudo apt install python3-pip

6. ffmpeg

1

sudo apt install ffmpeg

I try my best to make the information on this website as accurate as possible, but if you find any errors in the contents of this page or any other page on this website, kindly get in touch with me at contact@abeebyekeen.com. Also, you are welcome to reach out for assistance and collaboration.