Classic EM Tutorial, Part I
This "classic" tutorial teaches some basic map editing skills and how to perform a fast rigid-body docking of structures to single molecule density maps that were extracted by difference mapping of assemblies (here: ncd-decorated microtubules). Many of the early Situs tools from the 1990s are described here. The results can be compared to solutions distributed with the tutorial software. More documentation is available in the user guide, on the Methodology page, and in the published articles.
Content:
Download and Installation

Follow first the simple registration and download steps .

In addition to the executables, the Situs_2.3_single_tutorial/bin directory also contains four additional data files:

In the following, we will use these four files to dock ncd to the microtubule, following the steps described in Wriggers et al., 1999. The user can compare all generated files to the files in the solutions directory.

Data Flow and Design

The series of steps and the programs that are required to dock an atomic-resolution structure into a single-molecule, low-resolution EM data are shown schematically in the following figure. Detailed program explanations are given in the user guide

Schematic diagram of EM related routines. Major Situs components (blue) are classified by their functionality. The main data flow is indicated by brown arrows. The visualization (orange) for the rendering of the data requires a molecular graphics viewer (we recommend the free VMD graphics program, version 1.8.4 or higher; Chimera and Sculptor also support Situs format).

Standard EM formats are supported and are converted to cubic lattices in Situs format. Subsequently, the data is inspected and, if necessary, prepared for the vector quantization using a variety of visualization and analysis tools.
All Situs tools require one volume and one PDB structure for the fitting. Atomic coordinates in PDB format can be transformed to low-resolution maps, if necessary, and vice versa, to allow docking of maps to maps or structures to structures. After the vector quantization, the high-resolution structure is docked to the low-resolution density by the corresponding codebook vectors. The resulting docked complex can be inspected using the graphics program. 

Converting the EM Maps 

We convert EM maps to Situs format with the map2map utility. Enter at the shell prompt:
 

./map2map 0_mt.ascii 1_mt.situs

Enter the file format option 1: ASCII. At the program prompt enter the number of columns: 89, the number of rows: 89, and the number of sections: 61. Enter the grid (lattice) spacing in Angstrom: 6. Enter the order option: 1: x > y > z (order is already correct).

Repeat this procedure similarly for the other two EM maps to create the files 1_nm.situs and 1_nd.situs.

Here is the full map2map session for file 0_mt.ascii: 

% ./map2map 0_mt.ascii 1_mt.situs
map2map>
map2map> Situs file format conversion and cubic lattice interpolation.
map2map> Choose one of the following 10 options.
map2map>
map2map> OTHER -> Situs (map indexing may be altered):
map2map>
map2map>      1: ASCII (text) free format, sequential list of map densities
map2map>      2: X-PLOR map (ASCII)
map2map>      3: MRC (= old CCP4) binary (limited support*)
map2map>      4: CCP4 (= new MRC) binary (limited support*)
map2map>      5: SPIDER binary
map2map>      6: Generic binary (unknown map or header parameters)
map2map>
map2map> Situs -> OTHER**:
map2map>
map2map>      7: Situs -> X-PLOR (ASCII)
map2map>      8: Situs -> MRC (= old CCP4) binary (limited support*)
map2map>      9: Situs -> CCP4 (= new MRC) binary (limited support*)
map2map>     10: Situs -> SPIDER binary
map2map>
map2map> *  There are some known issues with these file formats. See user guide.
map2map>    If in doubt use the relatively robust SPIDER format and a third party
map2map>    conversion program such as em2em or MAPMAN.
map2map> ** Origin of coordinate system may not be preserved, avoid round-trip
map2map>    conversions.
map2map> 1
map2map> Enter number of columns (in x-direction): 89
map2map> Enter number of rows (in y-direction): 89
map2map> Enter number of sections (in z-direction): 61
map2map> Enter grid (lattice) spacing in Angstrom: 6
map2map> Reading ASCII data...
map2map> Volumetric data read from file 0_mt.ascii
map2map>
map2map> Order of density values.
map2map> Must have x changing fastest, then y, then z [x > y > z]
map2map> Enter order of values in file 0_mt.ascii
map2map>
map2map>      1: x > y > z (order is already correct)
map2map>      2: x > z > y conversion
map2map>      3: y > x > z conversion
map2map>      4: y > z > x conversion
map2map>      5: z > x > y conversion
map2map>      6: z > y > x conversion
map2map> 1
map2map> Cubic lattice present. The coordinate system origin is set to voxel (1,1,1)
map2map> and the voxels are numbered (1-89,1-89,1-61).
lib_vio> Writing density data...
lib_vio> Volumetric data written to file 1_mt.situs
lib_vio> File 1_mt.situs - Header information:
lib_vio> Columns, rows, and sections: x=1-89, y=1-89, z=1-61
lib_vio> 3D coordinates of first voxel (1,1,1): (0.000000,0.000000,0.000000)
lib_vio> Voxel size in Angstrom: 6.000000

