Skip to content

Commit

Permalink
Merge branch 'development'
Browse files Browse the repository at this point in the history 
This is the new version 0.7.6.3 (FEB 2022).

The main new features include:

1) The stripe on sphere mapped rotation function for angle 180deg around the equator is now gone.
        a) The cause was an error in rotation matrix to euler angles conversion in the singularity case.
        b) The Euler angles are in ZYZ and NOT in ZXZ format. All references changed.
2) Completely re-worked FSC computation - now it is faster and much more accurate. More specifically:
        a) Binning is improved.
        b) Resolution cut-off for faster computation.
        c) Map rotation now done in reciprocal space (i.e. faster).
3) Improved the symmetry detection logic
        a) There was a wrong axis in the pre-computed optimal Icosahedron, now resolved.
        b) D symmetries are now not simply taken as the highest fold and passing threshold, now smoothened histogram approach is used.
        c) C symmetries and D symmetries are both considered, instead of just taking any D over any C.
4) Speed improvements
        a) If mask is supplied, the inner settings (bandwidth) use the non-zero mask size instead of full map size.
        b) Radius in which the structure is considered and outside of which it is ignored can now be supplied for faster calculations
        c) Improved the peak detection threshold detection, which was causing some structures to take be 10 times slower for symmetry detection.
5) Minor bug fixes and code clean-ups.
  • Loading branch information
@michaltykac
michaltykac committed Mar 2, 2022
2 parents c3791b3 + 92b216b commit af07d84
Show file tree
Hide file tree
Showing 74 changed files with 3,542 additions and 1,395 deletions.
59 changes: 18 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
ProSHADE
========

Protein Shape Description and Symmetry Detection version 0.7.6.2 (DEC 2021)
Protein Shape Description and Symmetry Detection version 0.7.6.3 (FEB 2022)

# Introduction

Expand Down Expand Up @@ -323,7 +323,7 @@ To demonstrate how the tool can be run and the standard output for the symmetry

```
$: ./proshade -S -f ./emd_6324.map
ProSHADE 0.7.6.2 (DEC 2021):
ProSHADE 0.7.6.3 (FEB 2022):
============================
... Starting to read the structure: ./emd_6324.map
Expand All @@ -341,30 +341,26 @@ ProSHADE 0.7.6.2 (DEC 2021):
... Starting self-rotation function computation.
... Starting C symmetry detection.
... Starting D symmetry detection.
... Starting I symmetry prediction.
... Starting O symmetry prediction.
... Starting T symmetry prediction.
... Starting O symmetry prediction.
... Starting I symmetry prediction.
... Starting recommended symmetry decision procedure.
Detected C symmetry with fold 12 about point [2.9202 , 2.92307 , 13.017] away from centre of mass .
Fold X Y Z Angle Height Average FSC
+12 +0.00000 +0.00000 +1.00000 +0.52360 +0.95258 +0.94672
+12 -0.00001 +0.00002 +1.00000 -0.52360 +0.95258 +0.99413
To facilitate manual checking for symmetries, the following is a list of all detected C symmetries:
Fold X Y Z Angle Height Average FSC
+2 +0.00096 +0.00000 +1.00000 +3.14159 +0.99402 +0.99512
+4 +0.00000 +0.00000 +1.00000 +1.57080 +0.99359 +0.99694
+12 +0.00000 +0.00000 +1.00000 +0.52360 +0.95258 +0.94672
+6 +0.00000 +0.00000 +1.00000 +1.04720 +0.94835 +0.94139
+3 +0.00000 +0.00000 +1.00000 +2.09440 +0.93690 +0.92691
+8 +0.00000 +0.00000 +1.00000 +0.78540 +0.69255 -inf
... [Some lines removed for more succinct documentation]
+2 -0.54269 +0.23607 -0.80607 +3.14159 +0.36182 +0.00256
+2 +0.87870 -0.36777 +0.30435 +3.14159 +0.35287 +0.00973
+2 +0.00096 +0.00000 +1.00000 +3.14159 +0.99402 +0.99624
+4 +0.00000 +0.00000 +1.00000 +1.57080 +0.99359 +0.99720
+12 -0.00001 +0.00002 +1.00000 -0.52360 +0.95258 +0.99413
+6 -0.00000 +0.00000 +1.00000 -1.04720 +0.94835 +0.99353
+3 +0.00000 +0.00000 +1.00000 +2.09440 +0.93690 +0.99211
======================
ProSHADE run complete.
Time taken: 114 seconds.
Time taken: 52 seconds.
======================
```

