User Guide
This guide is intended to be used as a reference manual. A usage example of FilaSitus is given in the Tutorial.
Content:

The main FilaSitus programs:

filabuild - Helical / Filament Symmetry Builder
kercon - Kernel Convolution

Other programs:

pindown - Map cropping tool borrowed from Situs1.4 (needed for the Tutorial)
Header File and Library Routines
filabuild - Helical / Filament Symmetry Builder

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. The tool is loosely based on the Situs pdbsymm tool.

Usage (at shell prompt):

./filabuild file1 [file2] file3

file1: inputfile, PDB format
file2: (optional) configuration file
file3: outputfile, PDB format

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.

All of these parameters can be specified also in a configuration file (in this order) see the included template files configure*.dat.

Output:

Helical / lattice symmetry PDB file containing multiple copies of input PDB file.
kercon - Kernel Convolution

Purpose:

The kercon utility is a real-space convolution tool loosely based on the Situs pdb2vol 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 or converted to other map formats using Situs.

Usage (at shell prompt):

./kercon file1 file2

file1: inputfile, PDB format
file2: outputfile, Situs format

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.
Note:

If in doubt, use kernel amplitude 1.

Output:

3D density file in VMD-readable 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 spacing in Angstrom, the map origin (the x, y, z coordinates of the first voxel in the map), and the map dimensions (numbers of x, y, and z increments). The Situs header is followed by the sequence of data values. The converted Situs files are VMD-readable and they are in ASCII format, allowing the user to verify the successful conversion of the data.

pindown - Map Cropping

Purpose:

For general map editing purposes we recommend the newer tools (such as voledit, volhist, voldiff, etc) distributed with Situs. The simpler pindown utility (from Situs 1.4) is included here 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):

./pindown file1 file2

file1: inputfile, Situs format
file2: outputfile, Situs format

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 coordinates of voxel (1,1,1) and the number of x, y, and z increments depend on the chosen range of voxels.
Header File and Library Routines

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).
Return to the front page.