| BUSTER Documentation | previous next |
| buster-report |
Copyright
© 2011-2020 by Global Phasing Limited
All rights reserved.
This software is proprietary to and embodies the confidential
technology of Global Phasing Limited (GPhL). Possession,
use, duplication or dissemination of the software is authorised
only pursuant to a valid written licence from GPhL.
Contact
buster-develop@GlobalPhasing.com
buster-report is a tool for providing clear reports about the progress of and the results from a run of BUSTER. It includes mogul-based reporting of the geometric properties of the ligands in the output file, and a molprobity analysis of the protein geometry including unusual-rotamer information.
The report is intended to contain enough information about the refinement that it would be possible to delete the refinement directory and keep the report; for example, it contains the output PDB and MTZ files, the full contents of the CIF dictionaries given on the command line, and enough information about geometry outliers that you can run visualise-geometry-coot on an output directory from buster-report.
For example buster-report outputs and tutorials about using the program and interpreting its output please see the buster-report page on the BUSTER wiki.
| Option | Arguments | Explanation | Remarks |
|---|---|---|---|
| -h | Display usage information | Special option to print help message and exit | |
| -checkdeps | Check that all the dependencies are present | Special option that checks that the external tools buster-report needs are accessible and work properly. Useful for setting up buster-report and testing that the program works on a particular host. This option is one of the tests run by the checkdeps script. | |
| -d | <BUSTER refinement directory> | The refine -d directory on which to produce a report. | This is the only option that must be specified. |
| -dr | <output directory> | The place to put the report | optional, by default report directory name will be based on the BUSTER refinement directory with -report added to it. |
| -ligand | XXX,XXY,XXZ | A comma-separated list of only the ligands you want to see reports on | If you use both -ligand and -boring then the -boring request will be ignored |
| -boring | NAD,FAD | Specify a comma-separated list of the three-letter codes of ligands not to report on in addition to the defaults. For instance use -boring NAD,FAD to add NAD and FAD to list of "boring" ligands, so that you do not get a report for your co-factor. | The default list of three-letter codes regarded as boring: HOH, MSE, PO4, SO4, EDO, EOH, GOL, FMT, ACT, ACE, CIT, BOG, MPD, TAM, BTB, EPE, MES, PIN, DMS, DTT, 15P, PG4, PE5, MAN, NAG, C8E, BMA, GAL, L2P, LFA, SCN, " DA", " DC", " DG" and " DT" |
| -interesting | MSE,GOL | Specify a comma-separated list of ligands that should be removed from boring list. | For instance to report on MSE and GOL use -interesting MSE,GOL |
| -title | <title> | The title to display on the report. | This title will be used at the top of the report as well as appearing in both the html and pdf browser toolbars. The default title is Report on BUSTER refinement run in directory followed by the directory as specified in -d |
| -EDcontours | <C2mFo-DFc,CmFo-DFc> | Alter the contour levels used in the electron density around ligand pictures. | Two positive floating values must be specified separated by a comma. The first value C2mFo-DFc specifies the contour level (in rmsd units) used for the 2mFo-DFc map (grey). The second value CmFo-DFc specifies the positive and negative contour levels (in rmsd units) used for the mFo-DFc difference map (green/red). So specifying 1.3,3.5 would contour the 2mFo-DFc map at 1.3 rmsd and the difference map at +3.5 and -3.5 rmsd. The default values are 0.7,3.0. To override these defaults, set the environment variable BDG_BR_EDCONTOURS to a string with your desired values (separated by a comma). |
| -dname | <name> | The name to use for the .pdb and .mtz files in the report | Default name is the directory as specified in -d. This option is useful to give files recognisable names in the coot display manager window, particularly when using visualise-geometry-coot. |
| -f | Overwrite the output directory if it already exists | If you do not specify -f then buster-report will not overwrite an existing directory but instead will terminate with an error. | |
| -delete | Delete the input directory if buster-report runs without error | If you find yourself entirely happy with buster-report output then you might want to use this option to save some disc space. Please note that buster-report is being improved. | |
| -nopdf | Do not produce a PDF version report as well as the HTML. | The same thing can be achieved by setting environment variable $BDG_TOOL_PDFLATEX to none | |
| Produce a PDF version of the report | This option is now redundant as this is the new default. | ||
| -nomogul | Do not do any Mogul analysis of the final ligand geometry. | The same thing can be achieved by setting environment variable $BDG_TOOL_MOGUL to none | |
| -nopic | Do not draw pictures of ligands | Do not draw any pictures of ligand density or ligand outliers. The same thing can be achieved by setting environment variable $BDG_TOOL_PYMOL to none | |
| -nolig | Do not do any ligand analysis. | No ligand analysis will be done. This is a more drastic option than -nomogul or -nopic. | |
| -nomp | Do not do the MolProbity analysis | The same thing can be achieved by setting environment variable $BDG_TOOL_MOLPROBITY_ROOT to none. | |
| -png | Use PNG format rather than SVG for graphs | SVG graphs look considerably better in Firefox but do not display correctly in some versions of Internet Explorer | |
| -oldcolors | Use old primary colors for ligand Geometry analysis where bad is ed, poor is orange, ok is green and good is blue. | The new default is a purple to green scale that is clearer and better for color-blind people. | |
| -pyray | Run correctly with certain older versions of pymol | If the -pyray option is needed, buster-report will display an warning message advising you to use it |
buster-report uses a number of programs (tools) to produce its report, some are optional but others must be installed for buster-report to run. buster-report will first then check whether a tools location is defined by the relevant environment variable has been defined. If the environment variable is not defined then the tool will be found from the user's $PATH. Tools provided by the operating system will automatically be added to the user's $PATH and are best provided in this way. It is recommend that other tools are defined using environment variables are these are set in the files $BDG_home/setup_local.sh and $BDG_home/setup_local.csh as explained in the detailed installation instructions..
To check whether the external tools used by buster-report are properly setup then use:
| % buster-report -checkdeps |
The following table describes each of the external tools used by buster-report
| Program | required or optional? | Environment Variable | Remarks |
|---|---|---|---|
| ImageMagick convert | required | $BDG_TOOL_CONVERT can be set to the full path for the convert executable. |
Normally provided by an operating system supplied package and so convert will normally be found from the user's $PATH. |
| ImageMagick identify | required | $BDG_TOOL_IDENTIFY can be set to the full path for the identify executable. |
Normally provided by an operating system supplied package and so identify will normally be found from the user's $PATH. |
| Ghostscript ps2pdf | required | $BDG_TOOL_PS2PDF can be set to the full path for the ps2pdf executable. |
Normally provided by an operating system supplied package and so ps2pdf will normally be found from the user's $PATH. |
| xmgrace gracebat | required | $BDG_TOOL_GRACEBAT can be set to the full path for the gracebat executable. |
Normally provided by an OS supplied package and so gracebat will normally be found from the user's $PATH. Some recent Ubuntu versions have gracebat that produce mangled xml buster-report -checkdeps will detect these. See URL for details. |
| CCDC mogul | optional: turn off with argument -nomogul or by setting $BDG_TOOL_MOGUL to none | $BDG_TOOL_MOGUL should be set to the full path for the mogul executable or none. Also used by grade (optional) and grade_PDB_ligand (optional). $BDG_MOGUL_LOCAL_DATABASE_FILE can be set to provide support for Mogul with additional in-house libraries |
mogul is used to check ligand geometry against CSD small molecule structures.
buster-report -checkdeps should be used to check that the mogul licence works. To get the licence working run
mogul interactively and fill in the licence information.
There have been some reports of issues using mogul from initial 2014 release of Cambridge Structural Database System (CSDS) if CSDS is installed on a NFS-mounted file system, see https://www.globalphasing.com/buster/wiki/index.cgi?SoftwareMogulRelease2014NFSissues. See below for support for Mogul with additional in-house libraries |
| Open Babel obabel | optional: turn off by setting $BDG_TOOL_OBABEL to none | $BDG_TOOL_OBABEL should be set to the full path for the obabel executable or none. Also used by grade (optional) and grade_PDB_ligand (optional). |
obabel is used to generate 2D coordinates for ligands used in 2D schematic pictures. Versions 2.3.0 and 2.3.1 work. obabel is supplied by some operating systems. |
| MolProbity | optional: turn off with argument -nomp or by setting $BDG_TOOL_MOLPROBITY_ROOT to none | $BDG_TOOL_MOLPROBITY_ROOT should be set to the full path of the root directory of the MolProbity installation or none. The root directory of the MolProbity installation must contain the files: cmdline/reduce-nobuild, cmdline/multichart and lib/hless.jar Also used by hydrogenate and aB_hydrogenate (required). |
buster-report will run MolProbity in a batch mode. Note that there is no need to install apache as buster-report does not use the web interface. Tested with both the new 4.02b version of MolProbity available from http://molprobity.biochem.duke.edu/ and the old 3.19 http://helix.research.duhs.duke.edu/. Make sure that you have configured MolProbity with the setup.sh script supplied with MolProbity as per the instructions. |
| java | optional: but needed by MolProbity, turn off with argument -nomp or by setting $BDG_TOOL_MOLPROBITY_ROOT to none | $BDG_TOOL_BUSTERREPORT_JAVA can be set to the full path for the java executable (unless it is on the $PATH). |
Normally java will be on the users $PATH. Note that gij cannot be used (buster-report will check for this and stop with an ERROR message if gij is used) |
| pymol | optional: turn off with argument -nopic or by setting $BDG_TOOL_PYMOL to none | $BDG_TOOL_PYMOL can be set to the full path for the pymol executable (unless it is on the $PATH). |
Most OS's provide a pymol package. buster-report works will all versions tested. |
| latex | optional: turn off with argument -nopdf or by setting $BDG_TOOL_PDFLATEX to none | $BDG_TOOL_PDFLATEX can be set to the full path for the latex executable. |
Most OS's provide a latex package and if this is used then pdflatex will be on the users $PATH. |
# YourCompanyName private Mogul database DD-MMM-YYYY using NNNNN structures. MOGUL DATA LIBRARY /path/to/library/ MOGUL DATA DATABASE /path/to/database/file MOGUL DATA CSD ONPlease include an informative comment as the first line of the file as this will be included in buster-report, grade and grade_PDB_ligand output. Once you have prepared the file specify its location (including the full file path) by environment variable $BDG_MOGUL_LOCAL_DATABASE_FILE as described above.
Furthermore, it is possible to configure buster-report to hyperlink the ID to a relevant public or private page for that ligand. This is done automatically for PDB ligands whose dictionary is produced by grade_PDB_ligand. For an example see Ligand report pages for 2h7p in HTML and PDF formats, noting the hyperlinks 468 (PDB) to the RCSB page for the ligand. To configure buster-report to produce a hyperlink specific for your site it is necessary to set the environment variables $BDG_BR_DATABASEID_MATCH and $BDG_BR_DATABASEID_SUBSTITUTE.
For example if you where working on a ligand that has a pubchem ID of CID447873 then use the grade command line option -databaseid CID447873:
grade -in 447873.mol2 -resname LIG -databaseid CID447873buster-report will then use the identifier CID447873 instead of the three letter code LIG when describing the ligand. To present a hyperlink to allow further information for the ligand to be found then the environment variable BDG_BR_DATABASEID_MATCH should be set to a regular expression that matches the identifier (and stores the ligands code):
# for bash/sh/ksh/... use: export BDG_BR_DATABASEID_MATCH='CID(\d*)' # for tcsh/csh use: setenv BDG_BR_DATABASEID_MATCH 'CID(\d*)'The environment variable BDG_BR_DATABASEID_SUBSTITUTE is then used to define how the matching identifier should be processed to a hyperlink. For example for the pubchem example:
# for bash/sh/ksh/... use: export BDG_BR_DATABASEID_SUBSTITUTE='"'"<a href='http://pubchem.ncbi.nlm.nih.gov/compound/"'$1'"'>CID"'$1</a>"' # for tcsh/csh use: setenv BDG_BR_DATABASEID_SUBSTITUTE '"'"<a href='http://pubchem.ncbi.nlm.nih.gov/compound/"'$1'"'>CID"'$1</a>"'This defines a rule where the databaseid of CID447873 is presented as a hyperlink to http://pubchem.ncbi.nlm.nih.gov/compound/447873. If you need help to define a rule for your corporate intranet then please email buster-develop@GlobalPhasing.com and we can help (getting the single and double quotation marks correct is fiddly).
If you want to specify multiple ligand corporate id substitution patterns then this can be achieved by using an additional match/ substitute pair BDG_BR_DATABASEID_MATCH0 / BDG_BR_DATABASEID_SUBSTITUTE0. For yet another substitution pattern use BDG_BR_DATABASEID_MATCH1 / BDG_BR_DATABASEID_SUBSTITUTE1, and so on through to BDG_BR_DATABASEID_MATCH9 / BDG_BR_DATABASEID_SUBSTITUTE9. (If you need more than eleven patterns let us know!).