BUSTER Documentation : Advanced features

Copyright	© 2003-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

Contents

• The .autoBUSTER system of files and advanced command-line syntax

• The macro feature

• Grouped list of parameters, affecting ...
  • the generation of the TNT sequence file
  • the various checks performed
  • the refinement strategy
  • the analysis for potential, bound ligands
  • solvent structure (water) updating
  • handling of geometric restraints
  • handling of internal cavities (voids)
  • final analysis
  • creation of final PDB file

• Some parameters most likely to be of interest
  • Program for water updating and Water updating criteria
  • Type of B-factor refinement
  • Geometric restraint weights
  • X-Ray weights
  • extra arguments to GELLY
  • controlling output formatting

The .autoBUSTER system of files and advanced command-line syntax

1. (preferred) a command line argument of the form

   parameter="value"

2. To change some installation-wide defaults, a file .autoBUSTER can be placed into the same directory where the 'refine' binary is placed after installation, e.g. $BDG_home/autoBUSTER/bin/linux/.autoBUSTER. A file $HOME/.autoBUSTER (to set user-specific options) or ./.autoBUSTER (to set project-specific options) can also be used. The syntax of these files is:
   • any line starting with hash (#) is a comment (and ignored)
   • each line has the format:

     parameter="value"

     or

     parameter="value-1 value-2 ... value-N"

   Additionally, the environment variable $MyDotAutobuster can point to a file that will be used on top of the above hard-coded files.

Some of these options are described below: if a refinement doesn't behave as expected, or some additional control is required, please let us know: it is possible that some parameters are already available to do what you need.

The macro feature

# Comment line(s) explaining the purpose
# of this macro
__args="-adding -command -line -arguments"
param1=val1
# other comment (ignored)
param2="valA valB"

Notes:

• user-created macros should be placed into (readable) directories, and should have filenames containing only letters and numbers
• those directories need to be set in the environment variable $autoBUSTER_MacroDirs (in a form similar to the colon-separate dlist in PATH)
• a list of available macros is printed with the -M list command-line flag
• macros are processed at the time they appear in the command-line: so later arguments might override settings from a macro
• it is possible to chain macros, i.e. refering to a macro with a "-M" argument within another macro
• the top comment section is printed as part of the "-M list" output
• the special parameter __args will prepend the given list of arguments to the remaining list of arguments when the macro is processed.

Grouped list of parameters

• Parameters affecting the generation of the TNT sequence file (describing connectivity):

  AddMissingSsbondRecords, AdjustBasedOnLinkRecords, AdjustBasedOnLinkRecordsAllowAltloc, AdjustBasedOnLinkRecordsAngleSigma, AdjustBasedOnLinkRecordsBcorrelSigma, AdjustBasedOnLinkRecordsBondCutOffMax, AdjustBasedOnLinkRecordsBondCutOffMin, AdjustBasedOnLinkRecordsBondSigma, AdjustBasedOnLinkRecordsImproperSigma, AdjustBasedOnLinkRecordsMetalsKeep, AdjustBasedOnLinkRecordsMethod, AdjustBasedOnLinkRecordsPlaneSigma, AdjustBasedOnLinkRecordsTrigonalSigma, AdjustFivePrimeEnd, AdjustModifiedAminoAcids, AdjustModifiedNucleotides, AnalyseFivePrimeEnd, AnalyseForModifiedResidues, AnalyseLinkRecords, ExcludeResiduesFromSequence, MaxAllowedCNDistanceInSeq, MaxAllowedOPDistanceInSeq, MinAllowedCNDistanceInSeq, MinAllowedOPDistanceInSeq, SsbondSgDistanceMax, SsbondSgDistanceMin, StandardDictionaries, StandardDictionariesAll, TntDictionary_connect, UseGapAsBreakInSeq.

• Parameters affecting the various checks performed:

  PdbChk_AdditionalChecksToDo, PdbChk_AtomNameUnsupportedCharacters1, PdbChk_AtomNameUnsupportedCharacters2, PdbChk_AtomNamesAgainstStandardRestraintsExclude, PdbChk_AtomNamesAgainstStandardRestraintsWarning, PdbChk_ChecksNotToDo, PdbChk_FixAtomNamesOfResidues, PdbChk_MaxNumToPrint, PdbChk_MaximumCellAngle, PdbChk_MaximumCellEdge, PdbChk_MaximumCellVolume, PdbChk_MinimumCellAngle, PdbChk_MinimumCellEdge, PdbChk_MinimumCellVolume, PdbChk_PossibleChainIds, PdbChk_RecordFormats, PdbChk_TooShortRecordsList, PdbChk_WrongReferenceToCoordinateRecordError, PdbStandardResidues, RemoveScaleCardsFromPdb, RenumberIfBelow, ReuseSequenceFile, RmAnisou, RmAnisouHydrogens, RmLink, RmModres, RunGellySanityCheck, RunGellyScreen, StandardDictionaries, StandardDictionariesAll, UseMtzchk, UsePdbchk, WaterChainId, WaterNamingAtom, WaterNamingResidue, WaterResidueNames.

• Parameters affecting the refinement strategy:

  AdjustXrayWeightAutomatically, AllowBrefInRigidBody, AutomaticRestrictLowres, AutomaticRestrictLowresBinCut, AutomaticRestrictLowresCcCut, AutomaticRestrictLowresFromCycle, BusterCrdMlscalKeyword, BusterExe, BusterExtraArgs, BusterGellyKwd, BusterRigidBodyBimpfFrgLowResCut, BusterRigidBodyBimpfFrgNeverRefine, DoRigidIfCellDiffer, FixXyz, FormfactorCorrection, KeepCurrentRmsBond, KeepHydrogens, KeepZeroOcc, LastCycleBsolv2Bmiss, LastCycleKsolv2Kmiss, LastCycleRefineBmiss, LastCycleRefineKmiss, MxlcycCutBuster, NoOverallBanisoRefinement, PassThroughArgs PassThroughArgsUser ReuseSequenceFile, ScreenNumBuster, ScreenSigmaBuster, ScreenSigmaInitial, SetHydrogensBfixed, SetNonHydrogensADP, StopOnGellySanityCheckError, StopOnMissingContactDistance, TntBfacMax, TntBfacMin, TntWeightGeomRes, UseBrefGroupFrom, UseBrefMcScFrom, UseBrefNoneFrom, UseCrdScaleAfterRigid, UseHighResInRigid, UseLlgradAsFoFc, UseLowResInRigid, UseMapAsNup, UseMapAsSlv, UseMaxEntLastCycle, UseMaxEntThroughout, UseNmissThroughout, blkblr, blkrad, frgrad, mskblr, mskisl, mskrad, mxlcyc_start, nmiss, refocc, refscl_rfr, refscl_rfs, refscl_rif, refscl_rir, refscl_ris, refscl_rkim, refscl_rkis, solc, weight_max, weight_min, weight_start.

• Parameters affecting the analysis for potential, bound ligands:

  AnaPdbmapsCut1, AnaPdbmapsCut2, AnaPdbmapsMinVol, AnaPdbmapsPadding, AnalyseBusterFoFc, AnalyseClusterMethod, LigandDescribingPdbMethod, UseEpdbLastCycle, UseLlgradAsFoFc, UseLpdbLastCycle, UseMxlcycLastCycle, UseNmissLastCycle.

• Parameters affecting solvent structure (water) updating:

  DoWaterRemoveDeleted, KeepAddingWatersAfterN, UpdateWaters, UseSortwater, WaterChainId, WaterFindSigma, WaterFindSigmaLlg, WaterMinDistance, WaterNamingAtom, WaterNamingResidue, WaterPickingOptimise, WaterRemoveDeleted, WaterRemoveDistFac, WaterRemoveMerge, WaterRemoveSigma, WaterResidueNames, WaterUpdateFftResMin, WaterUpdateProgram.

• Parameters affecting handling of geometric restraints:

  AddModifiedAminoAcidToBusterSet, AdjustBasedOnLinkRecords, AdjustBasedOnLinkRecordsAllowAltloc, AdjustBasedOnLinkRecordsAngleSigma, AdjustBasedOnLinkRecordsBcorrelSigma, AdjustBasedOnLinkRecordsBondCutOffMax, AdjustBasedOnLinkRecordsBondCutOffMin, AdjustBasedOnLinkRecordsBondSigma, AdjustBasedOnLinkRecordsImproperSigma, AdjustBasedOnLinkRecordsMetalsKeep, AdjustBasedOnLinkRecordsMethod, AdjustBasedOnLinkRecordsPlaneSigma, AdjustBasedOnLinkRecordsTrigonalSigma, AdjustXrayWeightAutomatically, AnalyseGellySanityCheckForDuplicateBonds, DicFromPdbAllAtomsInBond, ExcludeBadContacts, KeepCurrentRmsBond, MaxAllowedCNDistanceInSeq, MaxAllowedOPDistanceInSeq, MinAllowedCNDistanceInSeq, MinAllowedOPDistanceInSeq, RunGellySanityCheck, StandardDictionaries, StandardDictionariesAll, TntDictionary_assume, TntDictionary_bcorrel, TntDictionary_cofactor, TntDictionary_connect, TntDictionary_contact, TntDictionary_csdx, TntDictionary_nuclgeo, TntDictionary_othergeo, TntDictionary_pdbfixup, TntDictionary_sugar, TransferExoticAAFromSeqToGelly, UseAutomaticDicts, UseAutomaticDictsCcp4, UseAutomaticDictsMsd, UseDictionaryOrder, GeometryWeight_angle, GeometryWeight_bcorrel, GeometryWeight_bond, GeometryWeight_chiral, GeometryWeight_contact, GeometryWeight_improper, GeometryWeight_ncs, GeometryWeight_plane, GeometryWeight_pseudo, GeometryWeight_torsion, GeometryWeight_trigonal. GeometryWeight_ideal.

• Parameters affecting handling of internal cavities (voids):

  AnaVoids_dist_and, AnaVoids_dist_and_fac, AnaVoids_dist_not, AnaVoids_dist_not_fac, AnaVoids_rmss, AnalyseVoids, AnalyseVoidsAlways, AnalyseVoidsLast.

• Parameters affecting final analysis:

  AnalyseExtraEpdbs, AnalysePictureCarve, AnalysePictureLarge, AnalysePictureLevel_2FoFc, AnalysePictureLevel_FoFc, AnalysePictureSmall, do_analyse, do_maps, FinalMapsCoverPdb, FinalMapsNormalized.

• Parameters affecting creation of final PDB file:

  AssumePdbFromRefinerCorrect, RunCor2Pdb, RunHarvest, RunSfcheck.

Some parameters most likely to be of interest

1. There are two programs available for adding/removing/updating waters: arp_waters (from the CCP4 suite - especially written for updating of the water/solvent structure) or pkmaps (from SHARP/autoSHARP). The default (for the moment) is to use pkmaps (which might be better when the goal is to explain positive difference density through 'waters').

   There is also the possibility to use an external program/script for this task: in that case the absolute path to this program/script should be given. This script will be given the arguments

   1. current PDB file
   2. MTZ file for 2mFo-DFc map (columns 2FOFCWT/PH2FOFCWT)
   3. MTZ file for mFo-DFc map (columns FOFCWT/PHFOFCWT)
   4. (sub-)directory for this run (e.g. for writing additional or temporary output to)
   5. name of output PDB file (should be a copy of the input PDB file as much as possible, with only the waters updated)
   6. (optional) PDB file with coordinates of waters that have already been removed in previous steps

   The parameter WaterUpdateProgram can be either set to "PKMAPS", "ARP_WATERS" or the absolute path of a user-supplied program/script.

   The levels for adding removing waters can be controlled using the parameters WaterFindSigma, WaterRemoveSigma and WaterRemoveMerge

   To completely switch off the update of solvent structure (or delay it for a few initial BIG cycles) see the -noWAT command line switch.

2. The resolution limits where different B-factor refinement schemes are used can be set with the parameters UseBrefNoneFrom, UseBrefGroupFrom and UseBrefMcScFrom. To enforce a specific B-factor refinement scheme, the command line flag -B can be used.

   The parameters to -B are

   individual	Refine one B-factor per atom. This is almost always the right option to use
   group-mcsc	Refine one B-factor shift for each main chain (N, C, CA, O) and another for the side chain
   group-res	Refine one B-factor shift for each residue
   None	Do not change the B-factors from the input file

   Note that BUSTER refines B-factor shifts within groups; it is therefore important to use the InitialiseBiso option when using grouped B refinement. Either pick an initial B-factor that you think appropriate, or use InitialiseBiso=wilson.

   If a grouped B-factor refinement scheme is selected, the restraint in temperature factors of bonded atoms (BCORREL) could be switched off using the GeometryWeight_bcorrel parameter.

3. The various (relative) weights on geometric restraints can be set with the parameters GeometryWeight_bond, GeometryWeight_angle, GeometryWeight_torsion, GeometryWeight_plane, GeometryWeight_trigonal, GeometryWeight_chiral, GeometryWeight_contact, GeometryWeight_bcorrel, GeometryWeight_ncs, GeometryWeight_improper, GeometryWeight_pseudo and GeometryWeight_ideal.

4. To change the starting X-ray weight (and associated minimum and maximum allowed values), use the XrayWeight_start, XrayWeight_min and XrayWeight_max parameters. autoBUSTER will automatically adjust the X-ray weight, unless told not to do so.

5. GELLY has its own set of additional command-line arguments that can be added using the BusterExtraArgs parameter.

6. controlling output formatting can be done by setting the environment variable $autoBUSTER_NO_HIGHLIGHT to a non-empty value. This will supress the use of certain escape sequences to create bold, underline or italic characters. Please note that this needs to be set as an environment variable, rather than an option on the refine command line!