Introduction Data Preparation The Emmental model requires the initial coordinates of a molecular model with the atoms organized into a hierarchy, and a density map in an internal format. The Yup.Models.Emmental.Prepare module contains four functions. PDB2Map The coordinates of the molecular model must be provided in one or more PDB files. This function will create a data structure that describes a default hierarchy of atoms in which Chains enclose Residues, and Residues enclose Atoms. The data structure is defined in a Python program which is why the second argument must be a string that can be used as a Python module name. It is safest to use an alphabetic first character and restricting the rest of the name to contain only digits and the letters of the alphabet. The file name extension for Python program files is ".py" and it is not necessary to include the extension when specifying this file. The third argument allows the selection of an all-atom or a coarse-grained model. The coarse-grained model uses the "P" atoms to represent the entire nucleotide while amino acids are represented by a pseudo-atom positioned at the mass center of each residue. Other coarse-grained representations (e.g. representing amino acids by their alpha carbons) are possible by using the makepartmap() function directly from the Yup.Models.Null.PDBPartMap module. The last argument specifies how the molecules are to be divided into rigid units. The default value is to define each PDB chain as a rigid unit. The symbols are defined in Yup.Models.Null.PDBPartMap. Other values are RIGID_NONE: do not define rigid units, RIGID_RESIDUE: define each residue as a rigid unit, RIGID_FILE: define each file as a rigid unit and RIGID_TRIPLET: group three more residues into interleaving rigid units. Argument Type Preset Value Description pdbfiles string or a tuple of strings names of one or more PDB files partmap string name of a partition map file, must be aceptable as a Python module name option integer: 0 and 1 only 1 0: generate an all-atom model; 1: coarse-grained model rigidity integer: the symbols RIGID_* from Yup.Models.Null.PDBPartMap RIGID_CHAIN divide the molecules into rigid units at this level The PDB files must be left in place for the simulations since the Partition Map contains only references to the atoms but not the coordinates. The Partition Map file can be modified to change the atom hierarchy. In fact one fitting function AnnealMC(), requires the model to be divided into a number of rigid units and the fitting will maintain the rigidity of these units throughout the fitting process. (PDB2Map() will start things off by designating each Chain as a rigid unit.) The rigid units can be specified by (very carefully) editing the Partition Map file. Note that the declaration of rigid units and the details of the atom hierarchy have no effect on the other fitting methods. In other words, the Partition Map file is necessary to accommodate one fitting method but is superfluous (other than maintaining a list of PDB files) for all the other methods. The Emmental module can accept density map data in only one internal format: SCX. This file contains data from voxels that have densities above a threshold value and the data are normalized on a 0 to 1 scale. Density data can be read from files in one of two supported formats and then converted to the SCX format using the following two functions. Spi2SCX One of the supported file format is SPIDER. Argument Type Preset Value Description spifile string name of a SPIDER-format density map (volume data) file voxelsize float width of a voxel in Angstroms, assumed to be cubical prefix string basename of the output SCX file suffix string ".scx" file name extension for the output SCX file floor float or None None the density value that corresponds to 0.0 on the SCX scale threshold float or None None voxels with densities below this value are ignored ceiling float or None None the density value that corrresponds to 1.0 on the SCX scale Please see the documentation for the SwissCheese utility for details of the last three arguments. Xpl2SCX The other supported format is XPLOR but only the formatted variant and only files with cubical voxels. Support for additional formats can be easily added. Argument Type Preset Value Description xplfile string name of an XPLOR-format electron density map file prefix string basename of the output SCX file suffix string ".scx" file name extension for the output SCX file floor float or None None the density value that corresponds to 0.0 on the SCX scale threshold float or None None voxels with densities below this value are ignored ceiling float or None None the density value that corrresponds to 1.0 on the SCX scale Please see the documentation for the SwissCheese utility for details of the last three arguments. CheckSpi This function can be used to check a SPIDER-format file. One use of this function is to verify that such files are being read properly in YUP. Argument Type Preset Value Description filename string name of a SPIDER-format density map (volume data) file histogram integer 25 number of bins in the histogram floor float or None None the density value that correspods to 0.0 on the SCX scale threshold float or None None voxels with densities below this value are ignored ceiling float or None None the density value that corresponds to 1.0 on the SCX scale. Another use for this utility is to examine the effects of the last three settings. You can examine the effects of various settings (particularly to see if your threshold setting will be honored) before applying them to the Spi2SCX() conversion function. EXAMPLES In the following, all the commands are typed into a Python interpreter. from Yup.Models.Emmental.Prepare import PDB2Map PDB2Map( 'tRNA.pdb', 'T0001' ) In the above example, from one PDB file "tRNA.pdb", a partition map file is created named "T0001.py", for a coarse-grained model (last argument is not specified and is therefore at the default value of 1) from Yup.Models.Emmental.Prepare import PDB2Map PDB2Map( ( 'tRNA.pdb', 'mRNA.pdb', 'rRNA.pdb' ), 'T0002', 0 ) In this example, the model is constructed out of three PDB files: "tRNA.pdb", "mRNA.pdb", "rRNA.pdb" and an all-atom model is created. PDB2Map() makes use of the makepartmap() function in the Yup.Tools.PDBPartMap module. Spi2SCX() and Xpl2SCX() make use of the Density class in the Yup.Tools.SwissCheese module. CheckSpi() makes use of the checkspider() function in the Yup.Tools.SwissCheese module. Force Field Assembly Calculate Analyze Utilities