collage - Simultaneous Multi-Fragment Refinement
colores - Exhaustive One-At-A-Time 6D Search
ddforge - Flexible Refinement Using Damped Dynamics.
elconde - Constrained Deconvolution of Tomographic Filament Bundles
eul2pdb - Graphical Representation of Euler Angles
map2map - Format Conversion
matchpt - Point Cloud Matching
pdb2sax - Create a Simulated SAXS Bead Model from a PDB
pdb2vol - Create a Volumetric Map from a PDB
pdbsymm - Symmetry Builder
qplasty - Interpolation of Sparsely Sampled Displacements
quanpdb - Vector Quantization of a PDB
quanvol - Vector Quantization of Volumetric Map
spatrac - Spaghetti Tracer for Tomographic Filament Bundles
strwtrc - Struwwel Tracer for Tomographic Filament Networks
vol2pdb - Create a PDB from a Volumetric Map
volaver - Map Averaging
voldiff - Discrepancy / Difference Mapping
voledit - Inspecting 2D Sections and Editing of 3D Maps
volfltr - Denoising 3D Maps and 2D Image Stacks
volhist - Inspecting and Shifting the Voxel Histogram
volmult - Map / Mask Multiplication
voltrac - Alpha-Helix Detection and (Legacy) Filament Tracing
Header File and Library Routines

Purpose:

Basic usage (at shell prompt):

The basic input parameters are:

<Density map> Density map in Situs or CCP4/MRC format (auto detect). To convert other maps to either of these formats use the map2map utility.

<PDB file(s)> A single or few input PDB files can be specified as a sequential list (all arguments are white space delimited, i.e. there should be no commas or other symbols between file names). To avoid very long arguments when processing a large number of input files one can also specify a directory name as the second argument. The designated directory should contain only relevant PDB input structures (identified by a .pdb or .PDB filename extension).

-res <float> Estimated resolution of the density map in Å. [default -res 15.0]

-cutoff <float> Density map threshold value. All density levels below this value are ignored. You can use volhist to rescale or shift the density levels in the voxel histogram. [default -cutoff 0.0]

-corr <int> This option controls the fitting criterion.
Two options are implemented: 

Input at program prompt:
None.

Purpose:

The basic input parameters are:

<density map> Density map in Situs or CCP4/MRC format (auto detect). To convert other maps to either of these formats use the map2map utility.

<PDB structure> Atomic structure in PDB format.

-nprocs <int> This option sets the number of processors used for the on-lattice 6D search and the off-lattice Powell optimization. Colores supports shared memory systems with multiple core and/or hyperthreaded processors. Usage on more than 16 cores may be unstable on some systems, use larger numbers at your own risk.  [default: the number of logical cores of the CPU but no more than 16]

-res <float> Estimated resolution of your density map in Å. [default -res 15.0]

-cutoff <float> Density map cutoff value. All density levels below this value are set to zero. You can use volhist to rescale the density levels or to shift the background peak in the voxel histogram to the origin. [default -cutoff 0.0]

-deg <float> Angular sampling of the rotational search space in degrees. For typical electron microscopy maps the recommended angular step size is 20-30° (a smaller step size might return near-redundant solutions in the peak search, and any orientational mismatch will be refined in the subsequent Powell optimization anyway). [default -deg 30.0]

-corr <int> This option controls the fitting criterion.
Two options are implemented:

-ani <float> Defines the resolution anisotropy factor (z direction vs. x,y plane) [default: -ani 1.0]. Allows one to set a different resolution in the z direction vs. the x,y plane. E.g. "-ani 1.5 -res 20" specifies a 30 A resolution in the z direction, and a 20 A resolution in x,y. This is useful for researchers dealing with membrane protein or tomography reconstructions that have a reduced resolution in the z direction.

-erang <float float float float float float> Defines the rotational space limits according to the range of the Euler angles (psi, theta, phi). By default the entire rotational space is considered [default: -erang 0 360 0 180 0 360]. Note that the Euler angle range is not limited to these standard intervals, so you can specify also negative values (within certain limits), but in any event any colores output angles are remapped to the standard intervals. For example, if you want to perform a fine search of 2° angular sampling in only one of the Euler angles, these are the options:

-euler <int> There are three ways to generate an exhaustive list of Euler angles that covers (nearly) uniformly the rotational space for a given angular sampling (option -deg). The proportional method yields very even results and also performs well for smaller intervals specified via '-erang'. The pole sparsing method is widely used but yields slightly less uniform distributions. The spiral method also produces a less uniform distribution, but for medium to low resolution docking it is quite reasonable. The Euler angles are saved to a file col_eulers.dat, and you can edit this file and reload it using the -euler 3 option. This way, you can also load any manually generated Euler angle files.

-peak <int> This option sets the peak search algorithm. By default, a combined sorting and filtering-based approach is used. A stand-alone filtering-based algorithm is available as an option.

-explor <int> Controls the number of the best fits found in the 6D on-lattice search to be subsequently refined by Powell optimization. This number is only an upper bound for the final number, since redundant solutions are removed in the Powell stage. [default -explor 10]

