ProSHADE: ProSHADE_internal_messages Namespace Reference

| ProSHADE 0.7.5.1 (JAN 2021) Protein Shape Detection

Functions
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] | verbose | Int value stating how loud the user requested the ProSHADE run to be.
  [in] | messageLevel | Int value stating how important the message is.
  [in] | message | String 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] | verbose | Signed 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] | verbose | Int value stating how loud the user requested the ProSHADE run to be.
  [in] | message | String of the actual message to be displayed.
  [in] | message | String 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] | verbose | Signed 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 }