Main window

Toolbar

Activate RMSD and PBS frames

 The visibility of the two other windows can be toggled from the View menu or by pressing the corresponding button

Import

 To start a new project, the initial model and experimental data need to be provided. To look at the structure available from the Protein Data Bank, click the PDB button

or use File/Import/PDB menu item. This will attempt to download the pdb and cif files from the http://www.rcsb.org. This may fail for several reasons described here.
If you are using data not yet deposited in the PDB, import local files using File/Import/Local files menu or this tool button

In esoteric cases you may want to import a model ensemble generated outside ShakErr (e.g. to use as the starting point for refinement). First, select the project into which the ensemble will be imported and then hit this button

The new job will be added. You can only import the tarball with accordingly named models (i.e. ShakErr tarball). Naming convention requres that individual pdb files are named shaken#.pdb, where # is the file number. Notice that numbering format depends on how many models there are: if less than 10, # must be a single digit, if more - two digits left-padded by zero if necessary. If you have more than 99 models (which is probably way too many), each number should be padded with zeros to get three digits. The easiest way to generate correctly formatted ShakErr tarball is to import the NMR-style multi-model file in RMSD window and output the ensemble as tarball.

Shaking operations

 Use the salt shaker button

to run jobs using current parameters defined in "Shake!" and "Software" tabs on the right. The main window will become unresponsive until the job is completed.
It is possible to run a job using another model ensemble as starting point. The button with two salt shakers will do this

The currently selected job will be used as starting point. This option may be useful if cleanup is needed for model ensemble that has many outliers and thus distorted statistics.
Individual models from the ensemble can be fixed manually in Coot (and ShakErr offers a streamlined process to do just that), but a lot of model errors can be fixed automatically using the cluster analysis algorithm implemented in the program. Parameters for this are defined in "Fix" tab on the right, and the ensemble repair is initiated by this button

Project tree

Overview

 Every branch of the tree is a single project, which is created either from a PDB entry or by importing pdb- and mtz-files. A project is therefore associated with a particular structure. It is listed in the tree with its number and title. The number can be used to locate the project files. For instance, if the project is designated as "36: 1bmb" its files can be found in $HOME/.shakerr/projects/36.

Under every project there are jobs. Job could be a series of refinements against perturbed data, externally imported model ensemble, ensemble patched in coot or fixed by the cluster analysis. Either way, job is associated with a model ensemble that can be analyzed.

Popup menus

 Right-click on a project invokes the popup menu.

Shake: shake the model from the project using current settings.

Edit PDB file: edit the pdb-file that defines the model for the project. This may be helpful if refinement program files due to problems with file format (e.g. C-terminal oxygen naming, missing CRYST1 record, incorrect atom names for nucleic acids etc.) A primitive editor is invoked, so this can be used for only minor edits.

Hide: Hides the project from view. The status can be toggled on and off, and the actual application results in creation/deletion of the .hide file in the corresponding project folder to mark the status. The behavior of the tree control depends on the View menu. If "Gray hidden" is checked, the hidden projects will still be shown and fully functional, but will be grayed out. Hide all/Show all options of the View menu will do exactly that - hide and show all of the projects. Currently, the operations are a bit slow because the whole project tree is re-scanned and tree control refilled every time user changes the parameters.