Expand All @@ -380,7 +376,7 @@ Time taken: 114 seconds.

```
$: ./proshade -D -f ./1BFO_A_dom_1.pdb -f ./1H8N_A_dom_1.pdb -f ./3IGU_A_dom_1.pdb -r 6
ProSHADE 0.7.6.2 (DEC 2021):
ProSHADE 0.7.6.3 (FEB 2022):
============================
... Starting to read the structure: ./1BFO_A_dom_1.pdb
Expand Down Expand Up @@ -436,7 +432,7 @@ Time taken: 114 seconds.
======================
ProSHADE run complete.
Time taken: 0 seconds.
Time taken: 1 seconds.
======================
```

Expand All @@ -454,7 +450,7 @@ Time taken: 114 seconds.

```
$ ./proshade -RMf ./emd_5762.map.gz
ProSHADE 0.7.6.2 (DEC 2021):
ProSHADE 0.7.6.3 (FEB 2022):
============================
... Starting to read the structure: ./emd_5762.map.gz
Expand Down Expand Up @@ -498,7 +494,7 @@ Time taken: 9 seconds.

```
$ ./proshade -O -f ./1BFO_A_dom_1.pdb -f ./1H8N_A_dom_1.pdb -r 1
ProSHADE 0.7.6.2 (DEC 2021):
ProSHADE 0.7.6.3 (FEB 2022):
============================
... Starting to read the structure: ./1BFO_A_dom_1.pdb
Expand Down Expand Up @@ -827,9 +823,9 @@ pStruct1.computeSphericalHarmonics ( pSet )
pStruct2.computeSphericalHarmonics ( pSet )
""" Get the distances """
energyLevelsDescriptor = proshade.computeEnergyLevelsDescriptor ( pStruct1, pStruct2, pSet )
traceSigmaDescriptor = proshade.computeTraceSigmaDescriptor ( pStruct1, pStruct2, pSet )
fullRotationFunctionDescriptor = proshade.computeRotationunctionDescriptor ( pStruct1, pStruct2, pSet )
energyLevelsDescriptor = proshade.computeEnergyLevelsDescriptor ( pStruct1, pStruct2, pSet )
traceSigmaDescriptor = proshade.computeTraceSigmaDescriptor ( pStruct1, pStruct2, pSet )
fullRotationFunctionDescriptor = proshade.computeRotationFunctionDescriptor ( pStruct1, pStruct2, pSet )
""" Print results """
print ( "The energy levels distance is %+1.3f" % ( energyLevelsDescriptor ) )
Expand Down Expand Up @@ -887,25 +883,6 @@ del pStruct

It is also possible to supply a mask for any input map as a three-dimensional array directly to the *readInStructure()* function. This possibility may be interesting for cases where custom masks are created by a python running software/code, as this avoids the need for the mask to be written into a file onto the disk and then read back. Furthermore, if the user should require weighting the input map in Fourier space, a set of weights can be supplied to the *readInStructure()* function as well; these weights will be applieds in the same order as they are given to the FFTW3 coefficients of the input map, *i.e.* the weights should be supplied in the format: f_0, ..., f_N/2, f_-N/2+1, ..., f_-1. For more details as to how the mask or weights can be supplied, please see the */path/to/proshade/proshade/examples/python/howto_accessInterimResults.py* file.

#### Reading co-ordinates from gemmi

An alternative way of supplying the structural data to the ProSHADE_data object is to pass it a gemmi::Structure object. Since Gemmi is also a C++ library with PyBind11 python interface, it is possible to pass its objects to ProSHADE through the shared python interface. This can be useful for users who wish to modify or create gemmi::Structure objects using other codes and then pass these to ProSHADE for further analysis. Please note, that only co-ordinate data will be parsed from gemmi::Structure objects by ProSHADE. An example follows, but more detailed description can be found in the */path/to/proshade/proshade/examples/python/howto_useGemmiObject.py* file.

