autoBUSTER Documentation previous next
buster-report

autoBUSTER Documentation : buster-report

Copyright    © 2011-2015 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


Contents


Using buster-report

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.

buster-report command-line options

Note that options can be abbreviated provided there is no ambiguity created.
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
-pdf 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

External tools used by buster-report

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 (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.

Support for Mogul with additional in-house libraries

In late 2014 CCDC provided to selected corporate users a facility to prepare additional libraries for Mogul containing information taken from in-house databases of small molecule structures. If you have this facility then these libraries can be used by buster-report, grade and grade_PDB_ligand. To do this prepare a file containing Mogul instructions to use the libraries following this template:
# 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 ON
Please 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.

Support for ligand corporate or database IDs

One of the many problems caused by the use of old style PDB format is the restriction to three characters for residue codes (for example ATP or GOL). This often means that pharmaceutical users routinely use residue code like INH, LIG or L01 for all their ligands. To produce a more useful ligand analysis output a grade command line option -databaseid has been introduced that allows the corporate or database ID for the ligand to be specified. This ID will be prominently displayed on the buster-report ligand analysis page.

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 CID447873
buster-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!).


Last modification: 10.08.2015