We need to specify the grid indexing. Also, we do not know the unit cell of the map, so the origin of the coordinate system is set to the first voxel in the map. 

Computing the Difference Density Maps

We compute difference density maps with the voldiff utility. To compute the difference density map of the first, attached ncd monomer, subtract the microtubule data from the monomer-decorated microtubule data: 

./voldiff 1_nm.situs 1_mt.situs 2_s1.situs

Similarly, to compute the difference density map of the second, detached monomer, subtract the monomer-decorated microtubule data from the dimer-decorated microtubule data:  

./voldiff 1_nd.situs 1_nm.situs 2_s2.situs
Inspecting Data Cross Sections 

Now we inspect the generated Situs maps with the voledit utility. voledit requires a fixed-width font in the shell window. 

First we look at the dimer-decorated microtubule. At the shell prompt, enter: 

./voledit 1_nd.situs

The program prints the header information and the minimum and maximum density values of the map. Note that the default density cutoff for the rendering of voxels is the mean of the minimum and the maximum density. Enter the desired cross section type: 1: (x,y)-cross section as function of z-value. The program will render the cross section at the half-maximal z position. At the program prompt, increase or decrease the z position or enter "0" for changing the cutoff value. What happens if you start the program with cross section types 2: (z,x) or 3: (y,z)? Also inspect the files 1_mt.situs, 1_nm.situs, 2_s1.situs, and 2_s2.situs (hint: a cutoff value of 12 gives best results for file 2_s2.situs). 

Here is an example voledit session for file 1_nd.situs:  

% ./voledit 1_nd.situs
lib_vio> File 1_nd.situs - Header information:
lib_vio> Columns, rows, and sections: x=1-89, y=1-89, z=1-61
lib_vio> 3D coordinates of first voxel (1,1,1): (0.000000,0.000000,0.000000)
lib_vio> Voxel size in Angstrom: 6.000000
lib_vio> Reading density data...
lib_vio> Volumetric data read from file 1_nd.situs
voledit> Min. / max. density values: -31.000000 / 51.000000
voledit> Choose one of the following three options -
voledit>      1: (x,y)-cross section as function of z-value
voledit>      2: (z,x)-cross section as function of y-value
voledit>      3: (y,z)-cross section as function of x-value
voledit> 1
voledit> Density threshold level = 10.000000
voledit> Box coordinates (1,1,1)=(0.000000,0.000000,0.000000); (89,89,61)=(534.000000,534.000000,366.000000)
voledit> Cross section at z = 31:
                                                                                           y
                                                                                           ^
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 85
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 81
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 77
                              uuuu        uuu
.   .   .   .   .   .   .   OOOOOOu .   .OOOO   .   .   .   .   .   .   .   .   .   .   .- 73
                            OOOOOO       ^
.   .   .   .   .   .   .  uOOOO^   .   . uu.   .   .   .   .   .   .   .   .   .   .   .- 69
                  uuOOOu  uOOOOOu       uOOOO     uuuu
.   .   .   .   .OOOOOOOO ^^^OOOOOu .  uOOOOOu uuOOOOO  .   .   .   .   .   .   .   .   .- 65
                 OOOOOOO       OOOOOu  OOOOOO^OOOOOOOOOu uuuO
.   .   .   .   . OOOOOOu   .  OOOOOO   .   .  ^OOOOOOOOOOOOO   .   .   .   .   .   .   .- 61
                   OOOOOOOOOuuuOOOO^                 OOOOOOOO     uu
.   .   .   .   . OOOOOOOOOOOOOO^   .   .   .   .   . ^^^OOOOu  uOOOOu  .   .   .   .   .- 57
            uOOOOO^OOO^^^OOOOOO^                          ^OOOOOOOOO^
.   .   .  uOOOOOO  .   .OOOOO^ .   .   .   .   .   .   .  ^OOOOOO^ .   .   .   .   .   .- 53
           OOOOOOOOuuOOOOOOO^                               ^OOO^^
