ProSHADE  0.7.6.2 (DEC 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, proshade_signed messageShift=0)
 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 119 of file ProSHADE_messages.cpp.

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

◆ printProgressMessage()

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

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.
[in]messageShiftHow much should the message be shifted (i.e. if this a sub-process of larger task, set this to 1 instead of 0).

Definition at line 71 of file ProSHADE_messages.cpp.

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

◆ 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 102 of file ProSHADE_messages.cpp.

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

◆ 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 }