The main FilaSitus programs:

filabuild - Helical / Filament Symmetry Builder
kercon - Kernel Convolution

Map editing, inspection, and conversion tools borrowed from Situs1.4:

volcube - Creating Isocontour Surfaces for VMD
convert - File Conversion
histovox - Inspecting and Shifting the Voxel Histogram
padup - Zero Padding
pindown - Map Cropping
subtract - Subtracting Density Values
volslice - Inspecting 2D Cross Sections of Density Values

Header File and Library Routines

Purpose:

The filabuild tool generates multiple copies of the input PDB file in the z-direction according to a user-specified helical symmetry, and in the (x,y) direction, acoording to a specified offset. All helical parameters, the start angle, flipping of filaments, etc., can be adjusted by the user.

Usage (at shell prompt):

Input at program prompt (if file2 is not specified):

• Number of filaments
• For each filament:
• Helical rise per subunit (in z-direction).
• Angular twist per subunit (sign determines handedness).
• Start (offset) angle of filament rotation about z-axis
• Desired number of subunits to be placed before file1 structure.
• Desired number of subunits to be placed after file1 structure.
• x- and y-position of helical axis (offset from file1 coordinate system origin).
• Option to flip the filament. Flipping is done such that the filaments are turned upside down, but the geometric centers of the first and last subunit are transformed onto each other. Thereby, the actin helix keeps a similar appearance after flipping.

Output:

Helical / lattice symmetry PDB file containing multiple copies of input PDB file.

Purpose:

The kercon utility is a real-space convolution tool. It allows one to lower the resolution of an atomic structure to a user-specified value, or to create a sphere model from atomic coordinates. Both mass and charge density maps can be created. The output is a 3D density file in Situs format that can be visualized with VMD (we recommend VMD version 1.7) or converted to other formats.

Usage (at shell prompt):

Input at program prompt:

• Choice of creating a charge or mass density file. Charges are read from the occupancy field of file1. Atom masses are assigned automatically.

• Desired voxel spacing for output map.

• Kernel width, defined by either the kernel half-max radius r-half (enter negative value) or by the target resolution of the output map (enter value of resolution as positive number). The standard deviation (sigma) of the kernel is assumed to be half the target resolution.

• Type of smoothing kernel:

• Gaussian, A exp(-1.5 r^2 / sigma^2): The structure is first projected to a cubic lattice by tri-linear interpolation. Subsequently, each lattice point is convoluted with the Gaussian kernel. The user specifies also the amplitude A of the kernel and the kernel width, defined by either the kernel half-max radius r-half (enter negative value) or by the target resolution of the output map (enter value of resolution as positive number). The standard deviation (sigma) of the kernel is assumed to be half the target resolution. The user has a choice of correcting for lattice smoothing (subtracts the lattice projection mean-square deviation from the kernel variance).
• Hard Sphere: 0 (r>R), A (r<R) There is a thin region (1 voxel wide) where density values are ramped linearly from 0 to A to avoid jaggies (anti-aliasing). The radii R of the spheres are read from the B-factor field of file1. The amplitude A of the largest sphere is user-specified. In the case of charge density maps, the amplitude of the smaller spheres is automatically adjusted higher to maintain equally weighted kernels i.e. charge balance.

If in doubt, use a kernel amplitude A=1.

Output:

3D density file in Situs format. The new grid follows the coordinate system origin convention of the atomic structure and forms the smallest possible box that fully encloses the structure convoluted by the kernel. A short header holds the voxel size and numbers of x, y, and z increments, as well as the 3D coordinates of the first voxel (x=1, y=1, z=1). The Situs header is followed by the sequence of data values. The converted Situs files are in ASCII format, allowing the user to verify the successful conversion of the data.

Purpose:

The program volcube produces wireframe meshes or solid surfaces of isocontours that can be displayed with atomic models of proteins using the free molecular graphics package VMD. We recommend VMD 1.7 to ensure maximum compatibility. The volcube utility takes advantage of VMD's Tcl scripting capabilities [Dalke and Schulten, 1997] that allow the user to display geometric objects and surfaces consisting of shaded triangles. In particular, volcube generates the vertices and vertex norm vectors of triangles that can be used for solid rendering of surfaces. The VMD-specific part of the volcube code is concentrated in a single subroutine and can easily be modified to other standard graphics packages with surface or mesh rendering capabilities. The isosurfaces are generated with an improved version of the "marching cubes'' algorithm [Lorensen and Cline, 1987].

Usage (at shell prompt):

Input at program prompt:

• New voxel size for rendering (the input grid is automatically interpolated).
• Isocontour surface density level.
• Rendering style: lines (wireframe), triangles (solid, flat shades), or trinorm (solid, smooth shades).

• (Program level:) Diagnostic messages and classification of the "marching cube" intersection patterns according to Heiden et al., J. Comp. Chem. 14 (1993), 246-250.

• (Shell level:) VMD script file with graphics primitives. The primitives can be sourced from the VMD text console (cf. VMD user guide). E.g. the following sequence of commands in the VMD text console will first list all files in the current directory and then render the graphics primitives of file "trinorm.vmd" in red", and those of file "wireframe.vmd" in green:

Known Bugs:

To prevent shading of the wireframe lines, the Tcl output scripts turn off the VMD "materials" rendering property. Subsequently loaded solid surfaces will therefore be rendered flat. This can be prevented by sourcing all solid surfaces before sourcing any wireframes.

Purpose:

Volumetric density data is created in a FilaSitus / Situs-specific format that provides data compatibility between the individual FilaSitus and Situs programs and that makes the core programs independent of the ever changing map format standards in the structural biology community.

The convert utility reads and writes file formats of standard structural biology application software. These include the MRC, SPIDER, and CCP4 formats, as well as similar 4-byte floating-point binary formats. X-PLOR maps in ASCII format, and ASCII files that contain a sequence of density values in free format are also recognized. The conversion of Situs format files to CCP4, MRC, X-PLOR, SPIDER format is supported to facilitate the visualization of FilaSitus-generated maps with programs other than VMD/volcube.

Usage (at shell prompt):

Input at program prompt (if necessary):

• Input file format (in FilaSitus typically Situs format): In Situs format, a short header holds the voxel size and numbers of x, y, and z increments, as well as the 3D coordinates of the first voxel (x=1, y=1, z=1). The default origin of the map coordinate system in Situs is the origin of the PDB coordinate system from which the map was created with kercon.
• Number of x, y, and z increments (columns, rows, and sections).
• Voxel size (grid spacing).
• Order of x, y, and z increments in the input file.

Density file in selected format. The order of values in the sequence of densities is altered, if necessary, such that x increments change fastest and z increments change slowest. If a SPIDER, MRC, CCP4, or X-PLOR map is created, the unit cell spans the space from the coordinate system origin to the maximum extent of the input Situs map.

Notes:

• The program name may get confused with any system installed convert tool. Enter "./convert" at the command prompt to avoid confusion. You may also update your UNIX path variable to search your local directory first.

• The MRC and CCP4 map file headers continue to evolve. Very old CCP4 maps may correspond to the format currently denoted "MRC", whereas future MRC maps may correspond to the current "CCP4" format. For a history and future plans of this development read Stephen Fuller's page at EMBL.

• Binary maps produced on a foreign machine architecture may not be readable by convert. We will soon support automatic binary format (endianism) adjustment. In the mean time, we suggest to use FilaSitus on the same machine the map was created, or to convert test-based ASCII maps. For a more powerful cross-platform conversion, see the manual of the free program MAPMAN, part of Gerard Kleywegt's RAVE package, or Image Science's em2em program.

Purpose:

The histovox utility prints the voxel histogram [Frank et al., 1991] of the density values. The histogram illustrates two general properties of low-resolution density distributions. First, a pronounced peak at low densities is due to background scattering. The protein density typically corresponds to a second, broader peak at higher densities. When integrating the histogram "from the top down'', the known molecular volume of a protein can be used to compute its boundary density value. The histovox program also allows the user to add a constant value to the densities to shift the background density peak to the origin, and to rescale the densities.

Usage (at shell prompt):

Input at program prompt (if file2 specified):

• Offset density value (will be added to all voxels).
• Scaling factor.

• (Program level:) Voxel histogram and fractional volume of volumetric data echoed to the screen. The histogram bars are normalized by the second highest density peak.

• (Shell level:) Density file in Situs format (if specified). The new density values are computed by adding the offset value and by multiplying the scaling factor entered at the program prompt. The new grid inherits all size and position parameters of the old grid.

Purpose:

The padup utility allows one to add margins of a user-specified density value to an existing density map. In most cases this tool will be used for zero-padding of maps.

Usage (at shell prompt):

Input at program prompt:

• Lower and upper x, y, and z margins in integer voxels.
• Padding density value.

Density file in Situs format. The new grid inherits the voxel size (grid spacing) of the old grid. The number of x, y, and z increments, and the coordinates of voxel (1,1,1) depend on the chosen padding margins.

Purpose:

The pindown utility allows one to crop away a user-specified margin to extract a box of interest located within a map. This is useful e.g. if one wants to apply periodic boundary conditions in z-direction using filaments with 13/6 symmetry:

First, create a model of filaments that extend somewhat (3-4 actin monomers) on each side of the desired boundary in z-direction (with filabuild). Then, blur the model with kercon, choosing a suitable voxel spacing that encodes 13 units in integer voxel numbers. Finally, use pindown to crop away the extra densities:

Usage (at shell prompt):

Input at program prompt:

The range of voxels of the selected box (x, y, and z increments of the old grid).

Output:

Density file in Situs format. The new grid inherits the voxel size (grid spacing) of the old grid. The number of x, y, and z increments, and the coordinates of voxel (1,1,1) depend on the chosen range of voxels.

Purpose:

The subtract utility allows one to compute the difference density map (discrepancy map) of two matching datasets in Situs format. The input datasets can differ in the origin of their coordinate systems, but must have identical voxel size and number of x, y, and z increments.

Usage (at shell prompt):

Input at program prompt:

(none)

Output:

Density file in Situs format. The new density values are computed by subtracting the corresponding values of input grid 2 from those of input grid 1. The new grid inherits the voxel size and the number of x, y, and z increments of the two input grids, and the coordinate system of input grid 1.

Purpose:

Cross sections of the density data in the (x,y)-, (y,z)-, or (z,x)-planes can be inspected with the simple terminal window graphics program volslice. All voxels whose corresponding density values exceed a threshold level are represented by text characters. The background is represented by a two-dimensional grid to help identify positions in the cross section. This simple rendering method is sufficient to locate individual voxels in the map.

Usage (at shell prompt):

Input at program prompt:

Type of cross section, (x,y), (y,z), or (z,x).
Threshold (cutoff) value for the rendering of the density.
z, x, or y position of the cross section plane (grid units).

(Shell window:) Cross section of the input map in Situs format. Note that pairs of voxels neighboring in the vertical direction are represented by a single character:

'^' if the upper voxel density exceeds a threshold (cutoff) level,
'u', if the lower voxel density exceeds the threshold level,
'0' if both upper and lower voxel densities exceed the threshold level, and
' ', if the densities are below the threshold.

The suite of programs is supported by a documented header file (situs.h) containing user-defined parameters (e.g., the floating point type used) and by auxiliary library programs. The library programs handle input and output of atomic coordinates in PDB format (pdbio.c), input and output of volumetric data (volio.c), and input of data at the prompt (stdread.c).