Installation

System requirements

PAIREF is a multiplatform Python module and works on GNU/Linux, Windows and macOS. PAIREF depends on the CCP4 Software Suite or PHENIX. Both contain the Computational Crystallography Toolbox with Python 2.7.

Installation

Installation can be done easily using pip that is usually distributed in CCTBX with Python 2.7. If not, see the Troubleshooting section below. In GNU/Linux or macOS, just open the terminal. In Windows, find the CCP4 console or Phenix Command Prompt in the Start menu and open it (see the screenshots below).

_images/ccp4console.gif _images/phenix_command_prompt.gif

Now execute the following commands that installs PAIREF on your computer:

cctbx.python -m ensurepip --user
cctbx.python -m pip install pairef --no-deps --upgrade --user

Be sure that you have used the command cctbx.python or ccp4-python instead of python. macOS users should also have a look to this section below: PAIREF works with PHENIX but not with CCP4 including PAIREF GUI.

If you have administrator permissions, it is possible to install PAIREF for all the users. Just skip the option --user:

cctbx.python -m ensurepip
cctbx.python -m pip install pairef --no-deps --upgrade

Note

If you have installed PAIREF as root or you added the user site-packages directory in your shell PATH, you will not need to write the whole cctbx.python -m pairef ARGUMENTS but only pairef ARGUMENTS.

Packages are also available at the PyPI repository.

Technical details of installation

The installation is done with pip, the package installer for Python. When the option --user is used, the PAIREF module is installed User Space (see the pip documentation). That means that the module is usually installed to folder ~/.local/lib/python2.7/site-packages/ (Linux) or :code:`C:UsersuserAppData` (Windows) so the root/administrator permissions are not required.

If the installation command is run without the option --user, the module is installed just into the CCP4 and PHENIX folders. So it should be installed separately for both CCP4 and PHENIX and the root/administrator permissions are usually required. CCP4 example: While using /software/ccp4/ccp4-7.1/bin/cctbx.python or /software/ccp4/ccp4-7.1/bin/ccp4-python for the installation command, the module would be installed to /software/ccp4/ccp4-7.1/lib/python2.7/site-packages/ . PHENIX example: While using /software/phenix/phenix-1.19-4092/build/bin/cctbx.python for the installation command, the module would be installed to /software/phenix/phenix-1.19-4092/conda_base/lib/python2.7/site-packages/ . So be sure which cctbx.python you are using in your shell - you can check it with the command which cctbx.python on Linux.

Moreover, if you installed the module as root/administrator, it can happen that a user got ther error message python2.7: No module named pairef. This depends on your umask setting. In this case, please set the umask properly that the other users can read the content newly created during the installation or change manually the permissions for the directory where the module was installed.

Troubleshooting

PAIREF works with PHENIX but not with CCP4 including PAIREF GUI

If you noticed that PAIREF does not work with CCP4 (typically on macOS) or you got the error No module named pairef while launching PAIREF GUI via ccp4-python -m pairef --gui, execute also these commands (using ccp4-python instead of cctbx.python) to be sure that the installation has been done properly also for CCP4:

ccp4-python -m ensurepip --user
ccp4-python -m pip install pairef --no-deps --upgrade --user

Command prompt freezes on Windows

PAIREF or its installation just hangs in the command prompt. Nothing is going on.

This can unfortunately happen suddenly on MS Windows. It is caused by the Quick Edit Mode of the Command Prompt. Press Enter or click in the prompt window, the process will continue running.

Error: No module pip available

To install pip in this case, we can follow the instructions in pip documentation: download the installation script get-pip.py and run it.

wget https://bootstrap.pypa.io/2.7/get-pip.py
ccp4-python get-pip.py

Then it should be possible to install PAIREF using the commands on the top of this page.

cctbx.python: Command not found

PAIREF depends on the CCP4 Software Suite or PHENIX. The appropriate paths to the executables must be set well in your working shell (typically bash or tcsh).

If you use CCP4, according to the documentation, run source /path/to/ccp4-<version>/bin/ccp4.setup-sh (in bash/dash/zsh shells) or source /path/to/ccp4-<version>/bin/ccp4.setup-csh (in csh/tcsh shells).

If you use Phenix, according to the documentation, run . /usr/local/phenix-<version>/phenix_env.sh (in bash shell) or source /usr/local/phenix-<version>/phenix_env (in csh/tcsh shells).

Then it should be possible to install PAIREF using the commands on the top of this page.

SNIMissingWarning and InsecurePlatformWarning

If you use old versions of CCP4, you may get the following error message during installation:

C:\ccp4temp>ccp4-python -Qnew -m pip install pairef --user --no-deps
Collecting pairef
C:\CCP4-7\7.0\lib\site-packages\pip\_vendor\requests\packages\urllib3\util\ssl_.py:318:
SNIMissingWarning: An HTTPS request has been made, but the SNI
(Subject Name Indication) extension to TLS is not available on this
platform. This may cause the server to present an incorrect TLS
certificate, which can cause validation failures. You can upgrade to a
newer version of Python to solve this. For more information, see
https://urllib3.readthedocs.io/en/latest/security.html#snimissingwarning.
  SNIMissingWarning
C:\CCP4-7\7.0\lib\site-packages\pip\_vendor\requests\packages\urllib3\util\ssl_.py:122:
InsecurePlatformWarning: A true SSLContext object is not available.
This prevents urllib3 from configuring SSL appropriately and may cause
certain SSL connections to fail. You can upgrade to a newer version of
Python to solve this. For more information, see
https://urllib3.readthedocs.io/en/latest/security.html#insecureplatformwarning.
  InsecurePlatformWarning
  Could not find a version that satisfies the requirement pairef (from
versions: )
No matching distribution found for pairef
C:\CCP4-7\7.0\lib\site-packages\pip\_vendor\requests\packages\urllib3\util\ssl_.py:122:
InsecurePlatformWarning: A true SSLContext object is not available.
This prevents urllib3 from configuring SSL appropriately and may cause
certain SSL connections to fail. You can upgrade to a newer version of
Python to solve this. For more information, see
https://urllib3.readthedocs.io/en/latest/security.html#insecureplatformwarning.
  InsecurePlatformWarning

To solve this problem, install the missing dependencies using the command:

cctbx.python -m pip install urllib3[secure] --user

Then it should be possible to install PAIREF using the commands on the top of this page.

Error: No module named pairef

Please check the section Technical details of installation.

Reinstallation and version upgrade

Reinstallation and upgrade to a new version can be done also using pip, you can use the following command:

cctbx.python -m pip install pairef --no-deps --user --upgrade --force-reinstall

If you have administrator permissions, skip the option --user.

Uninstallation

Run command cctbx.python -m pip uninstall pairef. If you have installed the package as system administrator, you must run this command as an administrator, too.