```
""" Import gemmi """
import gemmi
""" Read structure into gemmi::Structure object """
gStruct = gemmi.read_structure( "5woh.pdb" )
""" Modify the gemmi::Structure object """
...
""" Read gemmi::Structure into ProSHADE """
pStruct = proshade.ProSHADE_data ( )
pStruct.readInStructure ( gStruct, 0, pSet )
```

#### Creating ProSHADE_data object from map

Alteratively, **ProSHADE_data** object can be created from an already existing map and some of the basic map information data. As an example, we will create a 1D numpy.array, which will hold the density values of a map that we would like to supply to ProSHADE. Of course this array can be the result of any other python module, the only requirement is that the data type is 1D numpy.ndarray with dtype of *float64* with the XYZ axis order.
Expand Down
1 change: 0 additions & 1 deletion proshade/Doxyfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,6 @@ PROJECT_NAME = ProSHADE
# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
# could be handy for archiving the generated documentation or if some version
# control system is used.
PROJECT_NUMBER = "0.7.6.2 (DEC 2021)"


# Using the PROJECT_BRIEF tag one can provide an optional one line description
Expand Down
4 changes: 3 additions & 1 deletion proshade/error_list.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
====================================
====================================

== NEXT FREE MESSAGE NUMBER: 00073 ==
== NEXT FREE MESSAGE NUMBER: 00075 ==

========
GENERAL:
Expand Down Expand Up @@ -146,6 +146,7 @@ CODE: Message: Comment:
WM00049 Requested both Fourier-space and real-space map re-sampling. Defaulting to only Fourier space re-samplling. This warning results when both -a and -j options are given. If you are not using both, then consider that the Fourier-space re-sampling is default for some tasks.
WM00068 Requested box centre to be co-ordinate position outside of co-ordinates range. Please re-view the requested box The requested map box centre position (given in co-ordinate space) is outside of the map range. This could happen if position is given in non-co-ordinate space, e.g. in map indices space...
centre position.
WM00074 Requested maximum radius is larger than the maximum map dimension. Using the maximum map dimension instead. The user has supplied maximum radius using --maxRadius larger, than is the largest dimension. This makes no sense and would only be slower than just using the maximum dimension, while it would only add noise.

==========
RE-BOXING:
Expand Down Expand Up @@ -183,6 +184,7 @@ WS00069 SVD algorithm did not converge. When computing th
WS00071 Failed to find symmetry in Patterson map. Map rotation centre detection cannot be done without a symmetry, returning Pretty much what is says. If you believe the symmetry should be there, try changing the resolution.
vector with [Inf, Inf, Inf].
WS00072 Failed to find eigenvalue with value 1 for this rotation matrix. Is this a rotation matrix? This warning occurs when eigenvalue with value 1 is not found be LAPACK in the supplied rotation matrix. This should not happen, as all rotation matrices must have at least one eigenvalue with value 1, so this suggests the supplied matrix is not a rotation matrix.
WS00073 Requested both symmetry centre detection and COM centering. COM centering turned off. This warning means that symmetry centre detection was done (or at least symmetry centre position was supplied) and still centering on COM was requested - this makes no sense as the COM centering would over-write the previous centre of symmetry search and therefore the COM centering is turned off.

========
OVERLAY:
Expand Down
4 changes: 2 additions & 2 deletions proshade/examples/libproshade/advancedAccess_distances.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@
\author Michal Tykac
\author Garib N. Murshudov
\version 0.7.6.2
\date DEC 2021
\version 0.7.6.3
\date FEB 2022
*/

//==================================================== ProSHADE
Expand Down
6 changes: 3 additions & 3 deletions proshade/examples/libproshade/advancedAccess_overlay.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@
\author Michal Tykac
\author Garib N. Murshudov
\version 0.7.6.2
\date DEC 2021
\version 0.7.6.3
\date FEB 2022
*/

