ProSHADE  0.7.5.1 (JAN 2021)
Protein Shape Detection
ProSHADE_internal_messages Namespace Reference

This namespace contains all the functions used for reporting back to the user. More...

Functions

void printWellcomeMessage (proshade_signed verbose)
 Wellcome message printing. More...
 
void printTerminateMessage (proshade_signed verbose)
 Final message printing. More...
 
void printProgressMessage (proshade_signed verbose, proshade_signed messageLevel, std::string message)
 General stdout message printing. More...
 
void printWarningMessage (proshade_signed verbose, std::string message, std::string warnCode)
 General stderr message printing (used for warnings). More...
 
void printHelp (void)
 This function prints the help screen in the case -h is called, or if command line arguments cannot be parsed. More...
 

Detailed Description

This namespace contains all the functions used for reporting back to the user.

The ProSHADE_internal_messages namespace wraps all functions for reporting back to the user. The user should not need to access this namespace when using the library.

Function Documentation

◆ printHelp()

void ProSHADE_internal_messages::printHelp ( void  )

This function prints the help screen in the case -h is called, or if command line arguments cannot be parsed.

Definition at line 118 of file ProSHADE_messages.cpp.

119 {
120  //================================================ Print the help screen
121  std::cout << "ProSHADE " << __PROSHADE_VERSION__ << ":" << std::endl << "==========================" << std::endl << std::endl << std::flush;
122  std::cout << " " << std::endl << std::flush;
123  std::cout << "DESCRIPTION: " << std::endl;
124  std::cout << " ProSHADE is a library of functionalities for computing distances between " << std::endl;
125  std::cout << " two three-dimensional macromolecular structures, finding symmetry in a par- " << std::endl;
126  std::cout << " ticular structure and general structure manipulation including detection of " << std::endl;
127  std::cout << " optimal rotation and translation for structure overlay. The undelying method " << std::endl;
128  std::cout << " is spherical harmonics decomposition of theoretical or experimental density " << std::endl;
129  std::cout << " maps. " << std::endl;
130  std::cout << " ProSHADE is available as an executable, C++ library and Python module. " << std::endl;
131  std::cout << " The following dialogue describes the usage of the executable, for help with " << std::endl;
132  std::cout << " the library or module, see the examples and the documentation available in " << std::endl;
133  std::cout << " the installation (for CCP-EM in the checkout) directory. " << std::endl;
134  std::cout << " " << std::endl;
135  std::cout << " " << std::endl;
136  std::cout << "AUTHORS: " << std::endl;
137  std::cout << " Michal Tykac <tykacm@ibt.cas.cz> " << std::endl;
138  std::cout << " Garib N. Murshudov " << std::endl;
139  std::cout << " " << std::endl;
140  std::cout << " " << std::endl;
141  std::cout << "MODES: " << std::endl;
142  std::cout << " There are several different modes in which ProSHADE can be run, depen- " << std::endl;
143  std::cout << " ding on the required functionality. The selection between these modes is " << std::endl;
144  std::cout << " done using the following options. " << std::endl;
145  std::cout << " " << std::endl;
146  std::cout << " -D or --distances " << std::endl;
147  std::cout << " The shape distances will be computed between the first supplied " << std::endl;
148  std::cout << " structure and all other structures. Requires at least two " << std::endl;
149  std::cout << " structures. " << std::endl;
150  std::cout << " " << std::endl;
151  std::cout << " -M or --mapManip " << std::endl;
152  std::cout << " The input maps will be re-boxed using the internal map masking and " << std::endl;
153  std::cout << " boundary finding procedures. Requires at least one structure. In " << std::endl;
154  std::cout << " case of co-ordinate input, these will be converted to map using " << std::endl;
155  std::cout << " Gemmi library. " << std::endl;
156  std::cout << " " << std::endl;
157  std::cout << " -S or --symmetry " << std::endl;
158  std::cout << " Detect if any C, D, T or I symmetries are present in all supplied " << std::endl;
159  std::cout << " structures. " << std::endl;
160  std::cout << " " << std::endl;
161  std::cout << " -O or --strOverlay " << std::endl;
162  std::cout << " Given two structures, find the optimal overlay using the " << std::endl;
163  std::cout << " rotation and translation functions. The first structure is " << std::endl;
164  std::cout << " always unchanged, while a rotated and translated version of the " << std::endl;
165  std::cout << " second structure will be written to the \'--overlayFile\' option " << std::endl;
166  std::cout << " path or its default value \'./movedStructure\' file. " << std::endl;
167  std::cout << " " << std::endl;
168  std::cout << "ARGUMENTS: " << std::endl;
169  std::cout << " The following options can be used to to supply information and values " << std::endl;
170  std::cout << " to be used when executing the functionality - i.e. they all require some " << std::endl;
171  std::cout << " argument to follow. Some of the settings may be mandatory for some, but not " << std::endl;
172  std::cout << " other modes. See the MODES section above. " << std::endl;
173  std::cout << " " << std::endl;
174  std::cout << " -! or --verbose [DEFAULT: 1] " << std::endl;
175  std::cout << " The verbosity of the run. Accepted values are from 0 to 4 with " << std::endl;
176  std::cout << " increasing amount of lines being printed. " << std::endl;
177  std::cout << " " << std::endl;
178  std::cout << " -f or --file [DEFAULT: NONE] " << std::endl;
179  std::cout << " File name (including path) of the input coordinate or map file. " << std::endl;
180  std::cout << " For multiple files, use the option multiple times. " << std::endl;
181  std::cout << " " << std::endl;
182  std::cout << " -u [DEFAULT: TRUE] " << std::endl;
183  std::cout << " Switch the value of this boolean. If true, any input PDB files " << std::endl;
184  std::cout << " will be forced to have P1 spacegroup, CRYST1 value otherwise. " << std::endl;
185  std::cout << " " << std::endl;
186  std::cout << " -w [DEFAULT: TRUE] " << std::endl;
187  std::cout << " Switch the value of this boolean. If true, all water molecules " << std::endl;
188  std::cout << " in input PDB files will be removed. " << std::endl;
189  std::cout << " " << std::endl;
190  std::cout << " -x [DEFAULT: TRUE] " << std::endl;
191  std::cout << " Switch the value of this boolean. If true, only the first PDB " << std::endl;
192  std::cout << " file model will be used, all models will be used otherwise. " << std::endl;
193  std::cout << " " << std::endl;
194  std::cout << " -r or --resolution [DEFAULT: NONE] " << std::endl;
195  std::cout << " The resolution to which the calculations are to be done and to " << std::endl;
196  std::cout << " which PDB files theoretical maps will be sampled to. " << std::endl;
197  std::cout << " " << std::endl;
198  std::cout << " -b or --bandwidth [DEFAULT: AUTO] " << std::endl;
199  std::cout << " The bandwidth to which spherical harmonics decomposition shoud " << std::endl;
200  std::cout << " be computed to. For automatic determination supply 0 or nothing. " << std::endl;
201  std::cout << " " << std::endl;
202  std::cout << " -s or --sphereDists [DEFAULT: AUTO] " << std::endl;
203  std::cout << " The distance in Angstroms between any two concentric spheres to " << std::endl;
204  std::cout << " which the internal map representation will be mapped to. Use " << std::endl;
205  std::cout << " 0.0 for automatic determination. " << std::endl;
206  std::cout << " " << std::endl;
207  std::cout << " -e or --extraSpace [DEFAULT: 10.0] " << std::endl;
208  std::cout << " The supplied number of Angstroms will be added to the structure " << std::endl;
209  std::cout << " internal map representation in order to avoid clashes with " << std::endl;
210  std::cout << " adjacent cells. " << std::endl;
211  std::cout << " " << std::endl;
212  std::cout << " -i or --integOrder [DEFAULT: AUTO] " << std::endl;
213  std::cout << " The order to which the Gauss-Legendre integration should be " << std::endl;
214  std::cout << " computed to. For automatic determination use 0. " << std::endl;
215  std::cout << " " << std::endl;
216  std::cout << " -t or --taylorCap [DEFAULT: 10] " << std::endl;
217  std::cout << " The cap on Taylor series calculation (used for the Legendre " << std::endl;
218  std::cout << " polynomial computation). No automatic determination available " << std::endl;
219  std::cout << " yet. " << std::endl;
220  std::cout << " " << std::endl;
221  std::cout << " -d or --pdbTempFact [DEFAULT: -1.0] " << std::endl;
222  std::cout << " Some PDB files have issues with B-factors (like all being 0.0) " << std::endl;
223  std::cout << " and to allow simple dealing with this, if this value is >= 0.0, " << std::endl;
224  std::cout << " then all B-factors of all PDB inputs will be set to this value. " << std::endl;
225  std::cout << " " << std::endl;
226  std::cout << " --maskFile [DEFAULT: \"./maskFile\"] " << std::endl;
227  std::cout << " The filename to which the mask will be saved to. The extension " << std::endl;
228  std::cout << " will be added as well as the structure index (order of input). " << std::endl;
229  std::cout << " " << std::endl;
230  std::cout << " --maskBlurring [DEFAULT: 350.0] " << std::endl;
231  std::cout << " The B-factor (temperature factor) increase, which should be " << std::endl;
232  std::cout << " applied to blurr the map for its subsequent masking. " << std::endl;
233  std::cout << " " << std::endl;
234  std::cout << " --maskThreshold [DEFAULT: 3.0] " << std::endl;
235  std::cout << " The number of inter-quartile ranges from median which will be " << std::endl;
236  std::cout << " used to determine the map masking threshold. " << std::endl;
237  std::cout << " " << std::endl;
238  std::cout << " --boundsSpace [DEFAULT: 3.0] " << std::endl;
239  std::cout << " The number of angstroms to be added to all re-boxing determined " << std::endl;
240  std::cout << " bounds to make sure no important surface information is lost. " << std::endl;
241  std::cout << " " << std::endl;
242  std::cout << " --boundsThreshold [DEFAULT: 0] " << std::endl;
243  std::cout << " The number of indices which can be added to a dimension in order " << std::endl;
244  std::cout << " to make two dimension sizes the same. " << std::endl;
245  std::cout << " " << std::endl;
246  std::cout << " -g or --reBoxedFilename [DEFAULT: \"reBoxed\"] " << std::endl;
247  std::cout << " The file name to which the re-boxed structure will be saved to. " << std::endl;
248  std::cout << " The extension will be added as well as the structure index (order " << std::endl;
249  std::cout << " of input). " << std::endl;
250  std::cout << " " << std::endl;
251  std::cout << " --EnLWeight [DEFAULT: 1.0] " << std::endl;
252  std::cout << " The exponential weight to be applied to the shell distance for " << std::endl;
253  std::cout << " the energy levels descriptor. " << std::endl;
254  std::cout << " " << std::endl;
255  std::cout << " --peakNeigh [DEFAULT: 1] " << std::endl;
256  std::cout << " Number of points in each dimension that need to be lower for " << std::endl;
257  std::cout << " peak to be detected. " << std::endl;
258  std::cout << " " << std::endl;
259  std::cout << " --peakThres [DEFAULT: AUTO] " << std::endl;
260  std::cout << " Number of IQRs from median for small peaks threshold for remo- " << std::endl;
261  std::cout << " ving small peaks. " << std::endl;
262  std::cout << " " << std::endl;
263  std::cout << " --missAxThres [DEFAULT: 0.3] " << std::endl;
264  std::cout << " The fraction of axes that can be missing for missing axes " << std::endl;
265  std::cout << " search to be initiated. " << std::endl;
266  std::cout << " " << std::endl;
267  std::cout << " --sameAxComp [DEFAULT: 0.01] " << std::endl;
268  std::cout << " The difference in dot product of two vectors for them to be " << std::endl;
269  std::cout << " still considered to be the same. " << std::endl;
270  std::cout << " " << std::endl;
271  std::cout << " --axisComBeh or -q [DEFAULT: TRUE] " << std::endl;
272  std::cout << " Should the maximum difference in dot product of two vectors for " << std::endl;
273  std::cout << " them to be still considered to be the same decrease with fold of " << std::endl;
274  std::cout << " tested symmetry? " << std::endl;
275  std::cout << " " << std::endl;
276  std::cout << " --bicubSearch or -A [DEFAULT: TRUE] " << std::endl;
277  std::cout << " Should the bi-cubic interpolation for sphere peaks be used to " << std::endl;
278  std::cout << " improve the axis by searching between grid indices? " << std::endl;
279  std::cout << " " << std::endl;
280  std::cout << " --maxSymPrime or -B [DEFAULT: 30] " << std::endl;
281  std::cout << " The automated symmetry search starts by looking for prime number " << std::endl;
282  std::cout << " folds and then for multiples of any folds found. This sets the " << std::endl;
283  std::cout << " maximum prime number to use in the search. " << std::endl;
284  std::cout << " " << std::endl;
285  std::cout << " --minPeakHeight or -o [DEFAULT: 0.3] " << std::endl;
286  std::cout << " The minimum average peak height for symmetry axis to be still " << std::endl;
287  std::cout << " considered as \"real\" for the symmetry detection. " << std::endl;
288  std::cout << " " << std::endl;
289  std::cout << " --sym [DEFAULT: \"\"] " << std::endl;
290  std::cout << " This is where the user states any particular symmetry he is " << std::endl;
291  std::cout << " interested in detecting. The way to specify any symmetry is to " << std::endl;
292  std::cout << " first use the letter for the symmetry type (C = cyclic, D = di- " << std::endl;
293  std::cout << " hedral, T = tetrahedral, O = octahedral or I = icosahedral) and " << std::endl;
294  std::cout << " for C and D symmetries to follow them with the requested fold. " << std::endl;
295  std::cout << " I.e. \"C4\" means cyclic symmetry with fold 4. " << std::endl;
296  std::cout << " " << std::endl;
297  std::cout << " --overlayFile [DEFAULT: \"movedStructure\"] " << std::endl;
298  std::cout << " Filename to where the translated and rotated moving structure " << std::endl;
299  std::cout << " with optimal placement relative to the static structure will be " << std::endl;
300  std::cout << " saved to. Extension will be added automatically " << std::endl;
301  std::cout << " " << std::endl;
302  std::cout << " --overlayJSONFile or -y [DEFAULT: \"movedStructureOperations.json\"] " << std::endl;
303  std::cout << " Filename to where the translations and rotation operations required " << std::endl;
304  std::cout << " for moving the \"moving\" structure to overlay the \"static\" structure " << std::endl;
305  std::cout << " will be written into. " << std::endl;
306  std::cout << " " << std::endl;
307  std::cout << "FLAGS: " << std::endl;
308  std::cout << " The following options can be used to override the default values and " << std::endl;
309  std::cout << " specify the execution path. " << std::endl;
310  std::cout << " " << std::endl;
311  std::cout << " --invertMap [DEFAULT: FALSE] " << std::endl;
312  std::cout << " In the case of getting the wrong hand of the structure during its " << std::endl;
313  std::cout << " creation, ProSHADE can switch these by inverting the map (i.e. " << std::endl;
314  std::cout << " any x,y,z = -x,-y,-z ) " << std::endl;
315  std::cout << " " << std::endl;
316  std::cout << " --normalise [DEFAULT: FALSE] " << std::endl;
317  std::cout << " Should the internal map and any written out maps be normalised " << std::endl;
318  std::cout << " to mean 0.0 and standard deviation 1.0? " << std::endl;
319  std::cout << " " << std::endl;
320  std::cout << " --mask [DEFAULT: FALSE] " << std::endl;
321  std::cout << " Should the internal map be masked by blurring by \"maskBlurring\" " << std::endl;
322  std::cout << " and thresholding by \"maskThreshold\" IQRs? NOTE: This option will " << std::endl;
323  std::cout << " not save the mask. For saving the mask, use \"saveMask\". " << std::endl;
324  std::cout << " " << std::endl;
325  std::cout << " --saveMask [DEFAULT: FALSE] " << std::endl;
326  std::cout << " This option will do map masking as well as save the used mask " << std::endl;
327  std::cout << " to the filename supplied in \"maskFile\". " << std::endl;
328  std::cout << " " << std::endl;
329  std::cout << " -R or --mapReboxing [DEFAULT: FALSE] " << std::endl;
330  std::cout << " Should the map be re-boxed? If yes, please note that the masking " << std::endl;
331  std::cout << " will be turned on automatically. " << std::endl;
332  std::cout << " " << std::endl;
333  std::cout << " --sameBoundaries [DEFAULT: FALSE] " << std::endl;
334  std::cout << " Use same boundaries for multiple maps? Useful for half-maps. " << std::endl;
335  std::cout << " " << std::endl;
336  std::cout << " --center or -c [DEFAULT: FALSE] " << std::endl;
337  std::cout << " Should the map be moved to centre of mass (COM) before process- " << std::endl;
338  std::cout << " ing? This will not affect map overlay positioning. " << std::endl;
339  std::cout << " " << std::endl;
340  std::cout << " --changeMapResol or -j [DEFAULT: TRUE] " << std::endl;
341  std::cout << " Should the map sampling be changed to fit the required resolu- " << std::endl;
342  std::cout << " tion, or should it be left alone? Uses Fourier space re-sampling. " << std::endl;
343  std::cout << " " << std::endl;
344  std::cout << " --changeMapTriLin or -a [DEFAULT: FALSE] " << std::endl;
345  std::cout << " Should the map sampling be changed to fit the required resolu- " << std::endl;
346  std::cout << " tion, or should it be left alone? Uses tri-linear interpolation re- " << std::endl;
347  std::cout << " sampling. " << std::endl;
348  std::cout << " " << std::endl;
349  std::cout << " --noPhase or -p [DEFAULT: TRUE] " << std::endl;
350  std::cout << " This option forces removal of phase from the internal map rep- " << std::endl;
351  std::cout << " resentation. " << std::endl;
352  std::cout << " " << std::endl;
353  std::cout << " --progressive or -k [DEFAULT: FALSE] " << std::endl;
354  std::cout << " In this case, only the optimal number of bands will be used for " << std::endl;
355  std::cout << " each sphere, depending on its size. This is in cotrast to the " << std::endl;
356  std::cout << " default all spheres same number of bands setting. " << std::endl;
357  std::cout << " " << std::endl;
358  std::cout << " --usePeaksInRotFun or -z [DEFAULT: FALSE] " << std::endl;
359  std::cout << " Symmetry detection can now be done either using peak detection in " << std::endl;
360  std::cout << " rotation function space, or by default by converting rotation func. " << std::endl;
361  std::cout << " to angle-axis space and finding symmetries there. Using this option " << std::endl;
362  std::cout << " switches to using peak detection in rotation function space. " << std::endl;
363  std::cout << " " << std::endl;
364  std::cout << " --noEnL or -l [DEFAULT: TRUE] " << std::endl;
365  std::cout << " Is the computation of the energy levels descriptor required? " << std::endl;
366  std::cout << " " << std::endl;
367  std::cout << " --noTrS or -m [DEFAULT: TRUE] " << std::endl;
368  std::cout << " Is the computation of the trace sigma descriptor required? " << std::endl;
369  std::cout << " " << std::endl;
370  std::cout << " --noFRF or -n [DEFAULT: TRUE] " << std::endl;
371  std::cout << " Is the computation of the full rotation function descriptor " << std::endl;
372  std::cout << " required? " << std::endl;
373  std::cout << " " << std::endl;
374  std::cout << std::endl << std::flush;
375 
376  //================================================ Done
377  exit ( EXIT_SUCCESS );
378 
379 }