Delete: Delete the project. THIS IS IRREVERSIBLE! Files associated with the project will be permanently deleted (that's why it asks for confirmation twice.


The popup menu looks different when right-clicking on a job.

Load: Loads the job into the RMSD window. Same effect as the middle click, which is not as accessible from touchpads.

Coot: Invokes coot (assuming that your system is configured properly and coot can be started from a command line by simply typing "coot". If job has mtz-files associated with it, maps will be loaded in addition to models. Coot instance will be monitored and once the session ends, you will be asked what to do with modified models (if any). You can delete everything (saves space) or leave things where they are, in which case you will access the same models again if you call coot once more. In addition, you can "scoop up" the modified models (make sure you are only saving your results using quick-save option in coot (Ctrl-s)) and make a new "job" out of them.

Delete: Delete the job. All files associated with it will be permanently deleted.

Middle-button click

 By clicking the middle button on a job you will load it into the RMSD window.

Options & Tools

General

 Update PDB import folder: If checked, the last folder from which a pdb file was imported into a new project will be remembered and the import file dialog will start there. (Otherwise, the folder from which ShakErr was invoked will be used - why would anyone want that is not clear).

Update MTZ import folder: Same as the option above but refers to the MTZ import.

Save configuration on exit: Does what it says. Again, why would you want a different behavior is not clear.

Software

 Refmac: Specifies the command which will be used to run refmac. If you configure ccp4 on your system prior to starting ShakErr, something as simple as "refmac5" will do. You can also specify path to the location where you keep your latest refmac release.

It also has the configure... button which you can use to configure how the refmac refinement sessions will be performed. You will be able to select the type of positional and B-factor refinement; total number of refinement and TLS cycles (the TLS groups will be picked automatically from the input pdb file, so if you ever plan to use TLS, make that you get the TLS records included - ShakErr does not read an external TLS input file; weight on geometry restraints (either a number corresponding to the WEIGHT MATRIX keyword or "auto" for automatic weight selection); and the last but not the least you can specify the cif-file with restraints for your ligand.

Phenix: defines the path to phenix.refine. I suspect that the only way to get phenix running with ShakErr is to preconfigure Phenix prior to running ShakErr. In that case, simply specify phenix.refine in this field.

The configure... button below allows you to configure (curently very few) phenix.refine parameters. Number of cycles, map writing flag and cif-file for the ligand library can be specified.

CIF2MTZ: path to cif2mtz executable or just "cif2mtz" if you pre-configure CCP4.

Uniqueify: path to uniqueify from CCP4. It is actually a script that requires csh, so make sure that csh/tcsh is installed on your system (not done by default on Ubuntu). Since it's a script that invokes other CCP4 programs, I am not sure how it can be configured to allow for simple path reference.

Ctruncate: path to ctruncate from ccp4. There is a bug in some versions of it resulting in zeroing of few reflections. Refmac automatically ignores those and as a result the job's mtz-file generation will fail. As a workaround, this field may be set to "shruncate" which then invokes the internal truncation algorithm, based on Sivia, David, Acta Cryst A50:703.

Shake!

 Refinement program: choose between refmacc and phenix. CNS and SHELX are not implemented (at least yet). However, any kind of refinement protocol can be used via plugins (which are quite easy to write).

Number of models: the size of the enseemble to generate. More models mean (presumably) better statistics, but longer runs.

Number of processors: ShakErr will run this many refinements at once, which allows you to take advantage of the shiny multi-core processor you just purchased.

Coordinate noise: amplitude (in angstroms) of the noise added to the models prior to refinement. Default is 0.1A which was found to be sufficient to generate enough initial variation (average positional shifts are ~0.17A without introducing systematicc errors.

B-factor noise: amplitude of relative noise added to the B-factors prior to refinement. Default of 0.1 corresponds to 10%.

Error scale factor: experiemental errors will be scaled up by this value. Theoretical value is square root of two, but experimentally verified value from multiple dataset collection is 2.0, perhaps reflecting the crystal-to-crystal variation. Setting this to zero will produce ensembles refined against the same dataset, reflecting only the instability of refinement process.

Randomize: choose between amplitudes/intensities. If you choose to randomize intensities (there is no evidence that it leads to different results as far as shaking errors are concerned), the ctruncate must be available to convert intensities to amplitudes (or you can choose "shruncate" option for the internal conversion).

Fix outliers: if checked, the model outliers will be detected by interquartile-based algorithm applied to (x,y,z) of each atom separately. This will be followed by another cycle of refinement. Much more sophisticated outlier detection is available via model repair options and refinement can be repeated using seed shaking. So this option is somewhat obsolete.

PDB cleanup: deletes all the pdb files from job folder. Also somewhat obsolete since the pdb files are now stored in the tarball which can be exported/imported.

MTZ cleanup: deletes the mtz-files produced by refmac and/or phenix. If this option is selected, invoking coot will only bring up models, without maps.

Plugins

 In its core, ShakErr is the program which generates syntetic data emulating multiple dataset collection. Ensemble of likely models is then produced and analyzed in order to estimate the standard uncertainties of various model parameters, both inherent and derivative. Potentially, the tools can be applied to any refinement protocol and any type of analysis, and we can't cover all the possibilities imagined by you, the user. To improve versatility of the program, a simple procedure for writing plugins is implemented, both for model refinement and ensemble analysis. You'll need to write simple scripts, and hopefully as things progress more and more plugins will become available.

Two types of plugins are allowed: refinement and analysis. In this tab, you can import, run and delete the plugins. Note that the refinement plugins will be applied to the selected project (these may be useful if you need some unusual refinement features that require customized input file for rrefmac or phenix.refine; you can also use other refinement programs via appropriate plugin). The analysis plugins are applied to the currently selected job. A copy of the imported plugin code is stored in ~/.shakerr/plugins folder.

For further information about ShakErr plugins, take a look at this tutorial.

Plot


Plot e.s.u. per residue:

This will do exactly what it says. It will plot the e.s.u.'s for the currently selected job or for all the jobs from the currently selected project. You will be asked to select the chains and single window will be generated for each selection. The X-axis will be residue position in the list, hover over the data point to see the e.s.u. value and the actual residue ID.

Manual job selections: if the current selection in the job list is a whole project, by default the e.s.u.s will be plotted for all the jobs. Now this sometimes may be more than you need, and of this box is checked, you will be asked to select which jobs to include in the chart.

Percentile based spread: The p.b.s. is plotted instead of the defaut which is r.m.s.d.

Sorted plot: Normally e.s.u.s are plotted for the residues in the order in which they appear in the model. This option will sort them by e.s.u. - see the residue ID in the status bar when hovering over the particular bar. In this way the residues with the highest e.s.u. may be inspected in the structure to see if there is a problem.

Group: Select which atoms to include in the residue e.s.u. calculation. Sensible results are only guaranteed when looking at standard amino acids or nucleotides.

Residue type: By default, all residues are included in the calculation. You can also (multi)select specific residues. Combined with sorting the plot by e.s.u., this allows to find out, for example, which tyrosines are problematic. I think the improvement here is due to the correlation of an average expected e.s.u. with residue type (e.g. arginines will on average have higher e.s.u. than leucines, and thus looking only at leucines allows for better identification of problematic residues.

Plot model variance :

This will plot the model variance in reciprocal space. Subscript "o" means "observed", and the corresponding values are calculated directly from the project dataset. Subscript "c" means "calculated", and the corresponding variance is based on analysis of the calculated structural amplitudes for each of the ensemble models. Subscript "m" refers to "model", and this is calculated using Kevin Cowtan's spline approximation.