-sizef <float> FFT zero padding factor. The low resolution map is enlarged by a margin of width sizef times the map dimensions. We have optimized the zero padding empirically [default -sizef 0.1 for standard and 0.2 for Laplacian correlation]

-sculptor Save additional output files for interactive exploration (manual peak search) with our Sculptor molecular graphics program. This is documented in a Sculptor tutorial under item “Loading exhaustive search data into Sculptor“ [default: Off]

-nopowell This flag skips the Powell optimization and only the on-lattice search is performed. By default the Powell optimization is turned on.

-pwti <float int> Powell tolerance and max number of iterations of the Powell algorithm. This two parameters control the convergence of the optimization. By default, the tolerance is set to 1e-6 and the max iterations are limited to 25.

-pwdr <float float> Initial gradient of the translational and rotational search in the Powell optimization. By default the initial rotational gradient is set to 25% of the angular sampling (but not larger than 10°), and the translational initial gradient is set to 25% of the voxel spacing. To use the default value only for the rotational or only for the translational gradient, choose a negative number for the parameter that must be left at default, and your chosen value for the other.

-pwcorr <int> This option sets the Powell correlation algorithm. By default, the fastest algorithm which reproduces the standard cross correlation coefficient to within the Powell tolerance is determined at runtime.

-nopeaksharp This flag skips the peak sharpness estimation procedure in order to save processing time. By default, the peak sharpness estimation is turned on.

None.

Output:

Here is a brief description of the output files (see also the file headers);

col_best*.pdb The atomic coordinates in PDB format of the best fits found in the search. The total number of best fits saved is controlled by the option -explor, but only non-degenerate fits are returned, so the number may be smaller than specified by the -explor option. The PDB header contains information about the docking (sampling, fit criteria used, correlation values, position and orientation etc.). It also includes a table containing the angular variability of the correlation about the fit.

col_rotate.log This file contains the best translational fit (on-lattice) found for each rotation. The first 3 columns are the Euler angles (in degrees), the next 3 columns are the translational coordinates that gave the highest correlation value, followed by the correlation value (not normalized).

col_powell.log This file contains information about the Powell off-lattice search performed for the best fits from 6D lattice search. As before, rotational and translational coordinates correspond to the first 6 columns , but note that the Euler angles are in radian units.

col_trans.sit The on-lattice translation function (in Situs map format). Since the translational search space corresponds to the input map lattice , we can generate a map in which density values are the correlation values normalized by the maximum. You can use map2map to convert this to other formats.

col_trans.log Same as col_trans.sit, but instead of a map, the translational correlation values are stored in a regular file. Each row that corresponds to a lattice coordinate (columns 4,5,6) shows the corresponding Euler angles (columns 1,2,3) in degrees that exhibit the highest correlation value (column 7).

Notes:

Purpose:

Usage (at shell prompt): 

Type 1:  PDB to be fitted in density map:

Type 2:  PDB1 to be flexed toward PDB2:

Type 3:  PDB1 to be flexed toward PDB2 and fitted in density map:

Mandatory arguments (to be given in this order):

<PDB> or <PDB1>  <PDB2>  Atomic structures in PDB format (extension “.pdb”).

<density map>  Density map in Situs or CCP4/MRC format (auto detect). To convert other maps to either of these formats use the map2map utility. 

<min disp between outputs>  Desired minimum RMS displacement between output conformations, in Å. Typical range: 0.5 - 5.

<map resolution>  in Å.

<density threshold>  Density values below this will be set to 0, and all others will be lowered by this amount.

<damp/drag ratio>  Ratio between damping and drag strengths. Typical range: 10-100.

