ProSHADE  0.7.6.0 (JUL 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 << " -F or --keepNegDens [DEFAULT: TRUE] " << std::endl;
227  std::cout << " Some input files have negative density that causes differences " << std::endl;
228  std::cout << " to be detected between structures that appear identical. By " << std::endl;
229  std::cout << " default negative density is removed, this option keeps it in. " << std::endl;
230  std::cout << " " << std::endl;
231  std::cout << " --maskFile [DEFAULT: \"./maskFile\"] " << std::endl;
232  std::cout << " The filename to which the mask will be saved to. The extension " << std::endl;
233  std::cout << " will be added as well as the structure index (order of input). " << std::endl;
234  std::cout << " -G or --applyMask [DEFAULT: \"\"] " << std::endl;
235  std::cout << " This option allows supplying a map mask, which will be applied " << std::endl;
236  std::cout << " before any other processing in the input map. This option is only " << std::endl;
237  std::cout << " available for the map manipulation and symmetry detection tasks. " << std::endl;
238  std::cout << " " << std::endl;
239  std::cout << " --maskBlurring [DEFAULT: 350.0] " << std::endl;
240  std::cout << " The B-factor (temperature factor) increase, which should be " << std::endl;
241  std::cout << " applied to blurr the map for its subsequent masking. " << std::endl;
242  std::cout << " " << std::endl;
243  std::cout << " --maskThreshold [DEFAULT: 3.0] " << std::endl;
244  std::cout << " The number of inter-quartile ranges from median which will be " << std::endl;
245  std::cout << " used to determine the map masking threshold. " << std::endl;
246  std::cout << " " << std::endl;
247  std::cout << " --boundsSpace [DEFAULT: 3.0] " << std::endl;
248  std::cout << " The number of angstroms to be added to all re-boxing determined " << std::endl;
249  std::cout << " bounds to make sure no important surface information is lost. " << std::endl;
250  std::cout << " " << std::endl;
251  std::cout << " --boundsThreshold [DEFAULT: 0] " << std::endl;
252  std::cout << " The number of indices which can be added to a dimension in order " << std::endl;
253  std::cout << " to make two dimension sizes the same. " << std::endl;
254  std::cout << " " << std::endl;
255  std::cout << " -g or --reBoxedFilename [DEFAULT: \"reBoxed\"] " << std::endl;
256  std::cout << " The file name to which the re-boxed structure will be saved to. " << std::endl;
257  std::cout << " The extension will be added as well as the structure index (order " << std::endl;
258  std::cout << " of input). " << std::endl;
259  std::cout << " " << std::endl;
260  std::cout << " --EnLWeight [DEFAULT: 1.0] " << std::endl;
261  std::cout << " The exponential weight to be applied to the shell distance for " << std::endl;
262  std::cout << " the energy levels descriptor. " << std::endl;
263  std::cout << " " << std::endl;
264  std::cout << " --peakNeigh [DEFAULT: 1] " << std::endl;
265  std::cout << " Number of points in each dimension that need to be lower for " << std::endl;
266  std::cout << " peak to be detected. " << std::endl;
267  std::cout << " " << std::endl;
268  std::cout << " --peakThres [DEFAULT: AUTO] " << std::endl;
269  std::cout << " Number of IQRs from median for small peaks threshold for remo- " << std::endl;
270  std::cout << " ving small peaks. " << std::endl;
271  std::cout << " " << std::endl;
272  std::cout << " --missAxThres [DEFAULT: 0.3] " << std::endl;
273  std::cout << " The fraction of axes that can be missing for missing axes " << std::endl;
274  std::cout << " search to be initiated. " << std::endl;
275  std::cout << " " << std::endl;
276  std::cout << " --sameAxComp [DEFAULT: 0.01] " << std::endl;
277  std::cout << " The difference in dot product of two vectors for them to be " << std::endl;
278  std::cout << " still considered to be the same. " << std::endl;
279  std::cout << " " << std::endl;
280  std::cout << " --axisComBeh or -q [DEFAULT: TRUE] " << std::endl;
281  std::cout << " Should the maximum difference in dot product of two vectors for " << std::endl;
282  std::cout << " them to be still considered to be the same decrease with fold of " << std::endl;
283  std::cout << " tested symmetry? " << std::endl;
284  std::cout << " " << std::endl;
285  std::cout << " --bicubSearch or -A [DEFAULT: TRUE] " << std::endl;
286  std::cout << " Should the bi-cubic interpolation for sphere peaks be used to " << std::endl;
287  std::cout << " improve the axis by searching between grid indices? " << std::endl;
288  std::cout << " " << std::endl;
289  std::cout << " --maxSymPrime or -B [DEFAULT: 30] " << std::endl;
290  std::cout << " The automated symmetry search starts by looking for prime number " << std::endl;
291  std::cout << " folds and then for multiples of any folds found. This sets the " << std::endl;
292  std::cout << " maximum prime number to use in the search. " << std::endl;
293  std::cout << " " << std::endl;
294  std::cout << " --minPeakHeight or -o [DEFAULT: 0.3] " << std::endl;
295  std::cout << " The minimum average peak height for symmetry axis to be still " << std::endl;
296  std::cout << " considered as \"real\" for the symmetry detection. " << std::endl;
297  std::cout << " " << std::endl;
298  std::cout << " --fscThres or -C [DEFAULT: 0.75] " << std::endl;
299  std::cout << " The Fourier Shell Correlation value the axes need to achieve in " << std::endl;
300  std::cout << " order to be considered \"real\" by the symmetry detection algorithm. " << std::endl;
301  std::cout << " " << std::endl;
302  std::cout << " --peakMinThres or -E [DEFAULT: 0.80] " << std::endl;
303  std::cout << " The average peak height value the axes need to achieve in order " << std::endl;
304  std::cout << " to be considered \"possible\" by the symmetry detection algorithm. " << std::endl;
305  std::cout << " " << std::endl;
306  std::cout << " --reqSym [DEFAULT: \"\"] " << std::endl;
307  std::cout << " This is where the user states any particular symmetry he is " << std::endl;
308  std::cout << " interested in detecting. The way to specify any symmetry is to " << std::endl;
309  std::cout << " first use the letter for the symmetry type (C = cyclic, D = di- " << std::endl;
310  std::cout << " hedral, T = tetrahedral, O = octahedral or I = icosahedral) and " << std::endl;
311  std::cout << " for C and D symmetries to follow them with the requested fold. " << std::endl;
312  std::cout << " I.e. \"C4\" means cyclic symmetry with fold 4. " << std::endl;
313  std::cout << " " << std::endl;
314  std::cout << " --overlayFile [DEFAULT: \"movedStructure\"] " << std::endl;
315  std::cout << " Filename to where the translated and rotated moving structure " << std::endl;
316  std::cout << " with optimal placement relative to the static structure will be " << std::endl;
317  std::cout << " saved to. Extension will be added automatically " << std::endl;
318  std::cout << " " << std::endl;
319  std::cout << " --overlayJSONFile or -y [DEFAULT: \"movedStructureOperations.json\"] " << std::endl;
320  std::cout << " Filename to where the translations and rotation operations required " << std::endl;
321  std::cout << " for moving the \"moving\" structure to overlay the \"static\" structure " << std::endl;
322  std::cout << " will be written into. " << std::endl;
323  std::cout << " " << std::endl;
324  std::cout << "FLAGS: " << std::endl;
325  std::cout << " The following options can be used to override the default values and " << std::endl;
326  std::cout << " specify the execution path. " << std::endl;
327  std::cout << " " << std::endl;
328  std::cout << " --invertMap [DEFAULT: FALSE] " << std::endl;
329  std::cout << " In the case of getting the wrong hand of the structure during its " << std::endl;
330  std::cout << " creation, ProSHADE can switch these by inverting the map (i.e. " << std::endl;
331  std::cout << " any x,y,z = -x,-y,-z ) " << std::endl;
332  std::cout << " " << std::endl;
333  std::cout << " --normalise [DEFAULT: FALSE] " << std::endl;
334  std::cout << " Should the internal map and any written out maps be normalised " << std::endl;
335  std::cout << " to mean 0.0 and standard deviation 1.0? " << std::endl;
336  std::cout << " " << std::endl;
337  std::cout << " --mask [DEFAULT: FALSE] " << std::endl;
338  std::cout << " Should the internal map be masked by blurring by \"maskBlurring\" " << std::endl;
339  std::cout << " and thresholding by \"maskThreshold\" IQRs? NOTE: This option will " << std::endl;
340  std::cout << " not save the mask. For saving the mask, use \"saveMask\". " << std::endl;
341  std::cout << " " << std::endl;
342  std::cout << " --saveMask [DEFAULT: FALSE] " << std::endl;
343  std::cout << " This option will do map masking as well as save the used mask " << std::endl;
344  std::cout << " to the filename supplied in \"maskFile\". " << std::endl;
345  std::cout << " " << std::endl;
346  std::cout << " -R or --mapReboxing [DEFAULT: FALSE] " << std::endl;
347  std::cout << " Should the map be re-boxed? If yes, please note that the masking " << std::endl;
348  std::cout << " will be turned on automatically. " << std::endl;
349  std::cout << " " << std::endl;
350  std::cout << " --sameBoundaries [DEFAULT: FALSE] " << std::endl;
351  std::cout << " Use same boundaries for multiple maps? Useful for half-maps. " << std::endl;
352  std::cout << " " << std::endl;
353  std::cout << " --center or -c [DEFAULT: FALSE] " << std::endl;
354  std::cout << " Should the map be moved to centre of mass (COM) before process- " << std::endl;
355  std::cout << " ing? This will not affect map overlay positioning. " << std::endl;
356  std::cout << " " << std::endl;
357  std::cout << " --changeMapResol or -j [DEFAULT: TRUE] " << std::endl;
358  std::cout << " Should the map sampling be changed to fit the required resolu- " << std::endl;
359  std::cout << " tion, or should it be left alone? Uses Fourier space re-sampling. " << std::endl;
360  std::cout << " " << std::endl;
361  std::cout << " --changeMapTriLin or -a [DEFAULT: FALSE] " << std::endl;
362  std::cout << " Should the map sampling be changed to fit the required resolu- " << std::endl;
363  std::cout << " tion, or should it be left alone? Uses tri-linear interpolation re- " << std::endl;
364  std::cout << " sampling. " << std::endl;
365  std::cout << " " << std::endl;
366  std::cout << " --noPhase or -p [DEFAULT: TRUE] " << std::endl;
367  std::cout << " This option forces removal of phase from the internal map rep- " << std::endl;
368  std::cout << " resentation. " << std::endl;
369  std::cout << " " << std::endl;
370  std::cout << " --progressive or -k [DEFAULT: FALSE] " << std::endl;
371  std::cout << " In this case, only the optimal number of bands will be used for " << std::endl;
372  std::cout << " each sphere, depending on its size. This is in cotrast to the " << std::endl;
373  std::cout << " default all spheres same number of bands setting. " << std::endl;
374  std::cout << " " << std::endl;
375  std::cout << " --usePeaksInRotFun or -z [DEFAULT: FALSE] " << std::endl;
376  std::cout << " Symmetry detection can now be done either using peak detection in " << std::endl;
377  std::cout << " rotation function space, or by default by converting rotation func. " << std::endl;
378  std::cout << " to angle-axis space and finding symmetries there. Using this option " << std::endl;
379  std::cout << " switches to using peak detection in rotation function space. " << std::endl;
380  std::cout << " " << std::endl;
381  std::cout << " --noEnL or -l [DEFAULT: TRUE] " << std::endl;
382  std::cout << " Is the computation of the energy levels descriptor required? " << std::endl;
383  std::cout << " " << std::endl;
384  std::cout << " --noTrS or -m [DEFAULT: TRUE] " << std::endl;
385  std::cout << " Is the computation of the trace sigma descriptor required? " << std::endl;
386  std::cout << " " << std::endl;
387  std::cout << " --noFRF or -n [DEFAULT: TRUE] " << std::endl;
388  std::cout << " Is the computation of the full rotation function descriptor " << std::endl;
389  std::cout << " required? " << std::endl;
390  std::cout << " " << std::endl;
391  std::cout << std::endl << std::flush;
392 
393  //================================================ Done
394  exit ( EXIT_SUCCESS );
395 
396 }

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