PointSuite v.0.7

	PointSuite is a set of programs to process macromolecular assemblies described by point and helical symmetry operations, with the goals of uniform annotation, archiving, and viewing.  In order to handle coordinates deposited in any orthogonal Cartesian frame, the relationships between the deposition, standard point and crystal frames are captured as frame transformations.  For example, the transformation required to move icosahedral virus structures from deposited position to the standard frame shown at left is calculated and recorded.  All point symmetries are fully handled; helical entries are handled only for non-crystal cases. Written/compiled by C. Lawson, with thanks to V.J. Reddy (TSRI) for sharing PDB2VIPER code (findframe);  Tom Goddard (UCSF) for Chimera scripts (runchimera.csh); Huanwang Yang (RCSB PDB) for importmats and cif-handling subroutines. Please look at this open access article that describes how Pointsuite was used to remediate virus structures in the PDB: Lawson CL, Dutta SD, Westbrook JD, Henrick K, Berman HM (2008)   Representation of viruses in the remediated PDB archive, Acta Cryst D, 874-882.
	DOWNLOAD:  pointsuite0.7.tgz (version date: January 15, 2013)
	Virus Processing Tutorial
	Installation Instructions     Documentation

INSTALL/COMPILE/CONFIGURE:
Type the following commands in the directory where you want to install the software.

• FINDFRAME
  • Description
  • Use
  • Algorithm
  • Output
• POINTMATS
  • Description
  • Use
  • Output
• MAKEASSEMBLY
  • Description
  • Use
  • Algorithm
  • Output

• Utilities
  • importmats
  • autoscripts
    
  • frac2orth
  • movecoords
  • multiplymats
    

PROGRAM FINDFRAME

Description

The program FINDFRAME calculates the transformation matrix that moves the asymmetric unit of a particle with point symmetry in an arbitrary (skew) frame into a defined position within a standard point frame.  The standard icosahedral frame is defined as having the 5-fold axis of the first pentamer centered on the vector (x=0,y=1, z=phi), where phi is the golden ratio (sqrt(5)+1)/2.  This convention is also employed by the VIPER database and the is proposed convention of Belnap et. al. for cryoEM maps.

FINDFRAME is an extension of the PDB2VIPER program from the VIPERdb (Shepherd, et al. (2006) Nucleic Acids Res, 34, D386-389) that incorporates the qikfit least-squares fitting routine from Bioplib (A.C.R. Martin, personal communication). Algorithm steps have been added to increase the precision of the calculated transformation matrix and to improve uniformity of coordinate placement relative to the standard icosahedron symmetry axes (see description below).  

Use

on the command line:

>findframe infile.pdb/cif

The input file is expected to have all needed transformation matrices to build the icosahedral or other point group particle AND coordinates for the asymmetric unit .  PDB matrices can be given either as REMARK 350 BIOMT or MTRIX records; in cif the matrices are given in _pdbx_struct_oper_list and must have type of "general operation", "point symmetry operation" or "helical symmetry operation".  One of the transformation matrices must be the identity element. Optional: a second file can be provided with BIOMT records; in this case the matrices in the 2nd file override any present in the first file.

Algorithm

modifications to PDB2VIPER (from V.J. Reddy) are in italics

1. The approximate center of mass ("reference atom") is calculated from Calpha and P atom positions.
2. The set of matrix translation vectors are averaged to find the center of the particle relative to the coordinate origin. The reference atom is translated by the negated particle center and transformed into a unit vector.
3. The rotation matrices are decomposed into angle-axis form. The angle identifies the fold of the rotation (e.g. 72 or 144 degrees for 5-fold, 120 degrees for 3-fold). The axis vector defines the symmetry orientation. 
   
4. The rotations are checked against their corresponding translation vectors to identify helical symmetry.  If helical symmetry is detected, then the program attempts to identify all of the helical parameters from the matrices, and will print this info to findframe.cif and will then exit (currently, program only handles cases with helical axis on z).
   
5. If no helical operations are detected, then point symmetry is assumed and the program analyses the matrices to deduce the correct symmetry.  The remainder of the algorithm description explains what happens for icosahedral symmetry, but essentially similar steps are taken for the other symmetries (circular,dihedral, tetrahedral, octahedral).
   
6. The five-fold, two-fold, and three-fold closest to the reference atom are identified.
   