.   .   .  ^OOOOOOOOOOOOOOOO.   .   .   .   .   .   .   .   .   .   uOOOOu  .   .   .   .- 49
              ^OOOOOOOOOOOOO                                  uOOOOOOOOOOOOOOu
.   .   .   .   ^OOO^ ^^^^^ .   .   .   .   .   .   .   .   .uOOOOOOOOOOOOOOOOO .   .   .- 45
                       uuOu                                   OOOOOO^^  ^^OOOO
.   .   .   .   .   uOOOOOOu.   .   .   .   .   .   .   .   .uOOO^  .   .  ^^^  .   .   .- 41
            uuuuuuuOOOOOOOOO                                OOOOOuuuuOOu
.   .   .   OOOOOOOOOOO^^^Ou.   .   .   .   .   .   .   .  OOOOOOOOOOOOOO   .   .   .   .- 37
            ^^^^^^OO^^    OOOuu                           uOOOOOOOOOOOOOOu
.   .   .   .   .   .   .uOOOOOOu   .   .   .   .   .   uOOOO^^^^^^OOOOOOOOu.   .   .   .- 33
                        uOOOOOOOOuu                    OOOOOOu      OOOOOOOO
.   .   .   .   .   .  uOOO^^^^OOOOOOOu .   .   .   uuuOOOOOOOOuuOOOOOOOOOO .   .   .   .- 29
                       ^^^     OOOOOOOOOOOOuuu   OOOOO  ^^OOOOOOOOO^^^^O^^
.   .   .   .   .   .   .   .  OOOOO^^^OOOOOOO  OOOOOO  .   ^OOOOO^ .   .   .   .   .   .- 25
                                       OOOOO^    OOOO        OOOOOu
.   .   .   .   .   .   .   .   .   .   ^^^ .   . ^^Ouu .   uOOOOOOu.   .   .   .   .   .- 21
                                                   uOOOO    OOOOOOO
.   .   .   .   .   .   .   .   .   .   .   .   .uOOOOO^.   .^^^^   .   .   .   .   .   .- 17
                                                 OOOOO^
.   .   .   .   .   .   .   .   .   .   .   .   .^^^^   .   .   .   .   .   .   .   .   .- 13
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 9
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 5
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 1
|   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
1   5   9   13  17  21  25  29  33  37  41  45  49  53  57  61  65  69  73  77  81  85  89  >x

voledit> Increase/decrease z (enter offset value or 0 for more options):

Extracting Regions of Interest

We want to perform the docking of the ncd crystal structure to two selected regions of density near the microtubule surface. Obviously, the full datasets are too large and contain too many individual protein densities. Therefore, we extract first a small region of interest near the microtubule surface, using the cropping tool within voledit (enter 0 from within the slice window and 3 on the option menu). An inspection of the datasets with voledit shows that the 25x25x25 cube with positions x:57-81, y:33-57, z:15-39 is suitable. First, we extract this region from file 1_mt.situs and save the resulting map to file 3_mt.situs (option 8): 

% ./voledit 1_mt.situs
lib_vio> File 1_mt.situs - Header information:
lib_vio> Columns, rows, and sections: x=1-89, y=1-89, z=1-61
lib_vio> 3D coordinates of first voxel (1,1,1): (0.000000,0.000000,0.000000)
lib_vio> Voxel size in Angstrom: 6.000000
lib_vio> Reading density data...
lib_vio> Volumetric data read from file 1_mt.situs
voledit> Min. / max. density values: -32.000000 / 49.000000
voledit> Choose one of the following three options -
voledit>      1: (x,y)-cross section as function of z-value
voledit>      2: (z,x)-cross section as function of y-value
voledit>      3: (y,z)-cross section as function of x-value
voledit> 1
voledit> Density threshold level = 8.500000
voledit> Box coordinates (1,1,1)=(0.000000,0.000000,0.000000); (89,89,61)=(534.000000,534.000000,366.000000)
voledit> Cross section at z = 31:
                                                                                           y
                                                                                           ^
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 85
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 81
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 77
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 73
                                                                                          
.   .   .   .   .   .   .   .   .   .   uuOu.   .   .   .   .   .   .   .   .   .   .   .- 69
                                       OOOOOOu   uuOOu
.   .   .   .   .   .   .   .  uOOuu.  OOOOOOOuuOOOOOOO .   .   .   .   .   .   .   .   .- 65
                               OOOOOOu OOOOOOOOOOOOOOOOOuuuuu