//==================================================== ProSHADE
Expand Down Expand Up @@ -118,7 +118,7 @@ int main ( int argc, char **argv )
//================================================ Get optimal rotation matrix. This is not required for ProSHADE, but users may be interested in this, so it is showcased here.
proshade_double* rotMat = new proshade_double[9]; // The rotation matrix is returned as an array of 9 doubles, rows first. This is where the memory is allocated.
ProSHADE_internal_misc::checkMemoryAllocation ( rotMat, __FILE__, __LINE__, __func__ ); // Function for checking memory allocation, feel free to change to your preferred memory checking approach.
ProSHADE_internal_maths::getRotationMatrixFromEulerZXZAngles ( optimalEulerRot.at(0), optimalEulerRot.at(1), optimalEulerRot.at(2), rotMat ); // This is internal ProSHADE function which computes the rotation matrix from the Euler angles.
ProSHADE_internal_maths::getRotationMatrixFromEulerZYZAngles ( optimalEulerRot.at(0), optimalEulerRot.at(1), optimalEulerRot.at(2), rotMat ); // This is internal ProSHADE function which computes the rotation matrix from the Euler angles.
std::cout << "Optimal rotation Euler angles are: " << optimalEulerRot.at(0) << " ; " << optimalEulerRot.at(1) << " ; " << optimalEulerRot.at(2) << std::endl;
std::cout << "Optimal rotation matrix is : " << rotMat[0] << " ; " << rotMat[1] << " ; " << rotMat[2] << std::endl;
std::cout << " : " << rotMat[3] << " ; " << rotMat[4] << " ; " << rotMat[5] << std::endl;
Expand Down
4 changes: 2 additions & 2 deletions proshade/examples/libproshade/advancedAccess_reboxing.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@
\author Michal Tykac
\author Garib N. Murshudov
\version 0.7.6.2
\date DEC 2021
\version 0.7.6.3
\date FEB 2022
*/

//==================================================== ProSHADE
Expand Down
13 changes: 7 additions & 6 deletions proshade/examples/libproshade/advancedAccess_symmetry.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@
\author Michal Tykac
\author Garib N. Murshudov
\version 0.7.6.2
\date DEC 2021
\version 0.7.6.3
\date FEB 2022
*/

//==================================================== ProSHADE
Expand Down Expand Up @@ -134,8 +134,9 @@ int main ( int argc, char **argv )
}

//================================================ Expected output
// Detected symmetry: C-6 with axes:
// Symmetry axis number 0: Fold 6 XYZ: 0 ; 0 ; 1 Angle (radians): 1.0472 , axis peak: 0.955807 and averaged FSC of 0.966346
// Detected symmetry: D-6 with axes:
// Symmetry axis number 0: Fold 6 XYZ: 0 ; 0 ; 1 Angle (radians): 1.0472 , axis peak: 0.955807 and averaged FSC of 0.975556
// Symmetry axis number 1: Fold 2 XYZ: 0.87222 ; 0.489037 ; 0.00868856 Angle (radians): 3.14159 , axis peak: 0.957264 and averaged FSC of 0.612032

//================================================ Find all C axes
std::vector < std::vector< proshade_double > > allCs = settings->allDetectedCAxes;
Expand Down Expand Up @@ -190,9 +191,9 @@ int main ( int argc, char **argv )
}

//================================================ Expected output
// Detected symmetry: D-3 as requested. The axes are:
// Detected symmetry: D-3 as requested. The axes are
// Symmetry axis number 0: Fold 3 XYZ: 0 ; 0 ; 1 Angle (radians): 2.0944 and axis peak: 0.948237
// Symmetry axis number 1: Fold 2 XYZ: 0.999961 ; -0.0088698 ; -6.12323e-17 Angle (radians): -3.14159 and axis peak: 1.00933
// Symmetry axis number 1: Fold 2 XYZ: 0.0088698 ; 0.999961 ; 6.12323e-17 Angle (radians): 3.14159 and axis peak: 1


// NOTE: To get all the point group elements, one needs to supply the list of all cyclic point groups which comprise the
Expand Down
4 changes: 2 additions & 2 deletions proshade/examples/libproshade/proshadeBinary.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@
\author Michal Tykac
\author Garib N. Murshudov
\version 0.7.6.2
\date DEC 2021
\version 0.7.6.3
\date FEB 2022
*/

//==================================================== ProSHADE
Expand Down
4 changes: 2 additions & 2 deletions proshade/examples/libproshade/simpleAccess_distances.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@
\author Michal Tykac
\author Garib N. Murshudov
\version 0.7.6.2
\date DEC 2021
\version 0.7.6.3
\date FEB 2022
*/

//==================================================== ProSHADE
Expand Down
4 changes: 2 additions & 2 deletions proshade/examples/libproshade/simpleAccess_overlay.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@
\author Michal Tykac
\author Garib N. Murshudov
\version 0.7.6.2
\date DEC 2021
\version 0.7.6.3
\date FEB 2022
*/