<side-chain optim>  Side-chain "optimization" flag. This enables the rebuild of full atomic side chains from the truncated ones used internally by ddforge (see Figure below). Possible values: 0: no side-chain rebuild; 1: initial rebuild only; 2: subsequent only (only new conformations will be treated); 3: both. For options 1, 2 and 3, you need to download SCWRL4 and install it (in order for ddforge to find the executable "Scwrl4", you can put it in the folder requested by ddforge and denoted in ddforge.c line 2727 (or to specify your own path, edit this line in the code and and reinstall ddforge). Also, after installing SCWRL4, you may also need to edit the Scwrl4.ini file so the line at the top "[RotLib] FilePath" points to your side chain library location. Please note that ddforge behavior is slightly modified by the option flag. For options 1 and 3, SCWRL4 will automatically remove any unknown molecules or non-amino acid residues from the PDB, which may be unintentional. If you run your model the first time it is better to use options 0 or 2, in that case ddforge will terminate with an error message if it finds unknown residues and you can fix these issues manually in your PDB.

<force-field cutoff distance>  Maximum distance in Å for the action of the force field [which attracts the PDB toward the target(s) (PDB and/or map)]. Typical range: 10-50.

<max disp per step>  Maximum allowed RMS displacement of the PDB at each step of the integration, in Å. Typical range: 0.5 - 2. 

Optional arguments:

-rdfile <residue data>  Residue data file name. See detailed description below.

-dcfile <distance constraints>  To impose distance constraints, a file with their definition can be specified as the last argument. See detailed description below.

Input at program prompt:

None.

Output:

A series of PDB files is created, with names built from the name of the PDB1 file, by adding “.deform.n” to its base name, for n ranging from 1 to the total number of conformations produced till convergence.  These files describe the trajectory undergone by the initial atomic structure until its final fitted conformation.  Also, there is output sent by default to the “stdout” stream. This can be redirected to a text file.

First, ddforge echoes the parameters specified on the command line, and basic information about the input files. Then there is a progress log of the optimization of sigma and threshold parameters used for generating the simulated maps. Then comes the evolution proper.  The first column, “Conf#”, gives the conformation number of the PDB structure written to file at that time. “Step#” refers to the time step in the integration procedure.  “Time” and “speed” are simulation values —not really useful for the user. “Disp.” refers to the RMS displacement of the structure at that step. “Dist_cut” is the cutoff distance for connecting pairs of atoms with dampers.  “Overlap” is the amount of overlap between the density map and the simulated map, which can be used as a measure of convergence.  “Cos” is an internal parameter used in time-step control —not relevant to the user.  Lastly, “Compute time” is the actual CPU time up to that point of the trajectory.

The program will stop automatically according to a convergence criterion based on the analysis of the overlap evolution over time. The criterion aims at recognizing the saturation of the overlap function, by means of an exponential regression. Details about this are given in the paper. Note that the program will need to run slightly past this point to estimate the regression parameters. When it eventually stops, the screen output will indicate the proposed safe ending time, and we recommend to use the conformation just prior to this time, as the later conformations (used for regression) will probably be over-fitted.

Optional residue data file:

This allows the user to fine-tune the modeling of the amino acid resides. If this file is not specified on the command line, ddforge will assume that all atoms are freely movable and that all internal degrees of freedom are free. 

The structure of this optional residue data file is exemplified here:

where CH = PDB chain character, RES = PDB residue number, ORI = origin, TAR = target.

The first line is ignored by ddforge, it can be used for comments, or as a header indicating the name of each column. Starting with line 2, every line holds a separate residue specification. Residues are identified by their PDB residue number and by the PDB chain character, as present in the origin PDB file. Columns 4 and 5 ("target" residues) are only needed for Type 2 or 3 usage (i.e. fitting to another PDB, see below).  

The CODE column is a decimal code number that specifies which variables of each residue (of the “origin” structure) are to be free, and whether the residue should be static (fixed) in space or not (this is useful for “loop closures”).  This is indicated after transforming the decimal code into binary form. The resulting bits and their decimal weights (powers of 2) have the following meaning:

Bit  Weight  Meaning

Please refer to the figure below for the meaning of the variables. The user should note that ddforge uses a hierarchical, internal coordinate system for each independent chain. The global (absolute) position and orientation of the entire chain is set by the x, y, z coordinates of the first N(1) atom, as well as by the lambda, theta, and phi(1) angles (six rigid body degrees of freedom). This is the reason why bits 0 and 1 apply only to the first residue of each chain. All remaining degrees of freedom of the chain, designated by bits 2, 3, and 4, are internal angles. 

Any invalid codes are automatically corrected. (For example, if bit 0 or bit 1 is set for a residue that's not the first of the chain, or if bit 3 is set for the last residue of a chain, or if bit 2 is set for a proline residue if it’s not the first of the chain, etc.)

Special cases:

• In case the residue data file is not specified on the command line, ddforge will assume that all residues have a decimal code number of of 31, which means that x, y, z, lambda, theta, phi, psi, and chi are all free.
• In case the residue data file is used, but a residue is missing in the residue data file (although present in the origin PDB), it is treated as if its code were 0. The effect of this depends on whether the missing residue is (i) at the start of the chain (the residue is static and the entire chain is pinned down) or (ii) in the middle of the chain (the phi,psi,chi angles are frozen, i.e the residue moves as a rigid body).
• If there are gaps in the same chain, i.e. there are missing residues in the origin PDB itself, we recommend assigning a new chain character to every separate polypeptide chain segment. The program will try to handle such gaps gracefully by assigning a very long rigid "bond" between adjoining segments of the same chain (rigid, because omega angles, i.e. torsions about C-N bonds, are taken as constants).
• Bit 6 is a special modification that allows to fix only the backbone atoms during the refinement.

Figure: ddfforge residue data file variable name conventions

Columns 4 and 5 (see above residue data file example) are needed only when an atomic structure (i.e. PDB2) is used as the target; the columns indicate the target residue toward which the origin residue of columns 2 and 3 should be pulled. In the above example, the three backbone atoms are pulled toward the corresponding atoms of the target structure. As the example shows, some residues may be left without any target (no force is then exerted on those particular atoms). 

Setting up residue data files for large PDBs might become labor intensive. You can find templates and scripts for generating them in the flexible fitting tutorial.

Optional distance constraints file:

The user has the option to specify this file to impose distance constraints between certain residues, e.g. for purposes of keeping secondary structure elements intact during the refinement. The structure of this file is exemplified here (data will be read from line 2, line 1 is a user-defined header that will be ignored):

where CH = chain and RES = residue.  Each line (after the first) represents one distance constraint between the residues given. The first 2 columns refer to one of the endpoints of the constraint, while the last 2 columns refer to the other endpoint.

Purpose:

Usage (at shell prompt):

The argument “n” specifies the operation to be carried out. The program should be called sequentially with n = 0, 1, 2, and 3, see details below. Depending on the data, some of these steps may not be necessary. 

n = 0: Spatial decomposition of the input map into smaller maps:

Calling elconde with n = 0 will generate a set of smaller subtomograms that cover the input map. We call the input map “global map” and the smaller maps “local maps”. The local maps will overlap with each other along their boundaries as a way to deal with boundary artifacts. We recommend a size of roughly 1 million voxels for each of the local maps, as a good compromise between memory requirements for the solver and artifacts in the solution caused by wraparound effects if the maps are too small. This ideal size is given in the parameter file (described below), and the default values in there already satisfy the above size recommendation.

Arguments (mandatory):

n = 1: Map deconvolution and local U-map generation:

Calling elconde with n = 1 will proceed to the deconvolution of all the local maps generated in the previous step . This part (function condesa in the source code) runs in parallel, using OpenMP with OMP_NUM_THREADS cores (or as many as available on the system if not set). E.g. export OMP_NUM_THREADS=4 will use 4 threads. This part also generates log files for each of the maps, containing details on the progress of the optimization iterations. Screen output is also produced. Both can be controlled by parameters in the parameter file (described below).

Mandatory arguments:

Optional argument:

n = 2: Combination of the U-maps into a global U-list:

Calling elconde with n = 2 will collect (function collect in the source code) all the U-maps generated in the previous step and generate a global “U-list”. This is a reduced representation of a U-map, which covers the whole of the input (global) map. Its convolution with the “shape kernel” yields the global deconvolved map (done in the next step.

Arguments (mandatory):

n = 3: Tracing of the global map:

Calling elconde with n = 3 will use the U-list created in the previous step and generate a traces file (UCSF Chimera .cmm format). The corresponding function in the source code is named ctracer. It will optionally create the global deconvolved T (or "true") map described in the paper (Kovacs et al., 2020). We observed that the T map looks best for tightly packed (near-parallel) bundles of actin filaments in the shaft region of stereocilia, but it was not as well defined in semi-organized actin filaments in the taper region of stereocilia. Therefore, the output of the T map is optional, whereas the traces are considered more reliable.

Purpose:

Usage (at shell prompt):

Input at program prompt:

None.

Pseudo-atomic structure in PDB-format. Each triplet of Euler angles in the input file is represented as a point on a 10A radius sphere. The phi Euler angle (rotation in the projection plane) is encoded in the B-factor column of the PDB file (in radians units), whereas theta and psi correspond to longitude and latitude on the sphere.

Former names: convert, conformat

Purpose:

Situs programs require density maps either in Situs or in CCP4/MRC format. The details and conventions of these formats are documented elsewhere. The map2map program converts other map formats to and from these supported formats.

The map2map utility reads and writes many file formats used by standard EM or crystallographic application software. These include the MRC, SPIDER, and CCP4 formats and generic 4-byte floating-point binary formats (automatic byte-order adjustment). X-PLOR maps in ASCII format, and ASCII files that contain a sequence of density values in free format are also recognized. The reverse conversion to CCP4, MRC, X-PLOR, or SPIDER format is also supported.

Usage (at shell prompt):

Interactive input at program prompt (for automation see below):

• Input file format.
• Input file specific header fields if they are missing or if manual editing of fields is selected.

Notes:

• Also check out the free conversion programs MAPMAN/RAVE, and especially em2em which also has Situs and CCP4/MRC format options.
  

• The maps are quite robust under most round trip conversions, but note that header fields WIDTH, ORIGX, ORIGY, ORIGZ are not part of the SPIDER specification and cannot be saved in SPIDER.
• Advanced users may try the manual assignment of header fields, if available. 
• You can automate this interactive program by "overloading" the standard input (if you put expected values in a script, see run_tutorial.bash script in the tutorials).

Supersedes former programs: qdock, qrange

Purpose:

Basic usage (at shell prompt):

Optional command line parameters:

-res <float> Estimated resolution of file2 in Å. This currently affects only the computed cross-corelation value, not the docking.  [default 15.0Å]

-mincv <int> For autogeneration of feature points, or "codebook vectors" (CV), minimum number N of vectors per structure (file4) unit, must be >= 4.  [default 4]

-maxcv <int> For autogeneration of codebook vectors, maximum number N of vectors per structure (file4) unit, must be >= mincv. [default 9]

-units <float> For autogeneration of N and M (M ≈ units * N) codebook vectors, number of structure units contained in target volume. [default 1.0]

-nprocs <int> Number of parallel processing threads. This is still an experimental feature, so use with caution: We noticed that the parallel performance can be compiler or machine-dependent. If a multi-threaded application appears slow or unstable on your system, we recommend to reduce the number of threads, or use the default serial application. [default: 1]

mpt_CV_001.pdb ... mpt_CV_00n.pdb The fitted codebook vectors in PDB format.

mpt_CV_map.pdb The codebook vectors for file2 (volumetric map) in PDB format.

mpt_001.pdb ... mpt_00n.pdb The atomic coordinates in PDB format of the structures fitted by codebook vectors.

[ or mpt_001.log ... mpt_00n.log log files (text format) with fitting transformation. ]

Notes:

Purpose:

Usage (at shell prompt):

Interactive input at program prompt (also suitable for automation):

PDB file that contains the centers of the simulated beads with the radii in the occupancy column. This file can then be either inspected with a visualization program (for example VMD), or processed into a bead volume map using pdb2vol.

Purpose:

Usage (at shell prompt):

Interactive input at program prompt (also suitable for automation):

• If water, hydrogen, or codebook vector atoms are present, choice of ignoring them.
• Choice of atom mass-weighting and B-factor cutoff level. Atoms with B-factors above the cutoff level will be ignored.
• Desired voxel spacing for the output map.
• Kernel width, defined by either the kernel half-max radius r-half (enter positive value) or by the "Situs" resolution r-s of the kernel (enter value of r-s as a negative number). The standard deviation (sigma) of the 3D Gaussian is assumed to be half of r-s (for details and relationships with other resolution conventions see section 4 in Wriggers, 2012). In the case of "hybrid" maps (i.e., experimental EM maps transformed to a density PDB with vol2pdb, which can then be filtered by pdb2vol to a desired target resolution r-target), the pre-existing resolution r-em>0 of the EM map needs to be taken into account. The compensation of r-em>0 requires an adjustment of r-s. The squares of the resolution values add in the convolution: r-em^2 + r-s^2 = r_target^2. Therefore, the adjusted r-s (which for a Gaussian kernel needs to be entered as a negative number at the command prompt, see above) is given by r-s = sqrt (r_target^2 - r-em^2). 
• Type of smoothing kernel:
• Gaussian, exp(-1.5 r^2 / sigma^2)
• Triangular, max(0, 1 - 0.5 |r| / r-half)
• Semi-Epanechnikov, max(0, 1 - 0.5 |r|^1.5 / r-half^1.5)
• Epanechnikov, max(0, 1 - 0.5 r^2 / r-half^2)
• Hard Sphere, max(0, 1 - 0.5 r^60 / r-half^60)
• Choice of kernel width correction for lattice smoothing, i.e. grid blur. (Subtracts the voxel grid mean-square deviation from the kernel variance.) This adjustment is typically unnecessary, unless the voxelation of the map is significant. The effect of the voxelation is similar to the pre-existing blur in the case of hybrid maps above, so kernel size can be slightly adjusted to compensate for any additional resolution lowering by the voxelation.
• The kernel amplitude at the kernel origin (r=0).
• You can automate this interactive program by "overloading" the standard input (if you put expected values in a script, see run_tutorial.bash script in the tutorials).

Density map either in Situs or CCP4/MRC format (format based on file name extension: Situs if .sit or .situs, CCP4/MRC otherwise) at the desired target resolution value r_t. 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. 

Purpose:

Usage (at shell prompt):

Interactive input at program prompt (also suitable for automation):

Depending on symmetry type:

• Helical rise per subunit (in z-direction).
• Angular twist per subunit (sign determines handedness).
• Desired number of subunits to be placed before file1 structure.
• Desired number of subunits to be placed after file1 structure.
• Order of the principal symmetry.
• [If file2 is unspecified: x- and y-position of helical axis (offset from file1 coordinate system origin).]
• z-position of secondary symmetry axes (for D symmetry - offset from file1 coordinate system origin).
• You can automate this interactive program by "overloading" the standard input (if you put expected values in a script, see run_tutorial.bash script in the tutorials).

Symmetry PDB file containing multiple copies of input PDB file.

Purpose:

This program performs an approximative flexible fitting of atomic resolution data based on a coarse input model of displacements. The interpolation-based flexing is quite reasonable at the carbon alpha level of proteins, but bond lengths and angles at the atomic level may get distorted a bit. Flexing with qplasty is offered as a user-friendly alternative to a more complicated molecular dynamics simulation protocol. The qplasty-flexed structures may be processed further by a variety of simulation or structure refinement tools. For more information see (Rusu et al.,  2008).

Usage:

Usage (at shell prompt):

Optional interactive / manual input at program prompt with -interactive:

• The choice of interpolation method (Thin-Plate-Splines, Elastic Body Splines, Global Inverse Distance Weighting, Local Inverse Distance Weighting). The default method (Global IDW interpolation with exponent 8) performed best in our tests (Rusu et al, 2008), so there is no need to change it except for further validation of the supported algorithms.
  
• Various kernel and parameter choices (for details see Rusu et al, 2008).

• (Program level:) Various interpolation parameters and methods.

• (Shell level:) The flexed atomic coordinates will be exported into file4.

Former name: qpdb

Purpose:

Specialized tool to perform a vector quantization (coarse-graining) of atomic resolution data into a set of point-based fiducials, the so-called codebook vectors. To enable skeleton-based flexible docking with quanvol, quanpdb includes options to learn vector distances and to export the Voronoi cells generated by the codebook vectors.

Usage:

Usage (at shell prompt):

Interactive input at program prompt (also suitable for automation):

• If water, hydrogen,codebook vector atoms are present, choice of ignoring them.
• B-factor cutoff level. Atoms with B-factors above this level will be ignored.
• Number of codebook vectors.
• Choice of computing the vector connectivities (neighborhood relationships) with the Competitive Hebb Rule and writing them to a file.
• Choice of computing the Voronoi cells and writing them to a file.
• You can automate this interactive program by "overloading" the standard input (if you put expected values in a script, see run_tutorial.bash script in the tutorials).

• (Program level:) The sphericity, a measure between 0 and 1 that characterizes how spherical the shape of the structure (file1) is. After the vector quantization the program prints the average rms variability of the codebook vectors in Angstrom. Also given in Angstrom is the radius of gyration of the vectors.

• (Shell level:) Codebook vectors in PDB-formatted output file. The vector rms variabilities, representing the precision of the codebook vectors, are written to the occupancy fields of the PDB-style atom entries. The effective radii of the Voronoi cells are written to the B-factor fields of the PDB-style atom entries. (Optional) Vector connectivities can be written to a PSF file or a distance constraints file. Constraint file entries are triples of free-format values in the order <index1> <index2> <distance in Angstrom>, where the indices correspond to the order of vectors in file2, counting from 1. (Optional) The Voronoi cells can be written to a PDB file consisting of the file1 atom entries where the index of each corresponding vector is written to the B-factor field of the output file.

Purpose:

Specialized tool to perform a vector quantization (coarse-graining) of density maps into a set of point-based fiducials, the so-called codebook vectors. quanvol supports feature-based tracking and flexible docking with qplasty. In the absence of existing vector positions, quanvol carries out a global search using the TRN algorithm. If start vectors are already known, the LBG refinement algorithm (local search) is used instead of TRN, or connectivities can be learned. LBG allows to add distance constraints to the vector refinement that are useful for flexible docking.

With TRN, a small number of calculations (8 by default) are repeated with different random number seeds. The averaged codebook vectors and their statistical variability are then written to the output file. With LBG, no statistical clustering is performed. In this case it is important to specify reliable initial positions from a prior quanvol run.

Usage:

Before applying quanvol, one can modify the density map using voledit. Next, the user must determine a suitable number of codebook vectors. Only densities above a user-defined threshold value are considered by quanvol to eliminate background noise in the low-resolution data. Depending on the noise, this threshold value should be at 50-80% of the level that is typically considered the "molecular surface" of the biopolymer in the low-resolution data.

Usage (at shell prompt):

Interactive input at program prompt (also suitable for automation):

• Choice of utilities to inspect the density distribution (e.g. voxel histogram).
• Threshold (cutoff) density value.
• Number of codebook vectors.
• (If file2 is specified): Choice of entering distance constraints manually or from a file. There are two constraint file options. Constraint file entries generated e.g. with quanpdb are triples of free-format values in the order <index1> <index2> <distance in Angstrom>, where the indices correspond to the order of vectors in file2, counting from 1. It is also possible to read the connectivities from a PSF file in which case the missing distances are computed from file2.
  
• Choice of computing the vector connectivities (neighborhood relationships) with the Competitive Hebb Rule and writing them to a file.
• You can automate this interactive program by "overloading" the standard input (if you put expected values in a script, see run_tutorial.bash script in the tutorials).

• (Program level:) Statistical analysis of the vectors and their radius of gyration, i.e. the radial rms deviation from the vector center of mass.

• (Shell level): Codebook vectors in a PDB-formatted output file. The vector rms variabilities, representing the precision of the codebook vectors, are written to the occupancy fields of the PDB-style atom entries. If desired, vector connectivities can also be written to a PSF file or to a distance constraints file.

• Vector connectivities in PSF format can be visualized and edited as bond connections (together with the atom-style PDB entries of file2 and file3) using the molecular graphics program VMD. Simply overload the PSF file into the PDB file in the VMD 'Molecule' menu. Then under the 'Mouse' menu select 'Add/Remove Bonds'. The edited connectivity can then be saved later into a PSF file from the VMD command console (assuming your molecule is 'top'):

set sel [atomselect top all] $sel writepsf my.psf

• If there are cluster size deviations from the expected value (default: 8) when using the TRN algorithm, refine the found vector positions by passing them to quanvol as input file of a second, LBG run.

• Distance constraints do not determine the chirality (handedness) of vector connections. If you encounter mirror images or otherwise flipped connections after running quanvol compared to connections determined with quanpdb, you need to experiment with the indexing of your constraints. The LBG method combined with the SHAKE constraint algorithm is relatively insensitive to the position of start vectors.

Purpose:

Within cells, cytoskeletal filaments are often arranged into loosely aligned bundles. These fibrous bundles are dense enough to exhibit a certain regularity and mean direction, however, their packing is not sufficient to impose a symmetry between, or specific shape on, individual filaments. This intermediate regularity is computationally difficult to handle because individual filaments have a certain directional freedom, however, the filament densities are not well segmented from each other (especially in the presence of noise, such as in cryo-electron tomography). Assuming that the tomogram can be rotated such that the filaments are predominantly oriented in the Y direction, Spaghetti Tracer first identifies local seed points for candidate filament segments, which are then grown from the seeds using a dynamic programming algorithm. In a recent paper we tested and optimized various algorithmic variations of our framework on simulated tomograms that closely mimic the noise and appearance of experimental maps. We implement here the superior bipyramidal accumulation scheme for path density. Also, the multiplication of forward and backward path densities provides for an efficient filter that lifts the filament density above the noise level. Resulting from our tests is a robust and efficient method that can be expected to perform well (F1 scores 0.86-0.95) under experimental noise conditions.

Usage:

Usage (at shell prompt):

The argument “n” specifies the operation to be carried out. The program should be called sequentially with n = 0, 1, 2, and 3, see details below. Depending on the data, some of these steps may not be necessary. 

n = 0: Filamentous pattern-enhancement using path densities:

Calling spatrac with n = 0 will carry out an optional path-density-based enhancement (filtering) of filamentous densities so they rise above the noise level and can be easier detected. The path densities are enhanced in the Y-direction with a user-specified voxel length parameter. The enhanced map "combined_path_density.mrc" in the output directory uses combined (i.e. multiplied) forward and backward path densities.

Mandatory arguments:

Optional argument:

n = 1: Candidate filament generation:

Calling spatrac with n = 1 will generate candidate filament segments (CFSs) from seeds and stratify them by path density into 10 bins for further automated processing in the next steps.

Mandatory arguments:

Optional argument:

n = 2: Backtracing, thresholding and fusion of filament segments:

Calling spatrac with n = 2 will automatically select the optimum threshold bin, and fuse the resulting CFSs into longer filaments.

Mandatory arguments:

Optional arguments:

n = 3: Statistical evaluation of predicted models:

Calling spatrac with n = 3 computes precision, recall and F1 scores for predicted filements compared to ground truth filaments, as described in (Sazzed et al., 2022).

Arguments (mandatory):

Purpose:

Struwwel Tracer is a tool for the tracing of arbitrarily oriented actin filaments in cryo-electron tomography maps. The tool is time efficient and can complete the tracing process in just a few minutes. Struwwel Tracer accumulates densities along paths of a specific length in various directions, starting from locally determined seed points. The highest density paths originating from the seed points form short linear candidate filament segments, which are triaged user-inspection of a so-called "pruning map" that visualizes the likelihood of being part of longer filaments. The pruned linear candidate filament segments are then iteratively fused into continuous, longer, and curved filaments based on their relative orientations, gap spacings, and extendibility. When applied to the simulated phantom tomograms of a Dictyostelium discoideum filopodium at experimental conditions, we achieved F1 scores ranging from 0.85 to 0.90, depending on the noise level. 

Usage (at shell prompt):

The argument “n” specifies the operation to be carried out. The program should be called sequentially with n = 1, 2, and 3, see details below. Depending on the data, some of these steps may not be necessary. 

n = 1: Creates a pruning map for visual inspection:

Calling strwtrc with n = 1 will create a set of candidate filament segments (CFSs) and a "pruning map" (essentially a masked filament map where filaments are weighted by their path density). The resulting pruning map is placed in the output directory should be visually inspected in a molecular graphics program to find the intensity level that separates the true filaments from noise. The output directory also contains a number of intermediate files denoted by step#* filenames., and a directory with CFSs for further processing in the next step.

Mandatory arguments:

Optional argument:

n = 2: Thresholding and fusion of filament segments:

Calling strwtrc with n = 2 will apply the user-selected threshold, and fuse the surviving CFSs into longer filaments.

Mandatory arguments:

Optional arguments:

n = 3: Statistical evaluation of predicted models:

Calling strwtrc with n = 3 computes precision, recall and F1 scores for predicted filements compared to ground truth filaments, as described in (Sazzed et al., 2023).

Arguments (mandatory):

Purpose:

Usage (at shell prompt):

Input at program prompt:

None.

Output:

PDB format file with densities written to occupancy field (if rescaling is necessary due to limited bandwidth in that field, the conversion factor is reported by the program).

Purpose:

Usage (at shell prompt):

Input at program prompt:

None.

Output:

Density map either in Situs or CCP4/MRC format (format based on file name extension: Situs if .sit or .situs, CCP4/MRC otherwise). The new density values are computed by averaging the input densities. The input maps are resampled by trilinear interpolation, if necessary, to span all input files. The voxel spacing of the output grid is set by input file 1.

Former name: subtract

Purpose:

Usage (at shell prompt):

Input at program prompt:

None.

Output:

Density map either in Situs or CCP4/MRC format (format based on file name extension: Situs if .sit or .situs, CCP4/MRC otherwise). The new density values are computed by subtracting the corresponding density values of file2 (which is resampled by trilinear interpolation, if necessary) from those of input file1. The output grid thus inherits the geometric parameters from file1.

Purpose:

Interactive input at program prompt (also suitable for automation):

• Type of cross section, (x,y), (y,z), or (z,x).
• Display cutoff value for the rendering of the density (options).
• z, x, or y position of the cross section plane (grid units).
• Display voxel step (for display of larger maps).
• Polygon clipping parameters and vertices (options).
• Cropping parameters in voxel units (options).
• Zero padding in voxel units (options).
• Density threshold where all densities will be set to zero (or one) (options).
  
• Segmentation parameters to extract a targeted contiguous volume. Originating from the vicinity of a given start voxel, voledit finds recursively the maximum contiguous volume formed by neighboring voxels that exceed a given threshold density level. An additional layer is added for aesthetic reasons to facilitate isocontouring near the cutoff level. Although the extracted grid contains some voxels (in the contour layer) with densities below the cutoff, all voxels with density values above the cutoff are guaranteed to be part of the found contiguous volume. Voxels outside the contour layer are assigned a density value of 0.
• File name for 2D slice or 3D volume output file (options).
• You can automate this interactive program by "overloading" the standard input (if you put expected values in a script, see run_tutorial.bash script in the tutorials).

(Shell window:) Cross-section of the input map for standard section indices > 0 (follwing Situs index numbering convention starting at 1), or the projection (average) along this direction for a special slice 0. Larger maps are resaled by the voxel step parameter that can be set under options. Pairs of displayed voxels neighboring in the vertical direction are represented by a single character:

This program requires the use of a fixed-width font in the shell window.

Purpose:

Usage (at shell prompt):

Required command line parameters:

mask_width <int> 2*n+1 (odd integer), where integer n > 0 is the minimum path length.  [example: 5]

path_type <int> 0 for 4-neighborhood 2D model (image stack)
                             1 for 8-neighborhood 2D model (image stack)
                             2 for 6-neighborhood 3D model (3D map)
                             3 for 26-neighborhood 3D model (3D map) [example: 3]

beta <float> weighting exponent. This exponent determines how the ranked paths affect the filter output. The number depends on the path cardinality (see paper). Larger values are more discriminative. [example: 0.0001]

Optional command line parameter:

nprocs <int> Number of parallel processing threads.  [default: number of cores of the CPU]

Input at program prompt: 

None.

Purpose:

Usage (at shell prompt):

Interactive input at program prompt (if outfile specified):

• Offset density value (bias, will be added to all voxels).
• Scaling factor (gain)
• You can automate this interactive program by "overloading" the standard input (if you put expected values in a script, see run_tutorial.bash script in the tutorials).
  

• (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:) If specified, a density map is written either in Situs or CCP4/MRC format (format based on file name extension: Situs if .sit or .situs, CCP4/MRC otherwise). The new density values are computed by adding the offset value and by multiplying the scaling factor entered at the program prompt, and setting any negative densities to zero. The new grid inherits all size and position parameters of the old grid.

Purpose:

Usage (at shell prompt):

Input at program prompt:

None.

Output:

Density map either in Situs or CCP4/MRC format (format based on file name extension: Situs if .sit or .situs, CCP4/MRC otherwise). The new density values are computed by multiplying the corresponding density values of file2 (which is resampled by trilinear interpolation, if necessary) to those of input file1. The output grid thus inherits the geometric parameters from file1.

Purpose:

Basic usage (at shell prompt):

The basic input parameters are:

<density map> Density map in Situs or CCP4/MRC format (auto detect). To convert other maps to either of these formats use the map2map utility.

-res <float> Estimated resolution of the density map in Å. [default: 8.0]

-ntraces <int> The number objects (i.e. alpha helices or filaments) to be traced. [default: 20]

-ani <float> Resolution anisotropy factor (Z vs XY), typically ≥ 1. [default: 1.0]

-lambda <float> Orientation-dependent density attenuation parameter (Z vs XY), typically ≤ 1. [default: 1.0]

More advanced options (at shell prompt):

The inner workings of the genetic algorithm and many more parameters can be controlled in detail using a parameter configuration file that can be edited by the user. For information on how to write and read such a configuration file, call voltrac with the -expert option.

Output:

All traces detected during the search as well as a ranked list of top -ntraces traces (see paper) will be written as PDB files to the output directory [default: voltrac_results]. Any parameter configuration file and output redirect (log file specified by a configuration file) will also be saved in this directory.

The suite of programs is supported by various header files (.h) containing user-defined parameters and by auxiliary library programs using C and C++ code. The library programs and their respective header files handle input and output of atomic coordinates in PDB format (lib_pio), input and output of volumetric data (lib_vio), input of data at the command prompt (lib_std), error handling (lib_err), Euler angle generation (lib_eul), random number generation (lib_rnd), array management (lib_vec), Powell optimization (lib_pow), map manipulation (lib_vwk), PDB manipulation (lib_pwk), symmetric multiprocessing (lib_smp), timing (lib_tim), and support for specific tools such as ddforge (lib_ddf), matchpt (lib_mpt), elconde (lib_cde), strwtrc (lib_str), spatrac (lib_spa), volfltr and voltrac (lib_sba and lib_svt)..