◆ printProgressMessage()

void ProSHADE_internal_messages::printProgressMessage ( proshade_signed  verbose,
proshade_signed  messageLevel,
std::string  message 
)

General stdout message printing.

This function is used to print progress messages to the stdout. It takes the verbosity level, the message inportance level and the message as such and decides whether the message should be printed, doing so if required.

Parameters
[in]verboseInt value stating how loud the user requested the ProSHADE run to be.
[in]messageLevelInt value stating how important the message is.
[in]messageString of the actual message to be displayed.

Definition at line 70 of file ProSHADE_messages.cpp.

71 {
72  if ( verbose >= messageLevel )
73  {
74  if ( messageLevel > 0 )
75  {
76  std::cout << " ";
77  }
78 
79  for ( unsigned int iter = 0; iter < messageLevel; iter++ )
80  {
81  std::cout << "... ";
82  }
83 
84  std::cout << message << std::endl << std::flush;
85  }
86 
87  //================================================ Done
88  return ;
89 
90 }

◆ printTerminateMessage()

void ProSHADE_internal_messages::printTerminateMessage ( proshade_signed  verbose)

Final message printing.

This function prints the last message that appears when ProSHADE is being run, assuming the run ends with no problems.

Parameters
[in]verboseSigned int value stating how loud the user requested the ProSHADE run to be.

