SelectCoord and ReExpand

Description

During the refinement process, all atomic coordinates are independently shifted, even when either crystallographic or non-crystallographic symmetry is present. Constraints between shifts must be applied in order to retain the symmetry relationships between the copies of the protomer. Selectcoord makes the symmetry expansion, creating the symmetry equivalent copies of the protomer, and reexpand restores symmetry between atoms that have been shifted independently.

These programs run as part of refinement of macromolecules. Selectcoord also allows selecting the refining region of a macromolecule (zone or sphere - details in RSRef2000 GUI editor ), atoms within the margin (RSRef2000 GUI editor) which will be fixed during refinement, and residues from neighbouring symmetry related subunits which are close to the refining region and also will be fixed. Fixed atoms are contributing to the overall energy via interaction with the refining atoms.

Note that when Selectcoord and Reexpand run as part of the distributed refinement routines, only a subset of the functionality and parameters are available.

 

Function

selectcoord - selects subset of coordinates, sets-up book-keeping for symmetry equivalents.

reexpand - reimpose (non-crystallographic) symmetry equivalence.

 

Syntax

selectcoord (no command-line input/options). May be run from the cshell script as shown in the examples selectcoord_zone.* which may be found under subdirectory pscripts.

 

reexpand init-file protomer-file expanded-file

SelectCoord

The input is key-word directed. Comments, multi-line and redirected input are supported. Nested redirected input is given using @{file}, multiple line input using the "\" continuation character at the end of a line, and comments begin with "!". In the documentation, optional input is enclosed between [...], user-variable input should replace text enclosed within {...}. Input is free-format, but spaces are not allowed in strings.

Options specify coordinate files, symmetry operations to be applied and define a volume in which transformed coordinates must fall to be accepted. All the selection criteria must be satisfied for acceptance, but not all criteria need be invoked. Atoms are accepted from any symmetry-equivalent of any residues for which at least one atom is in the defined region, but atoms within a residue can be output with different weights and designations for refining, fixing etc.

Files

[Input [=] {string}] [Output [=] {string}]

Coordinate files: no defaults are provided

Files Input = input.pdb Output = expanded.pdb

Symmetry_operator

[Name [=] {string}] [Rotation [=] ({real})]

[Translation [=] ({real})]

This is repeated for each operator.

Name: a suffix appended to the chain name to designate the symmetry equivalent. The default is blank for the 1st operator, "A" for the 2nd, "B" for the 3rd etc. The name should not exceed 2 characters if chain identifiers are present in the coordinates, 4 characters if not.

Rotation: the nine elements of a 3 x 3 matrix in the order conventionally written: 3 elements of 1st row, then 2nd row, then 3rd row. The default is a unit matrix. The symmetry operators are acting on column vectors, in an orthonormal basis.

Translation: three elements of a translational matrix, applied after the rotation in the forward transformation, i.e.

Symmetry_operator Name = B Rotation = -0.50000 -0.80899 -0.30909 \

                                         0.80899 -0.30893 -0.50009 \

                                           0.30909 -0.50009 0.80893 \

                             Translation = 0.00000 0.00000 0.00000

Sphere

[Center [=] ({real})] [Radius [=] {real}] [Margin[=] {real}]

Center: the position of the sphere; default = (0.0,0.0,0.0).

Radius: the radius of the sphere; default is enormous.

Margin: add (fixed or low weight) residues with any atom within Margin of the volume border. Atoms in the Margin are fixed, but they are used in energy calculations. If Margin is greater than zero, the margin is outside the volume, else inside.

Sphere Center = -10.5 15.2 3.5 Radius = 20.0

Box

[X_limits [=] {real}] [Y_limits [=] {real}]

[Z_limits [=] {real}] [Margin[=] {real}]

-- The lower and upper limits for the box; defaults to an all-inclusive box.

Margin: add (fixed or low weight) residues with any atom within Margin of the volume border. Atoms in the Margin are fixed, but they are used in energy calculations. If Margin is greater than zero, the margin is outside the volume, else inside.

Box X_limits = 0.0 100.0 Z_limits = 80.0 120.0

Neighbors

[Contact [=] {real}] [Accuracy [=] {real}] [Start_Zone = {text} End_Zone = {text}]

