Skip to content

Manual

Usage

The general pattern to invoke disvis is

disvis <pdb1> <pdb2> <distance-restraints-file>

where <pdb1> is the fixed chain, <pdb2> is the scanning chain and <distance-restraints-file> is a text-file containing the distance restraints in the following format

<chainid 1> <resid 1> <atomname 1> <chainid 2> <resid 2> <atomname 2> <mindis> <maxdis>

As an example

A 18 CA F 27 CB 10.0 20.0

This puts a distance restraint between the CA-atom of residue 18 of chain A of pdb1 and the CB-atom of residue 27 of chain F of pdb2 that should be longer than or equal to 10A and smaller than or equal to 20A. Comments can be added by starting the line with the pound sign (#) and empty lines are ignored.

Options

To get a help screen with available options and explanation type

disvis --help

Some examples to get you started. To perform a 5.27 degree rotational search and store the results in the directory results/

disvis 1wcm_A.pdb 1wcm_E.pdb restraints.dat -a 5.27 -d results

Note that the directory is created if it doesn't exist.

To perform a 9.72 degree rotational search with 16 processors and a voxel spacing of 2A

disvis O14250.pdb Q9UT97.pdb restraints.dat -a 9.72 -p 16 -vs 2

To offload computations to the GPU (if the requirements are met) and increase the maximum allowed volume of clashes as well as the minimum required volume of interaction, and set the interaction radius to 2A

disvis 1wcm_A.pdb 1wcm_E.pdb restraints.dat -g -cv 6000 -iv 7000 -ir 2

To perform a grid occupancy analysis for complexes consistent with at least N restraints, include the -oa or --occupancy-analysis flag to the command. By default, the analysis is only performed on complexes consistent with either all and all - 1 restraints. If you want to perform an occupancy analysis for complexes consistent with a lower number of restraints, use the -ic or --interaction-restraints-cutoff option, followed by the minimum number of required consistent restraints. Thus the command

disvis 1wcm_A.pdb 1wcm_E.pdb restraints.dat -oa -ic 5

will make an occupancy grid for complexes consistent with at least 5 restraints, and higher.

Finally, to perform an interaction analysis to determine which residues are most likely at the interface, the -is or --interaction-selection options can be used with an additional file giving the residue numbers of the receptor and ligand for which the interaction analysis will be performed. The input file consists of two lines, where the two lines are a space separated sequence of residue numbers for the receptor and ligand, respectively. As the interaction analysis is particularly expensive, only complexes consistent with all, or all - 1 are considered. To lower the barrier, the -ic option can again be used. Also limit the selected residues to only the solvent accessible ones. A simple example for the selection-file

1 2 3 4
101 302 888

This will select residue numbers 1, 2, 3, and 4 for the receptor, and 101, 302, and 888 for the ligand.

disvis also writes an HTML report of the results, with a Mol* view of the accessible interaction space (and of the occupancy grids with -oa); see Viewing the report.

Output

Standard disvis outputs 5 files:

  • accessible_complexes.out: a text file containing the number of complexes consistent with a number of restraints.
  • violations.out: a text file showing how often a specific restraint is violated for each number of consistent restraints. This helps in identifying which restraint is most likely a false-positive if any.
  • accessible_interaction_space.mrc: a density file in MRC format. The density represents the center of mass of the scanning chain conforming to the maximum found consistent restraints at every position in space. The density can be inspected by opening it together with the fixed chain in a molecular viewer (UCSF Chimera is recommended for its easier manipulation of density data, but also PyMol works).
  • z-score.out: a text file giving the Z-score for each restraint. The higher the score, the more likely the restraint is a false-positive. If not all restraints are consistent, Z-scores above 1.0 are explicitly mentioned in the output.
  • disvis.log: a log file showing all the parameters used, together with date and time indications. It starts with the DisVis version and ends with how to view the report.

If an occupancy and/or interaction analysis was requested, disvis also outputs the following files:

  • occupancy_N.mrc: a volume file giving a normalized indication of how frequent a grid point is occupied by the ligand, where N indicates the minimal required number of consistent restraints that resulted in the occupancy grid.
  • [receptor|ligand]_interactions.txt: a text file containing the average number of interactions per complex each selected residue made, for both the receptor and ligand molecule. Each column denotes the minimal number of consistent restraints of each complex for which interactions were counted.

disvis also writes report.html and state.mvsj (the MolViewSpec state of the Mol* view), and copies the input files into the output directory, so the report can show and link them (--no-report turns this off).

Viewing the report

The report loads the files of the output directory, which browsers do not allow for a page opened from disk. Serve the output directory with Python instead

python -m http.server -d <directory>

and open http://localhost:8000/report.html in a web browser. Stop the server with Ctrl-C. If port 8000 is in use, choose another one, e.g. python -m http.server 8080 -d <directory> and http://localhost:8080/report.html.

To visualize the most contacted residues, write the average number of interactions into the B-factor column of the receptor or ligand PDB file

python scripts/interactions_to_bfactor.py receptor.pdb receptor_interactions.txt N

where N is one of the column numbers of the interaction file. This writes receptor_interactions.pdb, which can be colored on B-factor, e.g. with spectrum b, blue_red in PyMOL or color bfactor in ChimeraX.

DisVis is aimed at explorative modelling: checking the consistency and information content of a set of distance restraints, to design follow-up experiments or to select the restraints that drive docking, e.g. with HADDOCK.

  1. Determine the consistency of the restraints with a quick, coarse search (e.g. -a 15 -vs 2).
  2. Inspect the violations and z-scores (violations.out, z-score.out) and remove the likely false-positive restraints.
  3. Once the restraints are consistent, run a finer search (e.g. -a 9.72 -vs 1), with the occupancy analysis (-oa) to approximate the position of the scanning chain, and the interaction analysis (-is) to find the residues most likely at the interface.

To shorten the run time, use the larger molecule as fixed chain and the smaller one as scanning chain, unless you are interested in the accessible interaction space of the smaller molecule.

Web service

DisVis is also available as a web service on the WeNMR/CSB portal. You need an account on the portal to submit a job.

The submission form takes:

  • Fixed chain and scanning chain: the two structures, in PDB or mmCIF format.
  • Restraints file: the distance restraints, in the format described in Usage.
  • Scanning mode: see the table below.
  • Interaction analysis (optional): a residue selection file, as for the -is option.
  • Tag (optional): a name to identify your run.

The scanning modes set the search parameters:

Mode Rotational sampling interval Voxel spacing Occupancy analysis
Quick scanning (default) 15° 2 Å no
Complete scanning 9.72° 1 Å yes
Custom scanning 5–360° 1–4 Å optional

In the custom mode, the interaction radius (1–4 Å, default 3 Å, -ir), the maximum clash volume (default 200 ų, -cv) and the minimum interaction volume (default 300 ų, -iv) can also be changed.

As on the command line, start with a quick scan without the interaction analysis, to check that complexes consistent with all, or all but a few, restraints exist. The results page shows images of the accessible interaction space, the accessible complexes, the z-scores, the violations and, with an interaction analysis, the most contacted residues, and gives all files of the run as an archive. The results are kept on the server for 14 days.