Definition at line 49 of file ProSHADE_messages.cpp.

50 {
51  if ( verbose >= 0 )
52  {
53  std::cout << std::endl << "======================" << std::endl << "ProSHADE run complete." << std::endl << "Time taken: " << std::clock() / CLOCKS_PER_SEC << " seconds." << std::endl << "======================" << std::endl << std::endl << std::flush;
54  }
55 
56  //================================================ Done
57  return ;
58 
59 }

◆ printWarningMessage()

void ProSHADE_internal_messages::printWarningMessage ( proshade_signed  verbose,
std::string  message,
std::string  warnCode 
)

General stderr message printing (used for warnings).

This function is used to print warnings to the user through the stderr (cerr) stream. It will not terminate the program run, as it is just a warning. Note that errors (exceptions) are handled elsewhere.

Parameters
[in]verboseInt value stating how loud the user requested the ProSHADE run to be.
[in]messageString of the actual message to be displayed.
[in]messageString of the warning code to be displayed.

Definition at line 101 of file ProSHADE_messages.cpp.

102 {
103  if ( verbose >= -2 )
104  {
105  std::cerr << std::endl << message << std::endl << std::flush;
106  std::cerr << " ... CODE: " << warnCode << std::endl << std::endl << std::flush;
107 
108  }
109 
110  //================================================ Done
111  return ;
112 
113 }

◆ printWellcomeMessage()

void ProSHADE_internal_messages::printWellcomeMessage ( proshade_signed  verbose)

Wellcome message printing.

This function prints the first message that appears when ProSHADE is being run.

Parameters
[in]verboseSigned int value stating how loud the user requested the ProSHADE run to be.

Definition at line 31 of file ProSHADE_messages.cpp.

32 {
33  if ( verbose >= 0 )
34  {
35  std::cout << "ProSHADE " << __PROSHADE_VERSION__ << ":" << std::endl << "============================" << std::endl << std::endl << std::flush;
36  }
37 
38  //================================================ Done
39  return ;
40 
41 }