7. The position of the reference atom unit vector relative to the 5-3 and 5-2 planes is evaluated.  If the reference atom is closer to the 5-3 plane, the icosahedral a.u. is classified as "3-fold centric" and the closest 3-fold is selected for alignment in the next step.  If the reference atom is closer to the 5-2 plane (typically true for T=3 viruses), the icosahedral a.u. is classified as "2-fold centric" and the 3-fold to the right of the 2-fold is selected for alignment.
8. The  input structure's 5-fold and 3-fold are aligned onto the standard icosahedral frame 5-fold (0, 1, phi) and 3-fold (phi/3, 0, (2*phi+1)/3) axes in two steps.  First, the rotation that superimposes the normal to the 5-3 plane of the deposited structure onto the normal to the 5-3 plane of the standard icosahedron 5-fold is found and applied.  Second, the rotation around the aligned normals that superimposes the pair of 5-fold axes is found and applied.  The initial estimate for the findframe matrix is based on these two rotation matrices and the translation vector determined in step 2.
9. Fitting/refinement: The input-supplied transformations are applied to the reference atom, and the resulting 60-atom constellation is transformed to the icosahedral frame by the initial findframe matrix.  A reference set is generated by applying icosahedral symmetry operations to the 1st  transformed atom.  The 60-atom constellation is fitted to the icosahedral reference set, yielding a correction matrix.  The final findframe matrix is generated by applying the correction matrix to the initial estimate.  This step is particularly helpful for cases where the input file-supplied matrices have either low precision or small random errors, as these errors tend to be averaged out.

Output

General info about the calculation is provided in the standard output.  On successful execution a cif file with symmetry and frame transformation info is  also output called *findframe.cif*. 

PROGRAM POINTMATS

Description

Generates sets of transformations corresponding to point or helical symmetry provided in the input cif file ( _pdbx_point_symmetry, _pdbx_helical_symmetry).   If the input cif contains a "transform to point frame" matrix with _pdbx_struct_oper_list.id labelled 'P' (or a "transform to helical frame" matrix is given with _pdbx_struct_oper_list.id labelled 'H'), the matrix set is transformed such that it can be applied to coordinates away from the standard frame, e.g., [P-inv][std mats][P].  Use pointmats to obtain simple matrix set output files for point/helical symmetry operations; use makeassembly if you need full assembly and asymmetric unit descriptions.

Use

Output

General info about the calculation is provided in the standard output; the matrices are written in CIF format to pointmats.cif and in BIOMT format to pointmats.biomt.  Point symmetry operations follow a standard order.  Helical symmetry operations are given as a continuous run centered around the identity element.

PROGRAM MAKEASSEMBLY

Description

The set of point symmetry operations corresponding to a crystal asymmetric unit is identified, given the following input: CIF file with unitcell, spacegroup, asym_id, entity_id records ,  cif with _pdbx_point _symmetry or _pdbx_helical_symmetry and _pdbx_struct_oper_list with frame transformations (P for "transform to point frame" ; H for "transform to helical frame"; X0, X1, etc. for "transform to crystal frame").  The program will analyse the structure for ncs only if at least one "transform to crystal frame" matrix is given (X0) (this will frequently be the identity matrix). FROM v.5.7 onward, makeassembly outputs asym_id lists instead of author_asym id list.

Use

Crystal frame transformations are optional (e.g., for EM structures):

>makeassembly uc_symtry_scale_.cif symm_transforms.cif

Algorithm

1. For each independent particle position n defined by Xn, the full standard set of matrices for the point symmetry given in 2ptmat , **to be applied to coordinates transformed by X0**,  are calculated as [Xn][2ptmat^-1][StdMats][2ptmat][X0^-1].
2. The crystal symmetry matrices in their fractional forms are transformed by the translation part of [Xn^-1].   This moves the origin of the crystal lattice to the particle center.   Crystal symmetry operators passing through the particle center are identified by lack of fractional translation components (full unit translations are reset to 0).
3. Each crystal symmetry rotation identified in step 2 is applied to each of the rotations calculated in step 1.  Symmetry-transformed rotations that are identical to untransformed rotations with lower index are eliminated from the list of ncs operations.

Output

General info about the calculation for each independent particle is provided in the standard output; an archival cif (assembly.cif) is generated, as well as biomt records for the full assembly (assembly.biomt).  For crystal structures a bare-bones crystal frame pdb file is created that can be input to sfcheck or packing programs (assembly_xframe.pdb), and ncs records are generated (assembly.ncs).

Utilities

importmats:

autoscripts:

frac2orth:  

movecoords: 

multiplymats:

Performs complex matrix multiplications given a list of matrices in cif format and a string defining the desired multiplication.
String can include numerical ranges and recursion.
examples:
"(1-2)(3,5,7-9)"  creates the set of matrices 1*3, 1*5, 1*7, 1*8, 1*9, 2*3, 2*5, 2*7, 2*8, 2*9
"(1)(2,(2)(2),(2)(2)(2))" creates the set of matrices 1*2, 1*2*2, 1*2*2*2

call with
>multiplymats <pointmats or assembly cif> <matrix multiplication string in double quotes>

example (1m4x):
multiplymats 1m4x.cif "(1-60)(61-88)"
number of matrices read: 89
Matrix multiplication expression to be parsed: (1-60)(61-88)

result:

1*61
1*62
1*63
1*64
1*65
1*66
1*67
1*68
1*69
1*70
1*71
...

60*85
60*86
60*87
60*88
Writing 1680 matrices to *mult.cif*
Writing 1680 matrices to *mult.biomt*

last modified 14 Jan 2013
C. Lawson