.   .   .   .   .   .   .   . OOOOOOOO  .^^ . ^OOOOOOOOOOOOOOO  .   .   .   .   .   .   .- 61
      u                  OOOOOOOOOOO^              ^OOOOOOOOO
.   .   .   .   .   .   .OOOOOOOO^^ .   .   .   .   .^^OOOOOOuuu.   .   .   .   .   .   .- 57
                         OOOOOOO                         ^OOOOOOOOu
.   .   .   .   .   . uuuOOOOOO .   .   .   .   .   .   . ^OOOOOOOO .   .   .   .   .   .- 53
                     OOOOOOOO^^                             ^OOOO^
.   .   .   .   .   .OOOOOOOO   .   .   .   .   .   .   .   .^^ .   .   .   .   .   .   .- 49
                     ^OOOOOOO                                uOOOOOu
.   .   .   .   .   .  ^^^O^.   .   .   .   .   .   .   .   .OOOOOOOO   .   .   .   .   .- 45
                      uuOOO                                  OOOOOOOO
.   .   .   .   .   uOOOOOOu.   .   .   .   .   .   .   .   uOOOOO^^.   .   .   .   .   .- 41
                    OOOOOOOO                               OOOOOOu
.   .   .   .   .   .^^^OO^Ouu  .   .   .   .   .   .   .  OOOOOOO  .   .   .   .   .   .- 37
                          OOOOuu                         uOOOOOOOOO
.   .   .   .   .   .   .OOOOOOOOu  .   .   .   .   .   OOOOOOOOOO  .   .   .   .   .   .- 33
                        ^OOOOOOOOOuuuu                uOOOOOOO
.   .   .   .   .   .   .^^^^^OOOOOOOOOu.   .   . uuuOOOOOOOOO  .   .   .   .   .   .   .- 29
                               OOOOOOOOOOOOOOu uuOOOOOO^^OOOO
.   .   .   .   .   .   .   .  OOOOOOOOOOOOOOO ^OOOOOOO .   .   .   .   .   .   .   .   .- 25
                                ^^^   ^OOOOOO^  ^OOOOO^
.   .   .   .   .   .   .   .   .   .  ^OOO^.   . ^^^   .   .   .   .   .   .   .   .   .- 21
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 17
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 13
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 9
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 5
                                                                                          
.   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .- 1
|   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |   |
1   5   9   13  17  21  25  29  33  37  41  45  49  53  57  61  65  69  73  77  81  85  89  >x

voledit> Increase/decrease z (enter offset value or 0 for more options): 0
voledit> Choose one of the following options:
voledit>      1:  Enter new z value directly
voledit>      2:  Enter new threshold level for display
voledit>      3:  Cropping (cut away margin)
voledit>      4:  Zero padding (extra margin)
voledit>      5:  Polygon clippling
voledit>      6:  Segmentation (floodfill) of contiguous volume
voledit>      7:  Save current slice
voledit>      8:  Save entire map
voledit>      9:  Quit voledit
voledit> 3
voledit> Voxel range of cropping. Enter new grid values:
voledit> Minimum x value (1-89): 57
voledit> Maximum x value (57-89): 81
voledit> Minimum y value (1-89): 33
voledit> Maximum y value (33-89): 57
voledit> Minimum z value (1-61): 15
voledit> Maximum z value (15-61): 39
lib_vwk> Map size changed from from 89 x 89 x 61 to 25 x 25 x 25 by cropping and/or zero-padding.
lib_vwk> New map origin (coord of (1,1,1) voxel): (336.000000,192.000000,84.000000)
voledit> Density threshold level = 8.000000
voledit> Box coordinates (1,1,1)=(336.000000,192.000000,84.000000); (25,25,25)=(486.000000,342.000000,234.000000)
voledit> Cross section at z = 13:
                           y
                           ^
 ^OOOOOOOu
. OOOOOOOOOu.   .   .   .- 21
  ^^OOOOOOO
.   OOOOOO  .   .   .   .- 17
    OOOOOOOu
.   ^OOOOOOOO   .   .   .- 13
     OOOOOOO^
.   .OOOO^  .   .   .   .- 9
    uOOOOu
.   OOOOOOO .   .   .   .- 5
    OOOOOOO
uuuu. ^^^^  .   .   .   .- 1
|   |   |   |   |   |   |
1   5   9   13  17  21  25  >x

