FAQ
Content
- General
1.1. Does BALL compile on platform X/with compiler Y?
1.2. Does BALL run under MacOS?
1.3. Why do Flex/Bison generated files not compile?
- BALL Library
2.1. How to cite BALL?
2.2. Why do my .hin files contain one molecule per atom?
2.3. Are the RMSDs calculated by StructureMapper ok?
2.4. How to fix BALL applications crashing with "problem converting '1.33' to a number"?
2.5. Why does my python script crash?
- BALLView
3.1. How to cite BALLView?
3.2. Why does the BALLView color dialog freeze the application?
3.3. Why does my cursor "smear" in the 3D view?
3.4. Why is the Editing/Picking mode so slow?
3.5. Where is my newly computed Secondary Structure?
3.5.1. How can I show hydrogen bonds in BALLView?
3.6. The computation of hydrogen bonds seems not to work.
3.7. What is the difference between the highlighting and the selection concept?
3.8. How can I add missing hydrogens in BALLView?
3.9. Why do the added hydrogens have strange positions?
3.10. What is the difference between "Saturate with Hydrogens" and "Add Hydrogens" in the Build menu?
3.11. Which method is mapped to the Toolbar entry "+H"?
3.12. Why does the edit mode not work?
3.13. How can I change the representation type?
3.14. How can I change the background color in BALLView?
3.15. How can I improve my screenshots?
3.16. Why does my offscreen rendering not work?
3.17. Why does BALLView not show my loaded molecule?
3.18. What is the difference between "Modify Model" and "Modify Representation"?
3.19. Why does minimization via python not work"?
Questions and Answers
1.1. Platforms
Does BALL compile on platform X/with compiler Y?
BALL 1.2 has been successfully built and tested on the following platforms:
- Linux/x86 2.x using g++ 4.1.2
- Linux/x86_64 2.x using g++ 4.1.2
The Versions below are for BALL 1.0
- Solaris/SPARC 8 using g++ 3.2.1
- Solaris/SPARC 8 using g++ 2.95.3
- Solaris/SPARC 8 using SUN Forte Developer 7 C++ 5.4 2002/03/09
- IRIX 6.5 using CC 7.3.1.1m (32 and 64 bit)
- Microsoft Windows XP using Microsoft Visual Studio .NET (MSVC 7.0)
It should run on a number of additional platforms without too many problems, although these platforms have not been tested by us.
1.2. Compiling under MacOS
How can I compile BALL under MacOS 10.2/Darwin?
MacOS 10.2/Darwin is not yet a supported platform. However, it is possible to compile BALL if you use a recent snapshot (after 04/16/03). There's lots of trouble with the standard C headers provided with Darwin (for example, you cannot include math.h and cmath or you run into trouble with isnan and related functions, xdr.h seems to be broken, etc.). To compile just the core, grab a recent snapshot and configure with:
./configure --without-xdr --without-BALLVIEW
Then, you will have to build static libraries:
make depend make staticlibs ranlib libBALL.a make install.static
There's also a fixed version of xdr.h here, which has to be placed in a directory BALL/include/BALL/rpc (you will have to create this one). With this file you should be able to compile with XDR support. We still have some trouble getting BALL to work with dynamic libraries -- any help appreciated. We haven't tested BALL with QT/X11 yet. There's some reason to believe it should work if you call configure with:
./configure --with-qt-incl=/sw/include/qt/ --with-qt-libs=/sw/lib/ --with-qt-mt
Please let us know if you are interested in this platform or know how to improve things. Thanks!
1.3. Flex/Bison? problem
On some platforms bison/flex fail in the BALL installation process.
For some platforms and headers, the throw specifiers of the code produced by flex/bison are incorrect.
Up till now this error has been reported for the following files:
- BALL/source/KERNEL/expressionParserLexer.C
- BALL/source/MATHS/parsedFunctionLexer.C
- BALL/source/STRUCTURE/smilesParserLexer.C
This can be fixed by changing:
extern int isatty YY_PROTO(( int ));
to:
extern int isatty YY_PROTO(( int )) throw();
if the compiler fails with this error message:
error: declaration of `int isatty(int)' throws different exceptions /usr/include/unistd.h:712: error: than previous declaration `int isatty(int)throw ()'
Then, build the library with make
BALL version 1.2 has a builtin fix for this problem, so this should not occur. However if you compile BALL with e.g. make -j 2 this can still happen.
2.1. Citing BALL
How should I refer to BALL in papers or theses?
Please cite the following publication for all results that were obtained using BALL:
Andreas Hildebrandt, Anna Katharina Dehof, Alexander Rurainski, Andreas Bertsch, Marcel Schumann, Nora C Toussaint, Andreas Moll, Daniel Stockel, Stefan Nickels, Sabine C Mueller, Hans-Peter Lenhof, Oliver Kohlbacher: "BALL - Biochemical Algorithms Library 1.3", 2010, BMC Bioinformatics, 11:531
Or, as BibTeX:
@Article{HildebrandtEtAl2010,
AUTHOR = {Hildebrandt, Andreas and Dehof, Anna Katharina and Rurainski, Alexander and Bertsch, Andreas and Schumann, Marcel and Toussaint, Nora and Moll, Andreas and Stockel, Daniel and Nickels, Stefan and Mueller, Sabine and Lenhof, Hans-Peter and Kohlbacher, Oliver},
TITLE = {BALL - Biochemical Algorithms Library 1.3},
JOURNAL = {BMC Bioinformatics},
VOLUME = {11},
YEAR = {2010},
NUMBER = {1},
PAGES = {531},
URL = {http://www.biomedcentral.com/1471-2105/11/531},
DOI = {10.1186/1471-2105-11-531},
PubMedID = {20973958},
ISSN = {1471-2105},
ABSTRACT = {BACKGROUND:The Biochemical Algorithms Library (BALL) is a comprehensive rapid application development framework for structural bioinformatics. It provides an extensive C++ class library of data structures and algorithms for molecular modeling and structural bioinformatics. Using BALL as a programming
toolbox does not only allow to greatly reduce application development times but also helps in ensuring stability and
correctness by avoiding the error-prone reimplementation of complex algorithms and replacing them with calls into the
library that has been well-tested by a large number of developers.
In the ten years since its original publication, BALL has seen a substantial increase in functionality and numerous other improvements.RESULTS:Here, we discuss BALL's current functionality and highlight the key additions and improvements: support for additional file formats, molecular edit-functionality,
new molecular mechanics force fields, novel energy minimization techniques, docking algorithms, and support for cheminformatics.% and QSAR studies.CONCLUSIONS:BALL is available for all major operating systems, including Linux, Windows, and MacOS X.
It is available free of charge under the Lesser GNU Public License (LPGP). Parts of the code are distributed under
the GNU Public License (GPL). BALL is available as source code and binary packages from the project web site at \texttt{http://www.ball-project.org}. Recently, it has been accepted into the debian project; integration into further distributions is currently pursued.
},
}
2.2. Single atoms
When I write the contents of PDB files as HIN files, the resulting file contains loads of molecules each containing just one atom. What's going on?
You did not construct bonds. PDB files do (usually) not contain bonds. However, Hyperchem HIN files define "molecules" as sets of fully connected atoms (connected components). Therefore, if you do not have any bonds, each atom has to be written as its own molecule in order to comply with the Hyperchem file format. In order to avoid this problem, you should construct the bonds prior to writing the HIN file. This can be achieved by code similar to the example below:
// Read a PDB file. PDBFile infile("test.pdb"); System S; infile >> S; // Construct a fragment database containing the required // topology information and construct the bonds in the system. FragmentDB frag_db; S.apply(frag_db.build_bonds); // Write the system to a Hyperchem file. HINFile outfile("test.hin", File::OUT); outfile << S;
2.3. StructureMapper RMSD values
RMSDs calculated with StructureMapper seem to have strange values. What is wrong?
If your RMSDs seem to have strange values, make sure that all the atoms you want to map on each other are actually mapped by the StrucureMapper. You can check this by looking at the number of bijections the StructureMapper finds. Say you have one small molecule in two different positions and want to know how much they differ. To get a reasonable RMSD, you would want the Mapper to map every atom. Check this with the following code:
// Map two molecules with the same number of atoms StructureMapper structure_mapper(molecule1, molecule2) // Check, whether the StructureMapper mapped every atom Size number_of_bijections = structure_mapper.getBijection().size(); if (number_of_bijections != molecule1.countAtoms()) { Log.warn() << "WARNING: not all atoms were mapped." << std:endl; }
One reason for an incomplete mapping might be insufficient naming of the atoms in a molecule. If, for instance, your molecule comes from a HyperChem file and all atoms are named "-", then the StructureMapper cannot distinguish between different atoms. Give those atoms unique names and you will be fine.
2.4. "problem converting '1.33' to a number"
When starting BALLView or any other BALL applications, on some Linux/Unix? platforms users may get error messages like 'problem converting "1.33" to a number' and all kind of strange behaviour.
This is a problem generated by the local settings on your computer. The conversion of floating point numbers fails if you have set the language to german. Until we come up with a better solution, you may try
export LANG=C
or
export LC_NUMERIC="."
or
export LC_ALL=en
before starting BALLView or any other BALL application. This should fix your problems...
2.5. Python script crashes
Running your own python script in BALLView leads to crashes.
When running python scripts interactively like in BALLView, users have to account for the following specialites of python:
- Take care that you have to remain consistent in your use of either tabs or plain spaces for python indentation. Python relies on the relative indentation of nested blocks to determine the grouping of statements correctly.
- Take care that your script ends with two empty lines. Python needs them to interprete the end of the script.
- For running a python script using BALL functionalities outside of BALLView you need to set the LD_LIBRARY_PATH correctly and you need to import the BALL-Library in your script
import BALL
3.1. Citing BALLView
How should I refer to BALLView in papers or theses?
Please cite the following publication for all results that were obtained using BALLView:
Moll, Andreas, Hildebrandt, Andreas, Lenhof, Hans-Peter, and Kohlbacher, Oliver BALLView: A tool for research and education in molecular modeling Bioinformatics (2006), 22(3):365-366
http://www.ncbi.nlm.nih.gov/pubmed/16332707 and
Moll, Andreas, Hildebrandt, Andreas, Lenhof, Hans-Peter, and Kohlbacher, Oliver BALLView: An object-oriented molecular visualization and modeling framework Journal of Computer-Aided Molecular Design(2005), 19(11):791-800
http://www.ncbi.nlm.nih.gov/pubmed/16470421
3.2. BALLView ColorDialog
Whenever I try to use a ColorDialog, e.g. to set the background color of the stage or color a surface, BALLView freezes. What is wrong?
This is a known QT-Problem on Linux/Unix? platforms. A workaround is to delete the .qt folder in your homedirectory.
3.3. Problem with cursor in 3D view
On some Linux/Unix? machines the 3D view is "smeared" with the cursor or the underlying content of the 3D view.
To prevent this, try to add the following to your xserver configuration file (e.g xorg.conf or XF86config) in the section Screen:
Option "HWCursor" "true"
Also make sure, that SW_CURSOR is not set.
3.4. Picking/Editing? mode is slow
Users may experience several second long lags in the editing / picking mode when an atom gets selected.
On some platforms this may happen if a multi-monitor environment is used. This results from a bug in the OpenGL drivers. To circumvent this limitation, try to disable the second monitor or TV output.
3.5. Newly Computed Secondary Structures Not Shown
Why can't I see / Where is my newly computed Secondary Structure?
The Secondary Structure can be shown in the Structures window by choosing "Show Secondary Structures" in the right-mouse-button menu of the desired molecule in the Structures window. The Secondary Structure can be visualised by choosing the representation mode "Cartoon by Secondary Structure".
3.5.1. Show Hydrogen Bonds
How can I show hydrogen bonds in BALLView?
Hydrogen bonds can be computed using BALL's HydrogenBondProcessor?. In BALLView this can be done by highlighting a protein's system and clicking "Tools" --> "Calculate HBonds". The resulting hydrogen bonds can be visualised by choosing the representation mode H-Bonds by e.g. element.
3.6. Newly Computed Hydrogen Bonds Not Shown
The computation of hydrogen bonds seems not to work. / Where are my newly computed hydrogen bonds placed?
After computation, the hydrogen bonds have to be visualised by choosing the representation mode H-Bonds by e.g. element.
3.7. Highlighting versus Selecting
What is the difference between the highlighting and the selection concept?
In BALLView clicking on a structure's name is referred to as "highlighting" structures. This is used e.g. for creating representations. Activating the check box in the Structures window sets a Selection. This concept is used e.g. for defining objects subjected to minimization. All "selected" representations are colored with the selection-colour (default is yellow) Selecting a structure corresponds to calling the select method in the BALL library.
3.8. Adding Missing Hydrogens in BALLView
How can I add missing hydrogens in BALLView?
We have to distinguish two cases: proteins and non-proteins. For proteins in general, hydrogens are not contained in pdb files as they can hardly be measured by x-ray crystallography. Hydrogens can be added in BALLView by highlighting the protein's system and clicking "Build"-->"Add Hydrogens". In case of ligands, choose the "Add Hydrogen" method in the Build menu. Note that the positions of the added hydrogens are kind of random. To get more reliable atom positions for the added hydrogens, select all added hydrogens (e.g. using the SMARTS-matcher "element(H)"), right-mouse-click on the Composite (e.g. system or molecule), to which hydrogens have been added, and choose "Highlight Selection". Finally, run an energy minimization by clicking "Molecular Mechanics"-->"Energy Minimization".
3.9.Set Hydrogen Positions
Why do the added hydrogens have strange positions?
Hydrogens that were added by "Saturate with Hydrogens" or "Add Hydrogens" of the Build menu have kind of random positions. To optimize the positions select all hydrogens whose positions should be improved. This can be done very easily using the BALL expressions matcher (bottom of the Structures window). Type "element(H)" and press "Select". Right-mouse-click on the Composite (e.g. system or molecule), to which hydrogens have been added, and choose "Highlight Selection". Finally, run an energy minimization by clicking "Molecular Mechanics"-->"Energy Minimization".
3.10. Saturate with Hydrogens versus Add Hydrogens
What is the difference between "Saturate with Hydrogens" and "Add Hydrogens" in the Build menu?
"Add-Hydrogens" adds hydrogens and other missing atoms based on BALL's FragmentDatabase?, where common fragments like amino acids or DNA are specified. "Saturate with Hydrogens" uses a simple heuristic to add hydrogens wherever the atoms have free valences. Note that in both cases the hydrogen's positions have to be further optimized.
3.11. Toolbar Hydrogens Method
Which method is mapped to the Toolbar entry "+H"?
The "+H" button calls the "Saturate with Hydrogens" method.
3.12. Edit mode does not work
Why does the edit mode not work?
A very common mistake is, that the chosen/active representation is set to a non-atom-level type. This can be changed via the context menu of the current representation:
- Right-click the structure you want to edit.
- Choose "Modify Model".
- Now choose e.g. the "Ball and Stick" model.
Another reason can be, that the camera is not focused on your new molecule. Mouse right click on the Structure (e.g. System, Residue, or Atom) in the Structures window and choose "Focus". It is also possible, that no molecule is highlighted so BALLView does not know in which structure the new atoms have to be created.
3.13. Change Representation Type
How can I change the representation type?
Representations can be changed by right mouse clicking on an existing representation and choosing "Modify Model". Representations can be added by right mouse clicking on the Structure (e.g. System, Reside, or Atom) and choosing "Create Representation". In the following menu first select a representation type, then the colouring method. The default representation model can be set via "Display"-->"Display Properties".
3.14. Change Background Color
How can I change the background color in BALLView?
Open the Preference dialog via the Edit menu, in the left list view double click on the entry "Display", then select "Main". By clicking on the "Edit" button in the group box "Background color" a "Select color" dialog opens where the background color can be changed.
3.15. Screenshots
How can I improve my screenshots?
Activate the offscreen rendering option in the Preferences dialog: Open Main-Menu "Edit"--> "Preferences" --> Entry "Display" --> Main. Activate the checkbox in the lower right corner "Use offscreen rendering for PNGs". Furthermore you can activate the antialiasing option of your graphics card. If you are still not satisfied with your obtained results, you should consider to export your scene to POVRay via "File" --> "Export Image" --> "POVRay Scene". Please note the following entry!
3.16. Offscreen Rendering does not work
Why does my offscreen rendering not work?
This problem is related to the graphics cards or the graphic cards drivers. Older OpenGL versions (older than 2 years, laptops...) seem to not support offscreen rendering. Solution: either resize your BALLView as large as possible, go into Fullscreen by clicking "Display" --> "Toogle Fullscreen" and export the scene as png (return by again clicking "Display" --> "Toogle Fullscreen"). If you have access to a BALLView on a computer, whose graphic card supports offscreen rendering, just export your current scene as BALLView-Project by clicking "File" --> "Save Project", load it on this other BALLView and export the scene there. If you need really good picture quality with shadows, you can use the POVRay exporter. A POVRay file will be created containing the corresponding POVRay command within the first lines as comment.
3.17. Loaded Molecule not shown
Why does BALLView not show my loaded molecule?
BALLView remembers your last created representation model. It may happen that this model is not suited for your newly loaded molecule, e.g. there are no Secondary Structures to be shown. The default representation model can be changed by clicking "Display"-->"Display Properties". A representation can be changed directly via the Right-mouse-click menu entry "Modify Model" of the respective representation in the Representations window. Another reason for not seeing the newly loaded molecule can be a wrong focus. This can easily happen, if several molecules were loaded into BALLView. The focus can be changed by either selecting the molecule of interest in the Structures window or one of its representations in the Representations window and right mouse clicking "Focus".
3.18. Modify Model versus Modify Representation
What is the difference between "Modify Model" and "Modify Representation"?
"Modify Model" opens a dialog for switching between different representation modelse.g. Ball-and-Stick, Van-der-Waals (VDW), or Solvent-excluded-Surface (SES). The dialog can be accessed via either clicking "Display"-->"Display Properties" or the Right mouse click menu of a representation in the Representations window. "Modify Representation" offers a dialog to for changing the representation type (not model!) parameters like Color by Grid, Material Settings, or the Drawing Mode. This dialog can be accessed via either clicking "Display"-->"Modify Representation" or the Right mouse click menu of a representation in the Representations window.
3.19. Minimization using the Python interpreter
Why does minimization via python not work?
Suppose you wrote code like this:
clearAll() mol2 = MOL2File("~/scripts/BetulinicAcid.mol2") S = System() mol2.read(S) getMainControl().insert(S) getMolecularStructure().runMinimization(False)
And you are wondering that the last statement has no effect. There are 2 causes for this:
- You need to highlight the structure you wish to minimize.
- The BALLView GUI and the Python interpreter are running in a different thread. Thus if you pass data from Python to the GUI it might take a while until this change is applied. In order to wait for this change to happen, you need to tell Python to wait for the GUI thread.
This can be achieved by the two lines added to the script:
clearAll() mol2 = MOL2File("~/scripts/BetulinicAcid.mol2") S = System() mol2.read(S) getMainControl().insert(S) #Highlight the inserted system getMolecularControl().highlight([S]) #Wait for the threads to synchronize getMainControl().wait() getMolecularStructure().runMinimization(False)