//==================================================== ProSHADE
Expand Down
4 changes: 2 additions & 2 deletions proshade/examples/libproshade/simpleAccess_reboxing.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@
\author Michal Tykac
\author Garib N. Murshudov
\version 0.7.6.2
\date DEC 2021
\version 0.7.6.3
\date FEB 2022
*/

//==================================================== ProSHADE
Expand Down
8 changes: 4 additions & 4 deletions proshade/examples/libproshade/simpleAccess_symmetry.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@
\author Michal Tykac
\author Garib N. Murshudov
\version 0.7.6.2
\date DEC 2021
\version 0.7.6.3
\date FEB 2022
*/

//==================================================== ProSHADE
Expand Down Expand Up @@ -105,14 +105,14 @@ int main ( int argc, char **argv )

//================================================ Expected output
// Detected symmetry C of fold 12. The symmetry axes are:
// ... FOLD: 12 | XYZ: 0 ; 0 ; 1 | Angle: 0.523599 | Peak: 0.974519 | Average FSC: 0.970268
// ... FOLD: 12 | XYZ: -0.000177333 ; -4.83473e-05 ; 1 | Angle: -0.523599 | Peak: 0.974527 | Average FSC: 0.991312

//================================================ Get list of all detected cyclic symmetries
std::vector < std::vector< proshade_double > > allCs = runProshade->getAllCSyms ( );
std::cout << "Found a total of " << allCs.size() << " cyclic symmetries." << std::endl;

//================================================ Expected output
// Found a total of 90 cyclic symmetries.
// Found a total of 5 cyclic symmetries.

//================================================ Find the internal map processing COM shift
std::vector< proshade_double > comMove = runProshade->getMapCOMProcessChange ( );
Expand Down
4 changes: 2 additions & 2 deletions proshade/examples/python/advancedAccess_distances.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@
#
# \author Michal Tykac
# \author Garib N. Murshudov
# \version 0.7.6.2
# \date DEC 2021
# \version 0.7.6.3
# \date FEB 2022
######################################################
######################################################

Expand Down
4 changes: 2 additions & 2 deletions proshade/examples/python/advancedAccess_overlay.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@
#
# \author Michal Tykac
# \author Garib N. Murshudov
# \version 0.7.6.2
# \date DEC 2021
# \version 0.7.6.3
# \date FEB 2022
######################################################
######################################################

Expand Down
4 changes: 2 additions & 2 deletions proshade/examples/python/advancedAccess_reBox.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@
#
# \author Michal Tykac
# \author Garib N. Murshudov
# \version 0.7.6.2
# \date DEC 2021
# \version 0.7.6.3
# \date FEB 2022
######################################################
######################################################

Expand Down
14 changes: 7 additions & 7 deletions proshade/examples/python/advancedAccess_symmetry.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@
#
# \author Michal Tykac
# \author Garib N. Murshudov
# \version 0.7.6.2
# \date DEC 2021
# \version 0.7.6.3
# \date FEB 2022
######################################################
######################################################

Expand Down Expand Up @@ -97,8 +97,8 @@
### Expected output
# Detected D-6 symetry.
# Fold x y z Angle Height Average FSC
# 6.0 +0.000 +0.000 +1.000 +1.047 +0.9709 +0.9758
# 2.0 +1.000 -0.005 -0.000 -3.142 +1.0103 +0.8624
# 6.0 -0.000 -0.000 +1.000 -1.047 +0.9709 +0.9784
# 2.0 +0.011 +1.000 +0.000 +3.142 +1.0000 +0.6916

######################################################
### Get list of all cyclic axes detected
Expand Down Expand Up @@ -193,11 +193,11 @@ def isclose ( a, b, tol = 1e-04 ):

######################################################
### Expected output
# Found a total of 12 group [6, 0] elements.
# Found a total of 12 group [7, 2] elements.
# The first non-identity element is:
# +0.500 +0.866 +0.000
# -0.866 +0.500 +0.000
# +0.000 +0.000 +1.000
# -0.866 +0.500 -0.000
# -0.000 -0.000 +1.000

######################################################
### Assuming you have modifiex / created your own C groups
Expand Down
Loading

0 comments on commit af07d84

Please sign in to comment.