voledit> Increase/decrease z (enter offset value or 0 for more options): 0
voledit> Choose one of the following options:
voledit>      1:  Enter new z value directly
voledit>      2:  Enter new threshold level for display
voledit>      3:  Cropping (cut away margin)
voledit>      4:  Zero padding (extra margin)
voledit>      5:  Polygon clippling
voledit>      6:  Segmentation (floodfill) of contiguous volume
voledit>      7:  Save current slice
voledit>      8:  Save entire map
voledit>      9:  Quit voledit
voledit> 8
voledit> Enter filename for the modified map: 3_mt.situs
lib_vio> Writing density data...
lib_vio> Volumetric data written to file 3_mt.situs
lib_vio> File 3_mt.situs - Header information:
lib_vio> Columns, rows, and sections: x=1-25, y=1-25, z=1-25
lib_vio> 3D coordinates of first voxel (1,1,1): (336.000000,192.000000,84.000000)

Similarly, we create the files 3_nd.situs, 3_nm.situs, 3_s1.situs, and 3_s2.situs from the corresponding files 1_nd.situs, 1_nm.situs, 2_s1.situs, and 2_s2.situs. 

Inspecting the Voxel Histogram

Next, we inspect the file 3_nm.situs with the program volhist to make sure the background peak in the voxel histogram is at the origin. When prompted, enter the number of histogram bins (40):

% ./volhist 3_nm.situs test
lib_vio> File 3_nm.situs - Header information:
lib_vio> Columns, rows, and sections: x=1-25, y=1-25, z=1-25
lib_vio> 3D coordinates of first voxel (1,1,1): (336.000000,192.000000,84.000000)
lib_vio> Voxel size in Angstrom: 6.000000
lib_vio> Reading density data...
lib_vio> Volumetric data read from file 3_nm.situs
lib_vwk> Min. / max. density values: -27.000000 / 50.000000
lib_vwk> Please enter the of number histogram bins: 40
lib_vwk> Printing voxel histogram, 40 histogram bins
lib_vwk> (density value; voxel count; top-down cumulative volume fraction):
 -27.000 | 2 .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 1.000e+00
 -25.026 |= 27                                                                           | 9.999e-01
 -23.051 |==== 94    .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 9.981e-01
 -21.077 |======= 157                                                                    | 9.921e-01
 -19.103 |======== 193   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 9.821e-01
 -17.128 |============ 287                                                               | 9.697e-01
 -15.154 |============== 323 .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 9.514e-01
 -13.179 |============= 307                                                              | 9.307e-01
 -11.205 |============== 319 .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 9.110e-01
  -9.231 |=============== 350                                                            | 8.906e-01
  -7.256 |======================== 548   .   .   .   .   .   .   .   .   .   .   .   .   | 8.682e-01
  -5.282 |================================ 717                                           | 8.332e-01
  -3.308 |===================================================== 1185 .   .   .   .   .   | 7.873e-01
  -1.333 |====================================================================== 1565    | 7.114e-01
   0.641 |=======================================================================-> 1761 | 6.113e-01
   2.615 |=========================================== 966                                | 4.986e-01
   4.590 |=============================== 714    .   .   .   .   .   .   .   .   .   .   | 4.367e-01
   6.564 |==================== 459                                                       | 3.910e-01
   8.538 |=============== 355    .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 3.617e-01
  10.513 |================ 358                                                           | 3.389e-01
  12.487 |============== 328 .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 3.160e-01
  14.462 |=============== 349                                                            | 2.950e-01
  16.436 |============== 325 .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 2.727e-01
  18.410 |============= 305                                                              | 2.519e-01
  20.385 |=============== 342    .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 2.324e-01
  22.359 |============== 322                                                             | 2.105e-01
  24.333 |============= 300  .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 1.899e-01
  26.308 |============= 295                                                              | 1.707e-01
  28.282 |============== 326 .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 1.518e-01
  30.256 |=============== 353                                                            | 1.309e-01
  32.3 |============== 321 .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 1.084e-01
  34.205 |============= 303                                                              | 8.781e-02
  36.179 |============== 317 .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 6.842e-02
  38.154 |============ 278                                                               | 4.813e-02
  40.128 |========= 211  .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 3.034e-02
  42.103 |====== 137                                                                     | 1.683e-02
  44.077 |=== 74 .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 8.064e-03
  46.051 |= 40                                                                           | 3.328e-03
  48.026 | 11    .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   | 7.680e-04
  50.000 | 1                                                                             | 6.400e-05