Contact is the equivalent of Margin, but for a zone. If Contact is greater than 0, accept only those symmetry-equivalent residues within Contact of an atom from selected atoms in the first symmetry equivalent (default = 5.0). Accuracy is the maximum acceptable error in rasterizing the coordinates when determining neighbors (default = 1.5).

The selection of residues comes either from Sphere, or Box commands, or from the following:

Start_Zone, End_Zone: specify a zone. Residues are specified as [chain|]residue. The wild-card character "*" is supported.

Neighbors Contact = 5.7 Accuracy = 1.2 \

Start_zone = A|5 End_zone = A|25

Plane

Origin [=] ({real}) 2nd_point [=] ({real}) 3rd_point [=] ({real})

[Margin = {real}] ]

-- Only those atoms within the specified planes will be accepted. A plane is specified by three coplanar points and an optional translation along the normal.

Note that there are no defaults for the three position vectors, origin, 2nd_point and 3rd_point. An error will occur if values are not supplied. The order of the points in the plane is important. If a 4th point is defined to be outside the plane, then the vectors (2nd_point - origin), (3rd_point - origin) and (4th_point - origin) should make a right-handed set. If Margin (default = 0.0) is positive, the plane is moved outward along the normal, if negative inward. Plane must be called for each plane required.

Plane Origin = 0.0,0.0,0.0 2nd_point = 0.52547,0.0,0.85081 \

3rd_point = 0.0,-0.35674,0.9342 Margin = 5.0

 

Reexpand

Background

There are 2 differents ways to select a core refining zone and to add symmetry equivalent neighbors:

 

Around the core zone, a "neighbors" zone or Margin is defined, which contains all neighboring atoms within a threshold distance of any "core" atom, 5 for example. Atoms in the margin are not refined, but are used in energy calculations. A third "outer" zone is defined, containing all atoms in residues for which at least one atom is in the Margin. These latter atoms are not refined, but their presence is required since stereochemical restraints cannot be applied on partial residues.

When reexpansion occurs after a refinement cycle, symmetry is enforced for all atoms that belong to these 3 zones. Shifts are computed in two steps: first the shift of the atom in the protomer is computed by:

d = 1/(wi) . Sum i=0 n_s{wiRi-1di}

where di is the independent shift of the ith symmetry equivalent, related to the protomer atom by the symmetry operation Ri, i running through all symmetry equivalents of current atom presents in the 3 zones. Then the shift is applied to all copies. This former equation involves weights wi, which are 1 for the atoms belonging to the core zone, 0 for the outer zone atoms. This scheme is valid for all atoms and allows atoms which do not belong to the protomer to be shifted.

Input/Output Files

Either PDB or TNT ATOMC formats may be used. The file types are determined from the ".pdb" or " .cor" extensions, respectively.

 

selectcoord creates an equivalence file (extention *.eqf), containing all information pertinent to symmetry reexpansion. The name of the file is built from the output coordinates.

 

selectcoord's chain identifiers have names that are a subset of TNT's, i.e. 4 characters maximum. If selectcoord is used in context of CNS or X-PLOR chain identifiers should contain 1 character. Symmetry operations generate new chains with names that are extensions to the original chain name, when this extension scheme is possible. For example, a viral capsid is made of 4 different chains (1-4), which are copied by 8 symmetry operators (A-H), including the identity matrix. Application of the "A" operator on chain "1" will generate output chain 1_A. In most cases, the chain name should not exceed one character, 2 characters for the symmetry operator name, 1 character being reserved as separator. This can cause problems when converting back to a PDB file, because only one chain character is allowed in this format.

 

Limitations

Current version of selectcoord is supposed to be used for not very large regions of macromolecules. The program may stop if number of selected residues exceeds 600-1000 residues.

 

Credits

Program written by Eric Blanc, as a near-re-write of expcoord (M.S. Chapman).

 

Other Files:

 

${RSdir}/selectcoord ${RSdir}/reexpand - executables.

${RSdir}/source/ [selectcoord.c reexpand.c eqFile.c expandCoord.c mask.c oSymm.c] source codes.

${RSdir}/source /Makefile makefile for selectcoord and reexpand

${RSdir}/source/Lib/Libraries/ [libcrystal.a libtoken_io libcoords.a libmatrixvector.a] object libraries.

${RSdir}/source/Lib/ [Coordinates/* Crystal/* Matrixvector/* Token_io/*] directories with makefiles and sources of library routines.