%global _empty_manifest_terminate_build 0 Name: python-proshade Version: 0.7.6.6 Release: 1 Summary: Protein Shape Description and Symmetry Detection (ProSHADE) python module License: GNU General Public License (GPL) URL: https://github.com/michaltykac/proshade Source0: https://mirrors.nju.edu.cn/pypi/web/packages/ee/ea/3f786409f1acfcf6c34162641ea7de4729127ed27d23393a99b9c940b59b/proshade-0.7.6.6.tar.gz BuildArch: noarch %description Protein Shape Description and Symmetry Detection version 0.7.6.6 (JUL 2022) # Introduction ProSHADE is a C++ language library and an associated tool providing functionalities for working with structural biology molecular structures. The library implements functions for computing shape-wise structural distances between pairs of molecules, detecting symmetry over the centre of mass (or centre of map) of a single structure, map re-sizing as well as matching density maps and PDB coordinate files to one another. The executable implemented in the ```bin.cpp``` file then allows easy access to these functionalities without the need for library linking, while the python modules provides easy access to the functionality from the python language. For help on how the executable should be used, refer to the ```-h``` option of it. For more details about the functionalities, see below. # Obtaining ProSHADE The most recent stable version of ProSHADE is available from the *master* branch of the GitHub repository https://github.com/michaltykac/proshade, from where it can be cloned using the git application or downloaded manually using the interface. More advanced users may be interested in obtaining the *development* or the *experimental* branches, which are available from the same link. The *experimental* branch is where I do all new development and it may or may not be currently compilable and/or working properly, while the *development* branch should always compile, but is more likely to contain bugs and issues as it is the code before proper testing. # Index - [Introduction](#introduction) - [Obtaining ProSHADE](#obtaining-proshade) - [Index](#index) - [Installation](#installation) - [Standard System Dependencies](#standard-system-dependencies) - [Installing python](#installing-python) - [Installing standard system dependencies on MacOS](#installing-standard-system-dependencies-on-macos) - [Installing standard system dependencies using apt)](#installing-standard-system-dependencies-using-apt) - [Installing standard system dependencies using ZYpp](#installing-standard-system-dependencies-using-zypp) - [Installing standard system dependencies using yum](#installing-standard-system-dependencies-using-yum) - [Other dependencies](#other-dependencies) - [Installing on Windows](#installing-on-windows) - [Installing CMake](#installing-cmake) - [Installing git](#installing-git) - [Installing Build Tools for Visual Studio](#installing-build-tools-for-visual-studio) - [Installing ProSHADE](#installing-proshade) - [Setting ProSHADE PATH](#setting-proshade-path) - [Installing using CMake on Unix](#installing-using-cmake-on-unix) - [CMake options](#cmake-options) - [Uninstall using CMake](#uninstall-using-cmake) - [Installation using pip](#installing-using-pip) - [Uninstalling pip installed module](#uninstalling-pip-installed-module) - [Input PDB files](#input-pdb-files) - [Spacegroups](#spacegroups) - [Waters](#waters) - [Models](#models) - [Using the ProSHADE binary](#using-the-proshade-binary) - [Symmetry Detection](#symmetry-detection) - [Shape similarity distances](#shape-similarity-distances) - [Re-boxing structures](#re-boxing-structures) - [Optimal rotation and translation](#optimal-rotation-and-translation) - [Using the ProSHADE library](#using-the-proshade-library) - [Linking against the ProSHADE library](#linking-against-the-proshade-library) - [Examples of ProSHADE library usage](#examples-of-proshade-library-usage) - [Using the Python module](#using-the-python-module) - [Python module examples](#python-module-examples) - [Simple access](#simple-access) - [Advanced access](#advanced-access) - [Direct access](#direct-access) - [Reading a structure from file](#reading-a-structure-from-file) - [Reading co-ordinates from gemmi](#reading-co-ordinates-from-gemmi) - [Creating ProSHADE_data object from map](#creating-proshade_data-object-from-map) - [3D arrays](#3d-arrays) - [Writing out maps](#writing-out-maps) - [Getting back the ProSHADE internal representation map](#getting-back-the-proshade-internal-representation-map) - [Computing standard ProSHADE tasks](#computing-standard-proshade-tasks) - [Computing the spherical harmonics decomposition](#computing-the-spherical-harmonics-decomposition) - [Computing the self-rotation function](#computing-the-self-rotation-function) - [Computing the optimal rotation function](#computing-the-optimal-rotation-function) - [Finding the optimal rotation](#finding-the-optimal-rotation) - [Rotating the internal map representation](#rotating-the-internal-map-representation) - [Computing the translation function](#computing-the-translation-function) - [Writing out resulting structures](#writing-out-resulting-structures) # Installation The installation of the ProSHADE software should be done using the CMake system and the supplied CMakeLists.txt file. The minimal requiered version of CMake is 2.6, however, python modules and single source file compilation will not be available unless CMake version 3.4 or higher is used. The CMakeLists.txt file assumes the standard system dependencies are installed in the system folders; for a full list of standard system dependencies, please see the section [Standard System Dependencies](#standard-system-dependencies). Once all of the standard system dependencies are installed CMake can be run to create the make files as described in the section [Installing using CMake](#installing-using-cmake). Alternatively, ProSHADE also provides *setup.py* script, which wraps the CMake installation - please refer to the [Installation using pip](#installation-using-pip) section of this documentation for more details. The main difference between these two installation approaches is that using CMake allows building the executable and the dynamic C++ library, but will install the python module only locally, while installing using pip will install only the python module, but will install it globally. Combining these two installations is not a problem. Moreover, if CMake is used to build ProSHADE directly, then the user may make use of several options that can be used to modify the default behaviour of the installation; these typically drive the installation locations and dependencies paths in the case of non-standard dependency location. Please see the section [CMake options](#cmake-options) for details as to how to use these options and what do they do. Please note that while the ProSHADE code is C++ 98 standard compatible, some of the dependencies do require at least partial support for the C++ 11 standard and building python module requires full C++ 11 compliant compiler. ## Standard System Dependencies Generally, the following list of standard system libraries and utilities are required for successfull installation of ProSHADE on Unix systems: - **gcc** - **g++** - **make** - **cmake** - **fftw3-dev** - **liblapack-dev** - **git** - **zlib** - **python** with **numpy** This list is somewhat different for Windows systems, as ProSHADE contains 64-bit libraries for most of the dependencies already prepared, thus limiting the list. This, however, means that ProSHADE can only be installed on Windows10 64-bit systems and currently does neither supprt the 32-bit systems, nor the older Windows systems (7, Vista, XP, ...): - **cl** - **cmake** - **git** - **python** with **numpy** CMake should complain and issue a reasonably decipherable error messages if any of these dependencies are missing. ### Installing python Python is not required for ProSHADE binary and library installation, but it is necessary to have it installed for successfull ProSHADE python module installation. Now, while most modern Unix systems come with some version of the python language pre-installed (although Windows does not), it seems reasonable to assume that users who are interested in using the ProSHADE python module do have their preferred version of python already installed and set as the default system python (meaning that the ```python``` command points to the python executable that the user wants the ProSHADE module to be installed for). Should the user not have any python version installed or should the user be interested in having multiple versions, the Anaconda environment ( https://www.anaconda.com/products/individual ) can be recommended for all systems supported by ProSHADE. Of course, there are alternatives for installation of python and management of various environments and ProSHADE does not care which is being used. ### Installing standard system dependencies on MacOS Assuming a clean MacOS, the ProSHADE dependencies can be installed as follows: Firstly, the XCode tools should be installed from Apple - this can be achieved by issuing the command: ``` xcode-select --install ``` Next, CMake will need to be installed manually; that is, starting with downloading the source codes from https://github.com/Kitware/CMake/releases/download/v3.19.2/cmake-3.19.2.tar.gz . After moving the downloaded file to where the codes should live and navigating to the same location in Terminal, please use the following commands to install CMake: ``` tar -zxvf ./cmake-3.19.2.tar.gz cd ./cmake-3.19.2 ./bootstrap make sudo make install ``` Finally, some MacOS systems do not have the FFTW3 library pre-installed. If this is your case, then please use the following commands to install FFTW3 manually: Firstly, download the source codes from here: http://www.fftw.org/fftw-3.3.9.tar.gz . After moving the downloaded file to where the codes should live and navigating to the same location in Terminal, please use the following commands to install FFTW3: ``` tar -zxvf ./fftw-3.3.9.tar cd ./fftw-3.3.9 ./configure --enable-shared make sudo make install ``` Now, ProSHADE should be automaically installable using the CMake system. ### Installing standard system dependencies using apt The *APT* package manager can be used to install all the system dependencies of ProSHADE using the following command. ``` sudo apt-get install gcc g++ make cmake git fftw3-dev liblapack-dev zlib1g-dev ``` After this, ProSHADE should by automatically installable using the CMake system. ### Installing standard system dependencies using ZYpp The *ZYpp* package manager and the associated *zypper* command-line tool can be used install all the system dependencies of ProSHADE as follows: ``` sudo zypper install gcc gcc-c++ git cmake fftw3-devel lapack-devel zlib-devel ``` After this, ProSHADE should by automatically installable using the CMake system. ### Installing standard system dependencies using yum Firstly, at least on some systems, the *yum* package manager may not be using the *powertools* repository; however, some of ProSHADE dependencies are kept there. Therefore, the user may need to enable the *powertools* repository by issuing the folloing commands: ``` sudo yum install dnf-plugins-core sudo yum config-manager --set-enabled powertools ``` Then, the *yum* package manager can be used install all the system dependencies of ProSHADE as follows: ``` sudo yum install gcc gcc-c++ make cmake fftw3-devel lapack-devel zlib-devel ``` After this, ProSHADE should by automatically installable using the CMake system. ## Other dependencies ProSHADE also depends on the *Gemmi* and *SOFT2.0* libraries. The installation of these libraries is automated in the CMake scripts and therefore does not require any user input (*SOFT2.0* library is supplied with the ProSHADE code and will be installed locally by the ProSHADE CMake installation). Please note that these dependencies do have their own licences (the Mozilla Public License for *Gemmi* and the GPL v3 licence for *SOFT2.0*) and therefore this may limit the ProSHADE usage for some users beyond the ProSHADE copyright and licence itself. ## Installing on Windows As mentioned above, ProSHADE currently only supports Windows10 64-bit systems and cannot be simply installed on other Windows systems. In order to install ProSHADE on a Windows10 64-bit machine, the user is required to firstly have installed some basic pre-requisities. ### Installing CMake CMake can be installed on Windows using the 64-bit MSI installer (binary distribution) available from https://cmake.org/download . During the installation, please make sure that the option to *Add CMake to the system PATH* is selected (it does not matter to ProSHADE if it is for all users or just for the current user). ### Installing git Git can be installed on Windows by downloading the 64-bit Windows Setup installer from https://git-scm.com/download/win . The installer asks for many options, the only important one for ProSHADE installation is that in the section "Adjusting your PATH environment" it is required that the option *Use Git from Git Bash only* is **NOT** selected. This makes sure that the git executable is in the system PATH. ### Installing Build Tools for Visual Studio Sadly, the Authors are not aware of any simple way of installing the Microsoft C and C++ compilers and linker controlling tool - **cl.exe** except for installing the full Visual Studio or the Build Tools for Visual Studio. This will require well over 7.5GB of space on your hard-drive and the download is well over 1.5GB. Nonetheless, it is the main Windows compiler and linker and therefore ProSHADE cannot be installed on Windows without it. To install the Build Tools for Visual Studio, please download the installer from Microsoft at https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022 and in the Workload selection screen select the *Desktop development with C++* option. The rest of the installtion should be automatic. ### Installing ProSHADE Once all of the above dependencies are installed, the ProSHADE python module can now be installed using the pip installation as described in the [Installing using pip ](#installing-using-pip) section. Should the user require installation from the Command Prompt, they will need to open the *Developer Command Prompt for VS 2022* (or the appropriate version the MS Visual Studio they have installed) and type the following commands (replacing the \path\to\proshade with the appropriate path on their machine to the location where they want ProSHADE codes to be stored). Please note that you may need to run the command prompt as an administrator in order to be able to install into the system folders (i.e. C:\Program Files). Also, the same CMake options apply as discussed in section [CMake options](#cmake-options): ``` cd \path\to\proshade git clone https://github.com/michaltykac/proshade mkdir build cd .\build cmake ..\proshade\proshade cmake --build . --config Release cmake --install . ``` ### Setting ProSHADE PATH Finally, ProSHADE now needs to be able to locate the dependency libraries before it can be run on Windows. The simplest way of allowing for this is the add the ProSHADE libraries folder into the system PATH. This can be done by opening the *Control Panel* and selecting the *System and Security* option. In the new window, please select the *System* option and in the next window click the *Advanced system settings* option on the right-hand side panel. In the next window, please click on the *Environment Variables...* button, which will open the penultimate window. In here, in the *System variables* section, please click on the variable named *Path* and then click on the *Edit...* button. This opens the last window, where the *New* button needs to be clicked, immediately followed by clicking the *Browse...* button. In the file selector screen, please navigate to the \path\to\proshade location used in the previous section and then select the following folders: proshade\proshade\winLibs\x64\DLLs and then click on the *OK* button on all open windows which have one. Once the path is set, you can use ProSHADE from any Command Prompt window (not only the Developer Command Prompt used before), although you will have to close and re-open all currently open command prompt windows if you want to use ProSHADE in them. ## Installing using CMake on Unix CMake is the default ProSHADE installation tool and if the binary or the library is needed, then it is the only installation option. The python module can also be build using CMake, but it will be installed only locally and all python scripts will need to add the installation location to their PATH. Alternatively, if the python module is what the user is after, then it can be installed globally using pip - please see the [Installation using pip](#installation-using-pip ) section for more details. In order to install ProSHADE, first please check that all the [Standard System Dependencies](#standard-system-dependencies) are installed, preferably using a package management system such as *apt*, *yum*, *zypper*, *homebrew*, *etc.*. Next, please navigate to any folder to which you would like to write the install files; some find it useful to create a ```build``` folder in the ProSHADE folder in order to keep the install files in the same location as the source codes. Then, issue the following set of commands, changing the ```\path\to\ProSHADE``` to the correct path on your system and adding any required [CMake options](#cmake-options) to the first command. Please note that ```sudo``` may be required for the ```make install``` command if you are installing into the system folders. ``` cmake \path\to\ProSHADE\proshade make make install ``` ### CMake options **-DINSTALL_LOCALLY=ON** or **OFF** - This option is used to decide whether all the installed ProSHADE components are installed in the local source directory (value **ON** ) or whether they are instead installed in the system folders (value **OFF** ) as determined by CMake. This option applies to the binary, the C++ library and the headers as well. Please note that the python module will be installed locally; if it is to be installed globally, please use the pip installation described in the section [Installation using pip](#installation-using-pip ). **-DINSTALL_BIN_DIR=/path** - This option is used to manually specify the folder to which the ProSHADE binary shold be installed into. **-DINSTALL_LIB_DIR=/path** - This option is used to manually specify the folder to which the ProSHADE C++ library should be installed into. **-DINSTALL_INC_DIR=/path** - This option is used to specify the folder to which the ProSHADE header files required by the library should be installed into. **-DCUSTOM_FFTW3_LIB_PATH=/path** - This option is used to supply the path to the libfftw3.a/so/dylib in the case where ProSHADE CMake installation fails to detect the FFTW3 dependency. This is typically the case when FFTW3 is installed outside of the standard FFTW3 installation locations. **-DCUSTOM_FFTW3_INC_PATH=/path** - This option is used to supply the path to the fftw3.h file in the case where ProSHADE CMake installation fails to detect the FFTW3 dependency. This is typically the case when FFTW3 is installed outside of the standard FFTW3 installation locations. **-DCUSTOM_LAPACK_LIB_PATH=/path** - This option is used to supply the path to the liblapack.a/so/dylib in the case where ProSHADE CMake installation fails to detect the LAPACK dependency. This is typically the case when the LAPACK is installed outside of the standard LAPACK installation locations. **-DBUILD_PYTHON=TRUE** or **FALSE** - This option controls whether python modules should be build or not. If you have installed ProSHADE python modules using pip or if you are not interested in using the python modules, you may set this option to FALSE, otherwise the python module will be built for the currently used python. ### Uninstall using CMake To remove the installed ProSHADE components, the command ```make remove``` needs to be issued to the makefile originally created by the CMake call. Please note that ```sudo``` may need to be used if the installation was done into the system folders and your current user does not have sufficient rights. ## Installing using pip The ProSHADE python module is also available (as a source distribution) on the PyPi repository. Therefore, the ProSHADE python module can be installed by simply issuing the following command; **however, this assumes that all the system dependencies as discussed in the [Standard System Dependencies](#standard-system-dependencies) section are already installed.** If any of them is missing, then a cryptic error message will ensue - consider yourself warned. ``` python -m pip install proshade ``` Alternatively, the module can be build and installed using pip directly from the ProSHADE GitHub repository ( https://github.com/michaltykac/proshade ) using the following command. This approach has the advantage that it takes the most current stable version, rather than being dependent on the authors not forgetting to update the PyPi repository. ``` python -m pip install git+https://github.com/michaltykac/proshade ``` Again, please note that the pip installation only wraps around the CMake installation and that CMake is still being run by pip in the background. Therefore, the same system dependencies are required. Moreover, if any of the system dependencies is missing or cannot be found, then a bit more cryptic error message will be printed by pip. **Warning:** When installing using *pip* on Windows, the *Command Prompt* window needs to be closed once the installation is complete before ProSHADE will work. This is because the installation makes changes to the PATH variable and these will not be reflected by any windows opened before the installation completes. ### Uninstalling pip installed module Should the user require to uninstall the python module and all associated data after they were installed globally using pip, the following standard pip command can achieve this task irrespective as to how exactly the proshade module was installed: ``` python -m pip uninstall proshade ``` # Input PDB files There are several caveats to inputting PDB files; most of these have to do with the fact that PDB files encode much more information than ProSHADE is intended to use. Therefore, ProSHADE is by default set to disregard information it does not need; however, if the user so requires, the information may be used, albeit it may pose some unexpected problems. ## Spacegroups By default, ProSHADE will ignore the PDB file encoded spacegroup and will instead force the P1 spacegroup onto the input files. The reason for this behaviour is that when computing the theoretical density map, some spacegroups will cause density from other cells to be added as well (*e.g.* P21 21 21). Since ProSHADE is intended to use the structure shape irrespective of the experimental method (*i.e.* irrespective of crystal packaging), having density from other cells would cause ProSHADE to perceive differences where the structures could be identical except for the spacegroup. To force ProSHADE to make use of the spacegroup, please supply the ```-u``` command line option. ## Waters By default, ProSHADE will remove all water molecules from any input PDB files. The reason is similar to above, as ProSHADE is intended to compare protein shapes and as waters are in most cases not an integral part of the protein, this behaviour is attempting to avoid situations where two identical structures with one having hundreds of waters and one not would be perceived by ProSHADE as significantly different. Should the user require the water molecules to be used by ProSHADE, please supply the ```-w``` command line option. ## Models There are examples of both, PDB files containing multiple models of the same structure (with minor differences, *e.g.* trajectory files) and PDB files which have their chains (or collections of chains) separated into different models. Given this state of affairs, ProSHADE will by default use only the first model of each input PDB file and will print a warning message (which can be supressed by setting verbosity below 0) for each file it reads which has more than one model. Should the user want to use all available models for the input PDB files, please supply ProSHADE with the ```-x``` command line option. # Using the ProSHADE binary The ProSHADE tool was developed in a modular fashion and the usage slightly changes depending on the functionality that is required. Nonetheless, care has been taken to make sure that identical or closely related features are controlled by the same command line arguments in all cases. Moreover, the GNU command-line options standard have been adhered to (through the ```getOpts``` library) and therefore the users familiar with other command-line tools should find the entering of command line arguments simple. The following subsections relate to examples of using different functionalities; for a full list of command line options, please use the **--help** command line option of the ProSHADE binary. ## Symmetry Detection In order to detect symmetry in either a co-ordinate input file or in a map input file, the ProSHADE executable needs to be supplied with the option **-S** or **--symmetry** and it will also require a single input file to be supplied using the **-f** option. These two options are the only mandatory options, although there are many optional values that the user can supply to supersede the default values and therefore modify the operation fo the ProSHADE executable to fit their purpose. One particular option regarding the symmetry detection mode should be noted; the **--reqSym** (or **-u**) option, which allows the user to state which symmetry they believe to exist in the structure. The allowed values for this command line argument are "Cx", "Dx", "T", "O" and "I", where the *x* should be an integer number specifying the fold of the requested symmetry. When this option is used, it removes the default behaviour of returning the "best" detected symmetry and instead the symmetry requested by the user is returned, if it can be found in the structure. Another noteworthy option is the **--center** or **-c** option, which tells ProSHADE **NOT** to center the internal map representation over the centre of density before running any processing of the map (default is centering and adding this option will turn centering off). This may be important as ProSHADE detects symmetries over the centre of the co-ordinates and therefore a non-centered map (map which does not have the centre of mass at the centre of box) will be found to have no symmetries even if these are present, just not over the co-ordinate/box centre. Alternatively, ProSHADE can attempt a procedure for finding the symmetry centre itself - to enable this procedure, please supply the **--symCentre** or **-I** option. This procedure will firstly remove phase from the internal density map and attempt symmetry detection over the Patterson map. Then, by applying the symmetry that is found in the Patterson map (if any), the symmetry centre can be found; however, please note that this will consume considerable extra computation time (approximately 3-4 times slower than when the procedure is disabled). It is also worth noting that there are several extra functionalities available for the symmetry detection mode when accessed programmatically (**i.e.** either through the dynamic C++ library or through the Python language module). These extra functionalities include direct access to a vector/list of all detected cyclic symmetries, list/vector of all other symmetry type detections (meaning a list of all detected dihedral, tetrahedral, ... symmetries and the cyclic axes forming them) and also the ability to compute all point group elements for any point group formed by a combination of ProSHADE detected cyclic point groups. For more details on these functinoalities, the users are invited to consult the *advancedAccess_symmetry.cpp/py* example files in the **examples** folder. To demonstrate how the tool can be run and the standard output for the symmetry mode of operation, the current version of the ProSHADE executable was used to detect the symmetry of a density map of the bacteriophage T4 portal protein with the PDB accession code 3JA7 (EMDB accession code 6324), which has the *C12* symmetry. The visualisation of the structure is shown in the following figure, while the output of the ProSHADE tool follows. It is also worth noting that ProSHADE will output its prediction as well as table showing how different FSC average threshold values would change its prediction. This table can be used by the user to manually decide if they agree with the ProSHADE prediction or if thay suspect a different symmetry may indeed be real. Finally, ProSHADE will also output the list of all detected symmetries, so that experienced user could manually check for any particuar symmetry they are interested in and also check for how much they trust the ProSHADE prediction overall. ![T4 Portal Protein](https://github.com/michaltykac/proshade/blob/experimental/proshade/documentation/ProSHADE_3JA7.jpg) ``` $: ./proshade -S -f ./emd_6324.map %package -n python3-proshade Summary: Protein Shape Description and Symmetry Detection (ProSHADE) python module Provides: python-proshade BuildRequires: python3-devel BuildRequires: python3-setuptools BuildRequires: python3-pip %description -n python3-proshade Protein Shape Description and Symmetry Detection version 0.7.6.6 (JUL 2022) # Introduction ProSHADE is a C++ language library and an associated tool providing functionalities for working with structural biology molecular structures. The library implements functions for computing shape-wise structural distances between pairs of molecules, detecting symmetry over the centre of mass (or centre of map) of a single structure, map re-sizing as well as matching density maps and PDB coordinate files to one another. The executable implemented in the ```bin.cpp``` file then allows easy access to these functionalities without the need for library linking, while the python modules provides easy access to the functionality from the python language. For help on how the executable should be used, refer to the ```-h``` option of it. For more details about the functionalities, see below. # Obtaining ProSHADE The most recent stable version of ProSHADE is available from the *master* branch of the GitHub repository https://github.com/michaltykac/proshade, from where it can be cloned using the git application or downloaded manually using the interface. More advanced users may be interested in obtaining the *development* or the *experimental* branches, which are available from the same link. The *experimental* branch is where I do all new development and it may or may not be currently compilable and/or working properly, while the *development* branch should always compile, but is more likely to contain bugs and issues as it is the code before proper testing. # Index - [Introduction](#introduction) - [Obtaining ProSHADE](#obtaining-proshade) - [Index](#index) - [Installation](#installation) - [Standard System Dependencies](#standard-system-dependencies) - [Installing python](#installing-python) - [Installing standard system dependencies on MacOS](#installing-standard-system-dependencies-on-macos) - [Installing standard system dependencies using apt)](#installing-standard-system-dependencies-using-apt) - [Installing standard system dependencies using ZYpp](#installing-standard-system-dependencies-using-zypp) - [Installing standard system dependencies using yum](#installing-standard-system-dependencies-using-yum) - [Other dependencies](#other-dependencies) - [Installing on Windows](#installing-on-windows) - [Installing CMake](#installing-cmake) - [Installing git](#installing-git) - [Installing Build Tools for Visual Studio](#installing-build-tools-for-visual-studio) - [Installing ProSHADE](#installing-proshade) - [Setting ProSHADE PATH](#setting-proshade-path) - [Installing using CMake on Unix](#installing-using-cmake-on-unix) - [CMake options](#cmake-options) - [Uninstall using CMake](#uninstall-using-cmake) - [Installation using pip](#installing-using-pip) - [Uninstalling pip installed module](#uninstalling-pip-installed-module) - [Input PDB files](#input-pdb-files) - [Spacegroups](#spacegroups) - [Waters](#waters) - [Models](#models) - [Using the ProSHADE binary](#using-the-proshade-binary) - [Symmetry Detection](#symmetry-detection) - [Shape similarity distances](#shape-similarity-distances) - [Re-boxing structures](#re-boxing-structures) - [Optimal rotation and translation](#optimal-rotation-and-translation) - [Using the ProSHADE library](#using-the-proshade-library) - [Linking against the ProSHADE library](#linking-against-the-proshade-library) - [Examples of ProSHADE library usage](#examples-of-proshade-library-usage) - [Using the Python module](#using-the-python-module) - [Python module examples](#python-module-examples) - [Simple access](#simple-access) - [Advanced access](#advanced-access) - [Direct access](#direct-access) - [Reading a structure from file](#reading-a-structure-from-file) - [Reading co-ordinates from gemmi](#reading-co-ordinates-from-gemmi) - [Creating ProSHADE_data object from map](#creating-proshade_data-object-from-map) - [3D arrays](#3d-arrays) - [Writing out maps](#writing-out-maps) - [Getting back the ProSHADE internal representation map](#getting-back-the-proshade-internal-representation-map) - [Computing standard ProSHADE tasks](#computing-standard-proshade-tasks) - [Computing the spherical harmonics decomposition](#computing-the-spherical-harmonics-decomposition) - [Computing the self-rotation function](#computing-the-self-rotation-function) - [Computing the optimal rotation function](#computing-the-optimal-rotation-function) - [Finding the optimal rotation](#finding-the-optimal-rotation) - [Rotating the internal map representation](#rotating-the-internal-map-representation) - [Computing the translation function](#computing-the-translation-function) - [Writing out resulting structures](#writing-out-resulting-structures) # Installation The installation of the ProSHADE software should be done using the CMake system and the supplied CMakeLists.txt file. The minimal requiered version of CMake is 2.6, however, python modules and single source file compilation will not be available unless CMake version 3.4 or higher is used. The CMakeLists.txt file assumes the standard system dependencies are installed in the system folders; for a full list of standard system dependencies, please see the section [Standard System Dependencies](#standard-system-dependencies). Once all of the standard system dependencies are installed CMake can be run to create the make files as described in the section [Installing using CMake](#installing-using-cmake). Alternatively, ProSHADE also provides *setup.py* script, which wraps the CMake installation - please refer to the [Installation using pip](#installation-using-pip) section of this documentation for more details. The main difference between these two installation approaches is that using CMake allows building the executable and the dynamic C++ library, but will install the python module only locally, while installing using pip will install only the python module, but will install it globally. Combining these two installations is not a problem. Moreover, if CMake is used to build ProSHADE directly, then the user may make use of several options that can be used to modify the default behaviour of the installation; these typically drive the installation locations and dependencies paths in the case of non-standard dependency location. Please see the section [CMake options](#cmake-options) for details as to how to use these options and what do they do. Please note that while the ProSHADE code is C++ 98 standard compatible, some of the dependencies do require at least partial support for the C++ 11 standard and building python module requires full C++ 11 compliant compiler. ## Standard System Dependencies Generally, the following list of standard system libraries and utilities are required for successfull installation of ProSHADE on Unix systems: - **gcc** - **g++** - **make** - **cmake** - **fftw3-dev** - **liblapack-dev** - **git** - **zlib** - **python** with **numpy** This list is somewhat different for Windows systems, as ProSHADE contains 64-bit libraries for most of the dependencies already prepared, thus limiting the list. This, however, means that ProSHADE can only be installed on Windows10 64-bit systems and currently does neither supprt the 32-bit systems, nor the older Windows systems (7, Vista, XP, ...): - **cl** - **cmake** - **git** - **python** with **numpy** CMake should complain and issue a reasonably decipherable error messages if any of these dependencies are missing. ### Installing python Python is not required for ProSHADE binary and library installation, but it is necessary to have it installed for successfull ProSHADE python module installation. Now, while most modern Unix systems come with some version of the python language pre-installed (although Windows does not), it seems reasonable to assume that users who are interested in using the ProSHADE python module do have their preferred version of python already installed and set as the default system python (meaning that the ```python``` command points to the python executable that the user wants the ProSHADE module to be installed for). Should the user not have any python version installed or should the user be interested in having multiple versions, the Anaconda environment ( https://www.anaconda.com/products/individual ) can be recommended for all systems supported by ProSHADE. Of course, there are alternatives for installation of python and management of various environments and ProSHADE does not care which is being used. ### Installing standard system dependencies on MacOS Assuming a clean MacOS, the ProSHADE dependencies can be installed as follows: Firstly, the XCode tools should be installed from Apple - this can be achieved by issuing the command: ``` xcode-select --install ``` Next, CMake will need to be installed manually; that is, starting with downloading the source codes from https://github.com/Kitware/CMake/releases/download/v3.19.2/cmake-3.19.2.tar.gz . After moving the downloaded file to where the codes should live and navigating to the same location in Terminal, please use the following commands to install CMake: ``` tar -zxvf ./cmake-3.19.2.tar.gz cd ./cmake-3.19.2 ./bootstrap make sudo make install ``` Finally, some MacOS systems do not have the FFTW3 library pre-installed. If this is your case, then please use the following commands to install FFTW3 manually: Firstly, download the source codes from here: http://www.fftw.org/fftw-3.3.9.tar.gz . After moving the downloaded file to where the codes should live and navigating to the same location in Terminal, please use the following commands to install FFTW3: ``` tar -zxvf ./fftw-3.3.9.tar cd ./fftw-3.3.9 ./configure --enable-shared make sudo make install ``` Now, ProSHADE should be automaically installable using the CMake system. ### Installing standard system dependencies using apt The *APT* package manager can be used to install all the system dependencies of ProSHADE using the following command. ``` sudo apt-get install gcc g++ make cmake git fftw3-dev liblapack-dev zlib1g-dev ``` After this, ProSHADE should by automatically installable using the CMake system. ### Installing standard system dependencies using ZYpp The *ZYpp* package manager and the associated *zypper* command-line tool can be used install all the system dependencies of ProSHADE as follows: ``` sudo zypper install gcc gcc-c++ git cmake fftw3-devel lapack-devel zlib-devel ``` After this, ProSHADE should by automatically installable using the CMake system. ### Installing standard system dependencies using yum Firstly, at least on some systems, the *yum* package manager may not be using the *powertools* repository; however, some of ProSHADE dependencies are kept there. Therefore, the user may need to enable the *powertools* repository by issuing the folloing commands: ``` sudo yum install dnf-plugins-core sudo yum config-manager --set-enabled powertools ``` Then, the *yum* package manager can be used install all the system dependencies of ProSHADE as follows: ``` sudo yum install gcc gcc-c++ make cmake fftw3-devel lapack-devel zlib-devel ``` After this, ProSHADE should by automatically installable using the CMake system. ## Other dependencies ProSHADE also depends on the *Gemmi* and *SOFT2.0* libraries. The installation of these libraries is automated in the CMake scripts and therefore does not require any user input (*SOFT2.0* library is supplied with the ProSHADE code and will be installed locally by the ProSHADE CMake installation). Please note that these dependencies do have their own licences (the Mozilla Public License for *Gemmi* and the GPL v3 licence for *SOFT2.0*) and therefore this may limit the ProSHADE usage for some users beyond the ProSHADE copyright and licence itself. ## Installing on Windows As mentioned above, ProSHADE currently only supports Windows10 64-bit systems and cannot be simply installed on other Windows systems. In order to install ProSHADE on a Windows10 64-bit machine, the user is required to firstly have installed some basic pre-requisities. ### Installing CMake CMake can be installed on Windows using the 64-bit MSI installer (binary distribution) available from https://cmake.org/download . During the installation, please make sure that the option to *Add CMake to the system PATH* is selected (it does not matter to ProSHADE if it is for all users or just for the current user). ### Installing git Git can be installed on Windows by downloading the 64-bit Windows Setup installer from https://git-scm.com/download/win . The installer asks for many options, the only important one for ProSHADE installation is that in the section "Adjusting your PATH environment" it is required that the option *Use Git from Git Bash only* is **NOT** selected. This makes sure that the git executable is in the system PATH. ### Installing Build Tools for Visual Studio Sadly, the Authors are not aware of any simple way of installing the Microsoft C and C++ compilers and linker controlling tool - **cl.exe** except for installing the full Visual Studio or the Build Tools for Visual Studio. This will require well over 7.5GB of space on your hard-drive and the download is well over 1.5GB. Nonetheless, it is the main Windows compiler and linker and therefore ProSHADE cannot be installed on Windows without it. To install the Build Tools for Visual Studio, please download the installer from Microsoft at https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022 and in the Workload selection screen select the *Desktop development with C++* option. The rest of the installtion should be automatic. ### Installing ProSHADE Once all of the above dependencies are installed, the ProSHADE python module can now be installed using the pip installation as described in the [Installing using pip ](#installing-using-pip) section. Should the user require installation from the Command Prompt, they will need to open the *Developer Command Prompt for VS 2022* (or the appropriate version the MS Visual Studio they have installed) and type the following commands (replacing the \path\to\proshade with the appropriate path on their machine to the location where they want ProSHADE codes to be stored). Please note that you may need to run the command prompt as an administrator in order to be able to install into the system folders (i.e. C:\Program Files). Also, the same CMake options apply as discussed in section [CMake options](#cmake-options): ``` cd \path\to\proshade git clone https://github.com/michaltykac/proshade mkdir build cd .\build cmake ..\proshade\proshade cmake --build . --config Release cmake --install . ``` ### Setting ProSHADE PATH Finally, ProSHADE now needs to be able to locate the dependency libraries before it can be run on Windows. The simplest way of allowing for this is the add the ProSHADE libraries folder into the system PATH. This can be done by opening the *Control Panel* and selecting the *System and Security* option. In the new window, please select the *System* option and in the next window click the *Advanced system settings* option on the right-hand side panel. In the next window, please click on the *Environment Variables...* button, which will open the penultimate window. In here, in the *System variables* section, please click on the variable named *Path* and then click on the *Edit...* button. This opens the last window, where the *New* button needs to be clicked, immediately followed by clicking the *Browse...* button. In the file selector screen, please navigate to the \path\to\proshade location used in the previous section and then select the following folders: proshade\proshade\winLibs\x64\DLLs and then click on the *OK* button on all open windows which have one. Once the path is set, you can use ProSHADE from any Command Prompt window (not only the Developer Command Prompt used before), although you will have to close and re-open all currently open command prompt windows if you want to use ProSHADE in them. ## Installing using CMake on Unix CMake is the default ProSHADE installation tool and if the binary or the library is needed, then it is the only installation option. The python module can also be build using CMake, but it will be installed only locally and all python scripts will need to add the installation location to their PATH. Alternatively, if the python module is what the user is after, then it can be installed globally using pip - please see the [Installation using pip](#installation-using-pip ) section for more details. In order to install ProSHADE, first please check that all the [Standard System Dependencies](#standard-system-dependencies) are installed, preferably using a package management system such as *apt*, *yum*, *zypper*, *homebrew*, *etc.*. Next, please navigate to any folder to which you would like to write the install files; some find it useful to create a ```build``` folder in the ProSHADE folder in order to keep the install files in the same location as the source codes. Then, issue the following set of commands, changing the ```\path\to\ProSHADE``` to the correct path on your system and adding any required [CMake options](#cmake-options) to the first command. Please note that ```sudo``` may be required for the ```make install``` command if you are installing into the system folders. ``` cmake \path\to\ProSHADE\proshade make make install ``` ### CMake options **-DINSTALL_LOCALLY=ON** or **OFF** - This option is used to decide whether all the installed ProSHADE components are installed in the local source directory (value **ON** ) or whether they are instead installed in the system folders (value **OFF** ) as determined by CMake. This option applies to the binary, the C++ library and the headers as well. Please note that the python module will be installed locally; if it is to be installed globally, please use the pip installation described in the section [Installation using pip](#installation-using-pip ). **-DINSTALL_BIN_DIR=/path** - This option is used to manually specify the folder to which the ProSHADE binary shold be installed into. **-DINSTALL_LIB_DIR=/path** - This option is used to manually specify the folder to which the ProSHADE C++ library should be installed into. **-DINSTALL_INC_DIR=/path** - This option is used to specify the folder to which the ProSHADE header files required by the library should be installed into. **-DCUSTOM_FFTW3_LIB_PATH=/path** - This option is used to supply the path to the libfftw3.a/so/dylib in the case where ProSHADE CMake installation fails to detect the FFTW3 dependency. This is typically the case when FFTW3 is installed outside of the standard FFTW3 installation locations. **-DCUSTOM_FFTW3_INC_PATH=/path** - This option is used to supply the path to the fftw3.h file in the case where ProSHADE CMake installation fails to detect the FFTW3 dependency. This is typically the case when FFTW3 is installed outside of the standard FFTW3 installation locations. **-DCUSTOM_LAPACK_LIB_PATH=/path** - This option is used to supply the path to the liblapack.a/so/dylib in the case where ProSHADE CMake installation fails to detect the LAPACK dependency. This is typically the case when the LAPACK is installed outside of the standard LAPACK installation locations. **-DBUILD_PYTHON=TRUE** or **FALSE** - This option controls whether python modules should be build or not. If you have installed ProSHADE python modules using pip or if you are not interested in using the python modules, you may set this option to FALSE, otherwise the python module will be built for the currently used python. ### Uninstall using CMake To remove the installed ProSHADE components, the command ```make remove``` needs to be issued to the makefile originally created by the CMake call. Please note that ```sudo``` may need to be used if the installation was done into the system folders and your current user does not have sufficient rights. ## Installing using pip The ProSHADE python module is also available (as a source distribution) on the PyPi repository. Therefore, the ProSHADE python module can be installed by simply issuing the following command; **however, this assumes that all the system dependencies as discussed in the [Standard System Dependencies](#standard-system-dependencies) section are already installed.** If any of them is missing, then a cryptic error message will ensue - consider yourself warned. ``` python -m pip install proshade ``` Alternatively, the module can be build and installed using pip directly from the ProSHADE GitHub repository ( https://github.com/michaltykac/proshade ) using the following command. This approach has the advantage that it takes the most current stable version, rather than being dependent on the authors not forgetting to update the PyPi repository. ``` python -m pip install git+https://github.com/michaltykac/proshade ``` Again, please note that the pip installation only wraps around the CMake installation and that CMake is still being run by pip in the background. Therefore, the same system dependencies are required. Moreover, if any of the system dependencies is missing or cannot be found, then a bit more cryptic error message will be printed by pip. **Warning:** When installing using *pip* on Windows, the *Command Prompt* window needs to be closed once the installation is complete before ProSHADE will work. This is because the installation makes changes to the PATH variable and these will not be reflected by any windows opened before the installation completes. ### Uninstalling pip installed module Should the user require to uninstall the python module and all associated data after they were installed globally using pip, the following standard pip command can achieve this task irrespective as to how exactly the proshade module was installed: ``` python -m pip uninstall proshade ``` # Input PDB files There are several caveats to inputting PDB files; most of these have to do with the fact that PDB files encode much more information than ProSHADE is intended to use. Therefore, ProSHADE is by default set to disregard information it does not need; however, if the user so requires, the information may be used, albeit it may pose some unexpected problems. ## Spacegroups By default, ProSHADE will ignore the PDB file encoded spacegroup and will instead force the P1 spacegroup onto the input files. The reason for this behaviour is that when computing the theoretical density map, some spacegroups will cause density from other cells to be added as well (*e.g.* P21 21 21). Since ProSHADE is intended to use the structure shape irrespective of the experimental method (*i.e.* irrespective of crystal packaging), having density from other cells would cause ProSHADE to perceive differences where the structures could be identical except for the spacegroup. To force ProSHADE to make use of the spacegroup, please supply the ```-u``` command line option. ## Waters By default, ProSHADE will remove all water molecules from any input PDB files. The reason is similar to above, as ProSHADE is intended to compare protein shapes and as waters are in most cases not an integral part of the protein, this behaviour is attempting to avoid situations where two identical structures with one having hundreds of waters and one not would be perceived by ProSHADE as significantly different. Should the user require the water molecules to be used by ProSHADE, please supply the ```-w``` command line option. ## Models There are examples of both, PDB files containing multiple models of the same structure (with minor differences, *e.g.* trajectory files) and PDB files which have their chains (or collections of chains) separated into different models. Given this state of affairs, ProSHADE will by default use only the first model of each input PDB file and will print a warning message (which can be supressed by setting verbosity below 0) for each file it reads which has more than one model. Should the user want to use all available models for the input PDB files, please supply ProSHADE with the ```-x``` command line option. # Using the ProSHADE binary The ProSHADE tool was developed in a modular fashion and the usage slightly changes depending on the functionality that is required. Nonetheless, care has been taken to make sure that identical or closely related features are controlled by the same command line arguments in all cases. Moreover, the GNU command-line options standard have been adhered to (through the ```getOpts``` library) and therefore the users familiar with other command-line tools should find the entering of command line arguments simple. The following subsections relate to examples of using different functionalities; for a full list of command line options, please use the **--help** command line option of the ProSHADE binary. ## Symmetry Detection In order to detect symmetry in either a co-ordinate input file or in a map input file, the ProSHADE executable needs to be supplied with the option **-S** or **--symmetry** and it will also require a single input file to be supplied using the **-f** option. These two options are the only mandatory options, although there are many optional values that the user can supply to supersede the default values and therefore modify the operation fo the ProSHADE executable to fit their purpose. One particular option regarding the symmetry detection mode should be noted; the **--reqSym** (or **-u**) option, which allows the user to state which symmetry they believe to exist in the structure. The allowed values for this command line argument are "Cx", "Dx", "T", "O" and "I", where the *x* should be an integer number specifying the fold of the requested symmetry. When this option is used, it removes the default behaviour of returning the "best" detected symmetry and instead the symmetry requested by the user is returned, if it can be found in the structure. Another noteworthy option is the **--center** or **-c** option, which tells ProSHADE **NOT** to center the internal map representation over the centre of density before running any processing of the map (default is centering and adding this option will turn centering off). This may be important as ProSHADE detects symmetries over the centre of the co-ordinates and therefore a non-centered map (map which does not have the centre of mass at the centre of box) will be found to have no symmetries even if these are present, just not over the co-ordinate/box centre. Alternatively, ProSHADE can attempt a procedure for finding the symmetry centre itself - to enable this procedure, please supply the **--symCentre** or **-I** option. This procedure will firstly remove phase from the internal density map and attempt symmetry detection over the Patterson map. Then, by applying the symmetry that is found in the Patterson map (if any), the symmetry centre can be found; however, please note that this will consume considerable extra computation time (approximately 3-4 times slower than when the procedure is disabled). It is also worth noting that there are several extra functionalities available for the symmetry detection mode when accessed programmatically (**i.e.** either through the dynamic C++ library or through the Python language module). These extra functionalities include direct access to a vector/list of all detected cyclic symmetries, list/vector of all other symmetry type detections (meaning a list of all detected dihedral, tetrahedral, ... symmetries and the cyclic axes forming them) and also the ability to compute all point group elements for any point group formed by a combination of ProSHADE detected cyclic point groups. For more details on these functinoalities, the users are invited to consult the *advancedAccess_symmetry.cpp/py* example files in the **examples** folder. To demonstrate how the tool can be run and the standard output for the symmetry mode of operation, the current version of the ProSHADE executable was used to detect the symmetry of a density map of the bacteriophage T4 portal protein with the PDB accession code 3JA7 (EMDB accession code 6324), which has the *C12* symmetry. The visualisation of the structure is shown in the following figure, while the output of the ProSHADE tool follows. It is also worth noting that ProSHADE will output its prediction as well as table showing how different FSC average threshold values would change its prediction. This table can be used by the user to manually decide if they agree with the ProSHADE prediction or if thay suspect a different symmetry may indeed be real. Finally, ProSHADE will also output the list of all detected symmetries, so that experienced user could manually check for any particuar symmetry they are interested in and also check for how much they trust the ProSHADE prediction overall. ![T4 Portal Protein](https://github.com/michaltykac/proshade/blob/experimental/proshade/documentation/ProSHADE_3JA7.jpg) ``` $: ./proshade -S -f ./emd_6324.map %package help Summary: Development documents and examples for proshade Provides: python3-proshade-doc %description help Protein Shape Description and Symmetry Detection version 0.7.6.6 (JUL 2022) # Introduction ProSHADE is a C++ language library and an associated tool providing functionalities for working with structural biology molecular structures. The library implements functions for computing shape-wise structural distances between pairs of molecules, detecting symmetry over the centre of mass (or centre of map) of a single structure, map re-sizing as well as matching density maps and PDB coordinate files to one another. The executable implemented in the ```bin.cpp``` file then allows easy access to these functionalities without the need for library linking, while the python modules provides easy access to the functionality from the python language. For help on how the executable should be used, refer to the ```-h``` option of it. For more details about the functionalities, see below. # Obtaining ProSHADE The most recent stable version of ProSHADE is available from the *master* branch of the GitHub repository https://github.com/michaltykac/proshade, from where it can be cloned using the git application or downloaded manually using the interface. More advanced users may be interested in obtaining the *development* or the *experimental* branches, which are available from the same link. The *experimental* branch is where I do all new development and it may or may not be currently compilable and/or working properly, while the *development* branch should always compile, but is more likely to contain bugs and issues as it is the code before proper testing. # Index - [Introduction](#introduction) - [Obtaining ProSHADE](#obtaining-proshade) - [Index](#index) - [Installation](#installation) - [Standard System Dependencies](#standard-system-dependencies) - [Installing python](#installing-python) - [Installing standard system dependencies on MacOS](#installing-standard-system-dependencies-on-macos) - [Installing standard system dependencies using apt)](#installing-standard-system-dependencies-using-apt) - [Installing standard system dependencies using ZYpp](#installing-standard-system-dependencies-using-zypp) - [Installing standard system dependencies using yum](#installing-standard-system-dependencies-using-yum) - [Other dependencies](#other-dependencies) - [Installing on Windows](#installing-on-windows) - [Installing CMake](#installing-cmake) - [Installing git](#installing-git) - [Installing Build Tools for Visual Studio](#installing-build-tools-for-visual-studio) - [Installing ProSHADE](#installing-proshade) - [Setting ProSHADE PATH](#setting-proshade-path) - [Installing using CMake on Unix](#installing-using-cmake-on-unix) - [CMake options](#cmake-options) - [Uninstall using CMake](#uninstall-using-cmake) - [Installation using pip](#installing-using-pip) - [Uninstalling pip installed module](#uninstalling-pip-installed-module) - [Input PDB files](#input-pdb-files) - [Spacegroups](#spacegroups) - [Waters](#waters) - [Models](#models) - [Using the ProSHADE binary](#using-the-proshade-binary) - [Symmetry Detection](#symmetry-detection) - [Shape similarity distances](#shape-similarity-distances) - [Re-boxing structures](#re-boxing-structures) - [Optimal rotation and translation](#optimal-rotation-and-translation) - [Using the ProSHADE library](#using-the-proshade-library) - [Linking against the ProSHADE library](#linking-against-the-proshade-library) - [Examples of ProSHADE library usage](#examples-of-proshade-library-usage) - [Using the Python module](#using-the-python-module) - [Python module examples](#python-module-examples) - [Simple access](#simple-access) - [Advanced access](#advanced-access) - [Direct access](#direct-access) - [Reading a structure from file](#reading-a-structure-from-file) - [Reading co-ordinates from gemmi](#reading-co-ordinates-from-gemmi) - [Creating ProSHADE_data object from map](#creating-proshade_data-object-from-map) - [3D arrays](#3d-arrays) - [Writing out maps](#writing-out-maps) - [Getting back the ProSHADE internal representation map](#getting-back-the-proshade-internal-representation-map) - [Computing standard ProSHADE tasks](#computing-standard-proshade-tasks) - [Computing the spherical harmonics decomposition](#computing-the-spherical-harmonics-decomposition) - [Computing the self-rotation function](#computing-the-self-rotation-function) - [Computing the optimal rotation function](#computing-the-optimal-rotation-function) - [Finding the optimal rotation](#finding-the-optimal-rotation) - [Rotating the internal map representation](#rotating-the-internal-map-representation) - [Computing the translation function](#computing-the-translation-function) - [Writing out resulting structures](#writing-out-resulting-structures) # Installation The installation of the ProSHADE software should be done using the CMake system and the supplied CMakeLists.txt file. The minimal requiered version of CMake is 2.6, however, python modules and single source file compilation will not be available unless CMake version 3.4 or higher is used. The CMakeLists.txt file assumes the standard system dependencies are installed in the system folders; for a full list of standard system dependencies, please see the section [Standard System Dependencies](#standard-system-dependencies). Once all of the standard system dependencies are installed CMake can be run to create the make files as described in the section [Installing using CMake](#installing-using-cmake). Alternatively, ProSHADE also provides *setup.py* script, which wraps the CMake installation - please refer to the [Installation using pip](#installation-using-pip) section of this documentation for more details. The main difference between these two installation approaches is that using CMake allows building the executable and the dynamic C++ library, but will install the python module only locally, while installing using pip will install only the python module, but will install it globally. Combining these two installations is not a problem. Moreover, if CMake is used to build ProSHADE directly, then the user may make use of several options that can be used to modify the default behaviour of the installation; these typically drive the installation locations and dependencies paths in the case of non-standard dependency location. Please see the section [CMake options](#cmake-options) for details as to how to use these options and what do they do. Please note that while the ProSHADE code is C++ 98 standard compatible, some of the dependencies do require at least partial support for the C++ 11 standard and building python module requires full C++ 11 compliant compiler. ## Standard System Dependencies Generally, the following list of standard system libraries and utilities are required for successfull installation of ProSHADE on Unix systems: - **gcc** - **g++** - **make** - **cmake** - **fftw3-dev** - **liblapack-dev** - **git** - **zlib** - **python** with **numpy** This list is somewhat different for Windows systems, as ProSHADE contains 64-bit libraries for most of the dependencies already prepared, thus limiting the list. This, however, means that ProSHADE can only be installed on Windows10 64-bit systems and currently does neither supprt the 32-bit systems, nor the older Windows systems (7, Vista, XP, ...): - **cl** - **cmake** - **git** - **python** with **numpy** CMake should complain and issue a reasonably decipherable error messages if any of these dependencies are missing. ### Installing python Python is not required for ProSHADE binary and library installation, but it is necessary to have it installed for successfull ProSHADE python module installation. Now, while most modern Unix systems come with some version of the python language pre-installed (although Windows does not), it seems reasonable to assume that users who are interested in using the ProSHADE python module do have their preferred version of python already installed and set as the default system python (meaning that the ```python``` command points to the python executable that the user wants the ProSHADE module to be installed for). Should the user not have any python version installed or should the user be interested in having multiple versions, the Anaconda environment ( https://www.anaconda.com/products/individual ) can be recommended for all systems supported by ProSHADE. Of course, there are alternatives for installation of python and management of various environments and ProSHADE does not care which is being used. ### Installing standard system dependencies on MacOS Assuming a clean MacOS, the ProSHADE dependencies can be installed as follows: Firstly, the XCode tools should be installed from Apple - this can be achieved by issuing the command: ``` xcode-select --install ``` Next, CMake will need to be installed manually; that is, starting with downloading the source codes from https://github.com/Kitware/CMake/releases/download/v3.19.2/cmake-3.19.2.tar.gz . After moving the downloaded file to where the codes should live and navigating to the same location in Terminal, please use the following commands to install CMake: ``` tar -zxvf ./cmake-3.19.2.tar.gz cd ./cmake-3.19.2 ./bootstrap make sudo make install ``` Finally, some MacOS systems do not have the FFTW3 library pre-installed. If this is your case, then please use the following commands to install FFTW3 manually: Firstly, download the source codes from here: http://www.fftw.org/fftw-3.3.9.tar.gz . After moving the downloaded file to where the codes should live and navigating to the same location in Terminal, please use the following commands to install FFTW3: ``` tar -zxvf ./fftw-3.3.9.tar cd ./fftw-3.3.9 ./configure --enable-shared make sudo make install ``` Now, ProSHADE should be automaically installable using the CMake system. ### Installing standard system dependencies using apt The *APT* package manager can be used to install all the system dependencies of ProSHADE using the following command. ``` sudo apt-get install gcc g++ make cmake git fftw3-dev liblapack-dev zlib1g-dev ``` After this, ProSHADE should by automatically installable using the CMake system. ### Installing standard system dependencies using ZYpp The *ZYpp* package manager and the associated *zypper* command-line tool can be used install all the system dependencies of ProSHADE as follows: ``` sudo zypper install gcc gcc-c++ git cmake fftw3-devel lapack-devel zlib-devel ``` After this, ProSHADE should by automatically installable using the CMake system. ### Installing standard system dependencies using yum Firstly, at least on some systems, the *yum* package manager may not be using the *powertools* repository; however, some of ProSHADE dependencies are kept there. Therefore, the user may need to enable the *powertools* repository by issuing the folloing commands: ``` sudo yum install dnf-plugins-core sudo yum config-manager --set-enabled powertools ``` Then, the *yum* package manager can be used install all the system dependencies of ProSHADE as follows: ``` sudo yum install gcc gcc-c++ make cmake fftw3-devel lapack-devel zlib-devel ``` After this, ProSHADE should by automatically installable using the CMake system. ## Other dependencies ProSHADE also depends on the *Gemmi* and *SOFT2.0* libraries. The installation of these libraries is automated in the CMake scripts and therefore does not require any user input (*SOFT2.0* library is supplied with the ProSHADE code and will be installed locally by the ProSHADE CMake installation). Please note that these dependencies do have their own licences (the Mozilla Public License for *Gemmi* and the GPL v3 licence for *SOFT2.0*) and therefore this may limit the ProSHADE usage for some users beyond the ProSHADE copyright and licence itself. ## Installing on Windows As mentioned above, ProSHADE currently only supports Windows10 64-bit systems and cannot be simply installed on other Windows systems. In order to install ProSHADE on a Windows10 64-bit machine, the user is required to firstly have installed some basic pre-requisities. ### Installing CMake CMake can be installed on Windows using the 64-bit MSI installer (binary distribution) available from https://cmake.org/download . During the installation, please make sure that the option to *Add CMake to the system PATH* is selected (it does not matter to ProSHADE if it is for all users or just for the current user). ### Installing git Git can be installed on Windows by downloading the 64-bit Windows Setup installer from https://git-scm.com/download/win . The installer asks for many options, the only important one for ProSHADE installation is that in the section "Adjusting your PATH environment" it is required that the option *Use Git from Git Bash only* is **NOT** selected. This makes sure that the git executable is in the system PATH. ### Installing Build Tools for Visual Studio Sadly, the Authors are not aware of any simple way of installing the Microsoft C and C++ compilers and linker controlling tool - **cl.exe** except for installing the full Visual Studio or the Build Tools for Visual Studio. This will require well over 7.5GB of space on your hard-drive and the download is well over 1.5GB. Nonetheless, it is the main Windows compiler and linker and therefore ProSHADE cannot be installed on Windows without it. To install the Build Tools for Visual Studio, please download the installer from Microsoft at https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022 and in the Workload selection screen select the *Desktop development with C++* option. The rest of the installtion should be automatic. ### Installing ProSHADE Once all of the above dependencies are installed, the ProSHADE python module can now be installed using the pip installation as described in the [Installing using pip ](#installing-using-pip) section. Should the user require installation from the Command Prompt, they will need to open the *Developer Command Prompt for VS 2022* (or the appropriate version the MS Visual Studio they have installed) and type the following commands (replacing the \path\to\proshade with the appropriate path on their machine to the location where they want ProSHADE codes to be stored). Please note that you may need to run the command prompt as an administrator in order to be able to install into the system folders (i.e. C:\Program Files). Also, the same CMake options apply as discussed in section [CMake options](#cmake-options): ``` cd \path\to\proshade git clone https://github.com/michaltykac/proshade mkdir build cd .\build cmake ..\proshade\proshade cmake --build . --config Release cmake --install . ``` ### Setting ProSHADE PATH Finally, ProSHADE now needs to be able to locate the dependency libraries before it can be run on Windows. The simplest way of allowing for this is the add the ProSHADE libraries folder into the system PATH. This can be done by opening the *Control Panel* and selecting the *System and Security* option. In the new window, please select the *System* option and in the next window click the *Advanced system settings* option on the right-hand side panel. In the next window, please click on the *Environment Variables...* button, which will open the penultimate window. In here, in the *System variables* section, please click on the variable named *Path* and then click on the *Edit...* button. This opens the last window, where the *New* button needs to be clicked, immediately followed by clicking the *Browse...* button. In the file selector screen, please navigate to the \path\to\proshade location used in the previous section and then select the following folders: proshade\proshade\winLibs\x64\DLLs and then click on the *OK* button on all open windows which have one. Once the path is set, you can use ProSHADE from any Command Prompt window (not only the Developer Command Prompt used before), although you will have to close and re-open all currently open command prompt windows if you want to use ProSHADE in them. ## Installing using CMake on Unix CMake is the default ProSHADE installation tool and if the binary or the library is needed, then it is the only installation option. The python module can also be build using CMake, but it will be installed only locally and all python scripts will need to add the installation location to their PATH. Alternatively, if the python module is what the user is after, then it can be installed globally using pip - please see the [Installation using pip](#installation-using-pip ) section for more details. In order to install ProSHADE, first please check that all the [Standard System Dependencies](#standard-system-dependencies) are installed, preferably using a package management system such as *apt*, *yum*, *zypper*, *homebrew*, *etc.*. Next, please navigate to any folder to which you would like to write the install files; some find it useful to create a ```build``` folder in the ProSHADE folder in order to keep the install files in the same location as the source codes. Then, issue the following set of commands, changing the ```\path\to\ProSHADE``` to the correct path on your system and adding any required [CMake options](#cmake-options) to the first command. Please note that ```sudo``` may be required for the ```make install``` command if you are installing into the system folders. ``` cmake \path\to\ProSHADE\proshade make make install ``` ### CMake options **-DINSTALL_LOCALLY=ON** or **OFF** - This option is used to decide whether all the installed ProSHADE components are installed in the local source directory (value **ON** ) or whether they are instead installed in the system folders (value **OFF** ) as determined by CMake. This option applies to the binary, the C++ library and the headers as well. Please note that the python module will be installed locally; if it is to be installed globally, please use the pip installation described in the section [Installation using pip](#installation-using-pip ). **-DINSTALL_BIN_DIR=/path** - This option is used to manually specify the folder to which the ProSHADE binary shold be installed into. **-DINSTALL_LIB_DIR=/path** - This option is used to manually specify the folder to which the ProSHADE C++ library should be installed into. **-DINSTALL_INC_DIR=/path** - This option is used to specify the folder to which the ProSHADE header files required by the library should be installed into. **-DCUSTOM_FFTW3_LIB_PATH=/path** - This option is used to supply the path to the libfftw3.a/so/dylib in the case where ProSHADE CMake installation fails to detect the FFTW3 dependency. This is typically the case when FFTW3 is installed outside of the standard FFTW3 installation locations. **-DCUSTOM_FFTW3_INC_PATH=/path** - This option is used to supply the path to the fftw3.h file in the case where ProSHADE CMake installation fails to detect the FFTW3 dependency. This is typically the case when FFTW3 is installed outside of the standard FFTW3 installation locations. **-DCUSTOM_LAPACK_LIB_PATH=/path** - This option is used to supply the path to the liblapack.a/so/dylib in the case where ProSHADE CMake installation fails to detect the LAPACK dependency. This is typically the case when the LAPACK is installed outside of the standard LAPACK installation locations. **-DBUILD_PYTHON=TRUE** or **FALSE** - This option controls whether python modules should be build or not. If you have installed ProSHADE python modules using pip or if you are not interested in using the python modules, you may set this option to FALSE, otherwise the python module will be built for the currently used python. ### Uninstall using CMake To remove the installed ProSHADE components, the command ```make remove``` needs to be issued to the makefile originally created by the CMake call. Please note that ```sudo``` may need to be used if the installation was done into the system folders and your current user does not have sufficient rights. ## Installing using pip The ProSHADE python module is also available (as a source distribution) on the PyPi repository. Therefore, the ProSHADE python module can be installed by simply issuing the following command; **however, this assumes that all the system dependencies as discussed in the [Standard System Dependencies](#standard-system-dependencies) section are already installed.** If any of them is missing, then a cryptic error message will ensue - consider yourself warned. ``` python -m pip install proshade ``` Alternatively, the module can be build and installed using pip directly from the ProSHADE GitHub repository ( https://github.com/michaltykac/proshade ) using the following command. This approach has the advantage that it takes the most current stable version, rather than being dependent on the authors not forgetting to update the PyPi repository. ``` python -m pip install git+https://github.com/michaltykac/proshade ``` Again, please note that the pip installation only wraps around the CMake installation and that CMake is still being run by pip in the background. Therefore, the same system dependencies are required. Moreover, if any of the system dependencies is missing or cannot be found, then a bit more cryptic error message will be printed by pip. **Warning:** When installing using *pip* on Windows, the *Command Prompt* window needs to be closed once the installation is complete before ProSHADE will work. This is because the installation makes changes to the PATH variable and these will not be reflected by any windows opened before the installation completes. ### Uninstalling pip installed module Should the user require to uninstall the python module and all associated data after they were installed globally using pip, the following standard pip command can achieve this task irrespective as to how exactly the proshade module was installed: ``` python -m pip uninstall proshade ``` # Input PDB files There are several caveats to inputting PDB files; most of these have to do with the fact that PDB files encode much more information than ProSHADE is intended to use. Therefore, ProSHADE is by default set to disregard information it does not need; however, if the user so requires, the information may be used, albeit it may pose some unexpected problems. ## Spacegroups By default, ProSHADE will ignore the PDB file encoded spacegroup and will instead force the P1 spacegroup onto the input files. The reason for this behaviour is that when computing the theoretical density map, some spacegroups will cause density from other cells to be added as well (*e.g.* P21 21 21). Since ProSHADE is intended to use the structure shape irrespective of the experimental method (*i.e.* irrespective of crystal packaging), having density from other cells would cause ProSHADE to perceive differences where the structures could be identical except for the spacegroup. To force ProSHADE to make use of the spacegroup, please supply the ```-u``` command line option. ## Waters By default, ProSHADE will remove all water molecules from any input PDB files. The reason is similar to above, as ProSHADE is intended to compare protein shapes and as waters are in most cases not an integral part of the protein, this behaviour is attempting to avoid situations where two identical structures with one having hundreds of waters and one not would be perceived by ProSHADE as significantly different. Should the user require the water molecules to be used by ProSHADE, please supply the ```-w``` command line option. ## Models There are examples of both, PDB files containing multiple models of the same structure (with minor differences, *e.g.* trajectory files) and PDB files which have their chains (or collections of chains) separated into different models. Given this state of affairs, ProSHADE will by default use only the first model of each input PDB file and will print a warning message (which can be supressed by setting verbosity below 0) for each file it reads which has more than one model. Should the user want to use all available models for the input PDB files, please supply ProSHADE with the ```-x``` command line option. # Using the ProSHADE binary The ProSHADE tool was developed in a modular fashion and the usage slightly changes depending on the functionality that is required. Nonetheless, care has been taken to make sure that identical or closely related features are controlled by the same command line arguments in all cases. Moreover, the GNU command-line options standard have been adhered to (through the ```getOpts``` library) and therefore the users familiar with other command-line tools should find the entering of command line arguments simple. The following subsections relate to examples of using different functionalities; for a full list of command line options, please use the **--help** command line option of the ProSHADE binary. ## Symmetry Detection In order to detect symmetry in either a co-ordinate input file or in a map input file, the ProSHADE executable needs to be supplied with the option **-S** or **--symmetry** and it will also require a single input file to be supplied using the **-f** option. These two options are the only mandatory options, although there are many optional values that the user can supply to supersede the default values and therefore modify the operation fo the ProSHADE executable to fit their purpose. One particular option regarding the symmetry detection mode should be noted; the **--reqSym** (or **-u**) option, which allows the user to state which symmetry they believe to exist in the structure. The allowed values for this command line argument are "Cx", "Dx", "T", "O" and "I", where the *x* should be an integer number specifying the fold of the requested symmetry. When this option is used, it removes the default behaviour of returning the "best" detected symmetry and instead the symmetry requested by the user is returned, if it can be found in the structure. Another noteworthy option is the **--center** or **-c** option, which tells ProSHADE **NOT** to center the internal map representation over the centre of density before running any processing of the map (default is centering and adding this option will turn centering off). This may be important as ProSHADE detects symmetries over the centre of the co-ordinates and therefore a non-centered map (map which does not have the centre of mass at the centre of box) will be found to have no symmetries even if these are present, just not over the co-ordinate/box centre. Alternatively, ProSHADE can attempt a procedure for finding the symmetry centre itself - to enable this procedure, please supply the **--symCentre** or **-I** option. This procedure will firstly remove phase from the internal density map and attempt symmetry detection over the Patterson map. Then, by applying the symmetry that is found in the Patterson map (if any), the symmetry centre can be found; however, please note that this will consume considerable extra computation time (approximately 3-4 times slower than when the procedure is disabled). It is also worth noting that there are several extra functionalities available for the symmetry detection mode when accessed programmatically (**i.e.** either through the dynamic C++ library or through the Python language module). These extra functionalities include direct access to a vector/list of all detected cyclic symmetries, list/vector of all other symmetry type detections (meaning a list of all detected dihedral, tetrahedral, ... symmetries and the cyclic axes forming them) and also the ability to compute all point group elements for any point group formed by a combination of ProSHADE detected cyclic point groups. For more details on these functinoalities, the users are invited to consult the *advancedAccess_symmetry.cpp/py* example files in the **examples** folder. To demonstrate how the tool can be run and the standard output for the symmetry mode of operation, the current version of the ProSHADE executable was used to detect the symmetry of a density map of the bacteriophage T4 portal protein with the PDB accession code 3JA7 (EMDB accession code 6324), which has the *C12* symmetry. The visualisation of the structure is shown in the following figure, while the output of the ProSHADE tool follows. It is also worth noting that ProSHADE will output its prediction as well as table showing how different FSC average threshold values would change its prediction. This table can be used by the user to manually decide if they agree with the ProSHADE prediction or if thay suspect a different symmetry may indeed be real. Finally, ProSHADE will also output the list of all detected symmetries, so that experienced user could manually check for any particuar symmetry they are interested in and also check for how much they trust the ProSHADE prediction overall. ![T4 Portal Protein](https://github.com/michaltykac/proshade/blob/experimental/proshade/documentation/ProSHADE_3JA7.jpg) ``` $: ./proshade -S -f ./emd_6324.map %prep %autosetup -n proshade-0.7.6.6 %build %py3_build %install %py3_install install -d -m755 %{buildroot}/%{_pkgdocdir} if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi pushd %{buildroot} if [ -d usr/lib ]; then find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/lib64 ]; then find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/bin ]; then find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/sbin ]; then find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst fi touch doclist.lst if [ -d usr/share/man ]; then find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst fi popd mv %{buildroot}/filelist.lst . mv %{buildroot}/doclist.lst . %files -n python3-proshade -f filelist.lst %dir %{python3_sitelib}/* %files help -f doclist.lst %{_docdir}/* %changelog * Tue May 30 2023 Python_Bot - 0.7.6.6-1 - Package Spec generated