lib_vwk> Maximum at density value 0.641

As an exercise, check out what happens if you specify an output file "test" and an offset density value of 10 and a scaling factor of 2 are entered at the program prompt. 

The inspection shows that the background peak is already at the origin, so we remove the output file "test". Note also that volhist can be run without an output file as argument, in which case the program simply shows the histogram.

The volhist  tool is also useful for discrepancy / difference mapping of simulated maps (created with pdb2vol) that are to be subtracted from experimental maps. In this case a rescaling of the simulated map is in order until the histogram matches that of the experimental map (or until the histogram of the difference map is balanced between positive and negative values if the subtracted map is of same size).

Extracting Single-Molecule Densities
 
We are now prepared to extract single-molecule densities with the floodfill segmentation utility within voledit (enter 0 from within the slice window, then 6 on the option menu). Inspection of the file 3_s1.situs with the voledit indicates that the voxel at position x=16, y=16, z=16 is located near the center of the density of an attached monomer that can be isolated at a threshold level of 20. Similarly, one finds that the voxel at position x=19, y=12, z=13 is located near the center of the density of a detached monomer in file 3_s2.situs at a threshold level of 12. Here is the voledit session for extracting the first monomer and writing it to file 4_s1.situs:  

% ./voledit 3_s1.situs
lib_vio> File 3_s1.situs - Header information:
lib_vio> Columns, rows, and sections: x=1-25, y=1-25, z=1-25
lib_vio> 3D coordinates of first voxel (1,1,1): (336.000000,192.000000,84.000000)
lib_vio> Voxel size in Angstrom: 6.000000
lib_vio> Reading density data...
lib_vio> Volumetric data read from file 3_s1.situs
voledit> Min. / max. density values: -19.000000 / 56.000000
voledit> Choose one of the following three options -
voledit>      1: (x,y)-cross section as function of z-value
voledit>      2: (z,x)-cross section as function of y-value
voledit>      3: (y,z)-cross section as function of x-value
voledit> 1
voledit> Density threshold level = 18.500000
voledit> Box coordinates (1,1,1)=(336.000000,192.000000,84.000000); (25,25,25)=(486.000000,342.000000,234.000000)
voledit> Cross section at z = 13:
                           y
                           ^
         ^OOOO^
.   .   .  ^.   .   .   .- 21
                         
.   .   .  uOOOOOO  .   .- 17
           ^OOOOOO
.   .   .   .OOOO^  .   .- 13
                         
.   .   .   .   .   .   .- 9
                         
.   .   .   uuuu.   .   .- 5
            OOOOO
.   .   .   ^^^ .   .   .- 1
|   |   |   |   |   |   |
1   5   9   13  17  21  25  >x

voledit> Increase/decrease z (enter offset value or 0 for more options): 0
voledit> Choose one of the following options:
voledit>      1:  Enter new z value directly
voledit>      2:  Enter new threshold level for display
voledit>      3:  Cropping (cut away margin)
voledit>      4:  Zero padding (extra margin)
voledit>      5:  Polygon clippling
voledit>      6:  Segmentation (floodfill) of contiguous volume
voledit>      7:  Save current slice
voledit>      8:  Save entire map
voledit>      9:  Quit voledit
voledit> 6
voledit> Min. / max. density values: -19.000000 / 56.000000
voledit> Enter desired threshold level for floodfill segmentation: 20
voledit> Enter floodfill start index x (1-25): 16
voledit> Enter floodfill start index y (1-25): 16
voledit> Enter floodfill start index z (1-25): 16
voledit> 3D coordinates of start grid point (16,16,16): (426.00,282.00,174.00)
voledit> Shrink map about found volume? Choose one of the following options:
voledit>
voledit>      1: No (keep input map size)
voledit>      2: Yes (shrink map)
2
voledit> Filling contiguous volume...
voledit> Filling contiguous volume...
voledit> Contiguous volume, > 20.000000: 284 voxels (6.134400e+04 Angstrom^3)
voledit> Extracted volume, > 0.000000: 724 voxels (1.563840e+05 Angstrom^3)
lib_vwk> Map size changed from from 25 x 25 x 25 to 9 x 10 x 14 by cropping and/or zero-padding.
lib_vwk> New map origin (coord of (1,1,1) voxel): (396.000000,252.000000,132.000000)
voledit&g