The Yup.scx program fits a molecular structure into a density map. The molecular model is represented by atoms connected in a Gaussian Network while the density map is represented by a cloud of attractive holes, each hole is fixed in space and attracts all the atoms that are within an adjustable distance. The fitting is accomplished by finding the minimum of the combined Gaussian Network and attractive hole energy functions. These functions, data preparation utilities, simulation methods and data analysis routines are implemented in the Emmental module of the YUP package. This module can be used directly provided one is ready to write Python scripts. The Yup.scx program packages a small number of the most important features in a simple-to-use command-line utility.	YUP.SCX INTRODUCTION TUTORIAL YUP.SCX YUP.VLAT EMMENTAL
The command syntax is: Yup.scx [ options ] PARTMAP SCXFILE This page is not a complete documentation of Yup.scx. Type the following command to learn about the minor options. You probably want to pipe the output of the command to a pager. Yup.scx --help This manual is for Yup.scx version 1.071023 or higher. Note that if you had used a version of Yup.scx prior to 1.070823, you need to recreate the SCX file for newer versions.
ARGUMENTS
Two arguments must always be provided. PARTMAP: The first argument is the name of a partition map file. A molecular model can be assembled from one PDB file or a number of PDB files. A partition map file describes how one or more PDB files are to be organized into a YUP Model object. The PDB files named in the partition map file must be accessible to Yup.scx. PARTMAP must be the name of a Python module, i.e., the first letter must be alphabetic and the rest of the name must be alphanumeric. The name extension must be .py but it is not necessary to give the extension in the command. A partition map file may also be created as part of a Yup.scx run. SCXFILE: The second argument is the name of a SCX format density file. The name extension is always .scx, therefore, it is not necessary to list the extension in the command. A SPIDER or XPLOR file may be converted to a SCX format file as part of a Yup.scx run.
OPTIONS
Some options are specified with a single letter, some by multi-letter words and most options can be specified with either method. A number of options are switches, they turn a feature on or off. INFORMATION: These options provide information about the program. Other options, if present, are ignored. Short Option Long Option -h --help --version CONTROL: These options control the operation of the program. The following pair of options are mutually exclusive: specify only one or the other, not both. Either option will produce some output, the verbose option provides just a bit more. Long Option Default Value --quiet no --verbose yes The following option specifies a prefix for the output PDB files. When a fitting is finished, an output PDB file is written for each input PDB file. The prefix allows the output to be distinguished from the input. Short Option Long Option Value Type Default Value -P --pdbprefix string SCX-
DENSITY MAP FILE: These options are used to convert an external format density map to a SCX format file named SCXFILE. If SCXFILE does not exist, then it must be created from one of two support formats. The following options specify the name of a SPIDER format file and the size of the voxels in Angstroms. Since the voxel size is not recorded in a SPIDER format file, both of these options must be specified. Short Option Long Option Value Type -s --spider string -v --voxel float
This option is used to convert an XPLOR (formatted only, cubic voxels only) file to a SCX format file. Short Option Long Option Value Type -x --xplor string Note that no more than one of -s (--spider) or -x (--xplor) may be specified.
The following options provide some control over how the data in the density source file will be processed. Only the voxels with densities above the threshold value are added to the SCX output file. The density values in the SPIDER file are normalized to numbers between 0 and 1, where 0.0 corresponds to the floor density and 1.0 to the ceiling density. Thus, the values specified for these options must be in the following ascending order: floor, threshold, ceiling.	Yup.scx calls the Spi2SCX() or Xpl2SCX() functions from the Yup.Models.Emmental.Prepare module to perform the data conversion. You can use the functions directly if you want to have more control over the conversion.
Short Option Long Option Value Type Default Value -t --threshold float minimum positive density -f --floor float minimum density or 1% below the threshold -c --ceiling float maximum density
PARTITION MAP FILE: A molecular model may be described by any number of PDB files. The following option is used to name a PDB file. Repeat for each PDB file that constitutes the model. Short Option Long Option Value Type -p --pdb string Note the lowercase p in the short option. The uppercase P is the short option for --pdbprefix (see above). The partition map file will be named PARTMAP.	Yup.scx calls the PDB2Map() function from the Yup.Models.Emmental.Prepare module to perform the data conversion. You can use the function directly if you want to have more control over this process.
MODEL CREATION: The following options can be used to modify the molecular model that is created. Short Option Long Option Value Type Default Value --hookeoption integer 3 --hookecut float 0 --hookeconst float 1 --addcore yes --nocore no -o --outratio float 4.0 -F --finalratio float 0.0 --cutratio float 1.5 --minimumscx float 300kB --updatenonbond integer 100 --nonbondcutoff float 1.75
The Gaussian Network is created from the initial structure, taking in any atom pairs that are within the cutoff distance. The cutoff distances are defined for pairs of atom types, e.g. it is 22.5Å between pairs of "P" atoms, 8Å between pairs of "CA" atoms and so on, with a default cutoff distance of 4Å. If hookecut is specified with a value greater than 0, then the cutoff distance will be taken as that value for all atom pairs regardless of atom type. If hookeconst is specified with a value other than exactly 1, all the force constants for the Gaussian Network term are scaled by the given factor. [Note the potential for abuse: scaling factors less than or equal to 0 are not rejected.] Force constants are assigned according to the specified value of hookeoption. With a value of 0, all bonds are assigned the same force constant. For option 1, the bonds along the backbones are assigned a separate value. For option 2, the bonds are assigned force constants according to the bond length. The default option 3 is like option 2, except that all bonds between non-adjacent residues are assigned a force constant designated for the longest bonds. The option "addcore" is the default, an additional term is added to the model. This is the Exclusion Soft Sphere term. Contact distances correspond to the sum of the van der Waals radii of the atoms that make up the pair. This term excludes pairs of atoms that are within a residue or are in adjacent residues that are linked in the Gaussian Network by a bond whose length is less than 1.1 of the contact distance.	From the Yup.Models.Emmental.FFA module, Yup.scx calls the NewModel() function to create the model and optionally, the AddSoftCore() function to add the soft core. The model makes use of the Hooke, SwissCheeseX terms and if a soft core is added, also the SoftSphereX term. Alternatively, one could represent the molecule with a standard molecular mechanics potential (such as AMBER) and combine it with the SwissCheeseX function. This will ensure that the fitted structure will be stereochemically correct. However, the step size used for molecular dynamics will have to be reduced to 1 or 2fs. This will require a bit of Python programming.
The outratio value is the initial value of the ratio between the outer and inner radii of the holes. The value of finalratio is the ratio at the end of the annealing process. The final ratio must be at least 1.0. If set to less than 1.0, then an internal default value of approximately 1.396 will be used. The default value is 0 which has a special meaning, the outer radius is kept at a constant value throughout the annealing procedure.  The value of cutratio is the ratio of the cutoff to the outer radii. A list of atom-hole pairs that are separated by less than the cutoff distance is created and used to calculate the SCX term. The minimumscx value is the magnitude of the deepest hole, the hole that corresponds to the SCX value of 1.0. The updatenonbond setting determines the update interval for the nonbond lists. This may have to be reduced (for more frequent updates) for very mobile systems. Alternatively, increase the nonbondcutoff ratio, which increases memory usage. FINDING THE OPTIMAL FIT: These options are used to control the molecular dynamics-based simulated annealing procedure that is used to optimize the fitting of the model into the density map. Long Option Value Type Default Value --steps float stepfactor x (rounded number of atoms) --stages float 0.01 x steps --init float steps The following options fine-tune the annealing process: Short Option Long Option Value Type Default Value -a --stepfactor float 0.5 -n --numtimes integer 1
The molecular dynamics simulation is carried out with a time step of 5fs. At the start of the process, the ratio of the outer to the inner radii in the SwissCheeseX term is set to the value of outratio. The model is heated from a very low temperature to 10K over 0.2 x init steps, then held at 10 K over 0.8 x init steps. The radius ratio is held fixed over these two initial stages. It is simpler to specify a value for stepfactor to affect the steps, stages and init settings. However, adjusting the last three settings allow finer control over the annealing procedure. The annealing takes place over as many steps as defined for steps. During this stage, the temperature is reduced from 10K to 1K. At the same time, the ratio of the outer to inner radii of the SwissCheeseX term is gradually reduced from a starting value of outratio to a final value of finalratio. The ratio is adjusted every stages steps, starting from outratio until at the end of the annealing process, the ratio is finalratio. This is essentially a radius annealing procedure (temperature remains low throughout the whole procedure). When the radius ratio is high, atoms are attracted to more and further holes. As the ratio is contracted, atoms are attracted to a smaller number of holes that are closer.	Yup.scx calls the AnnealMD() function from the Yup.Models.Emmental.Calculate module to perform the optimization. The modules also contains other optimization methods. Th 5 fs step size can accommodate models that are softer than the default. However, when setting hookconst below about 0.2, be prepared for failure. The Calculate module contains other functions that can perform the fitting, although AnnealMD() has proven to be the best method.
The numtimes option if greater than 0, selects one annealing cycles. This is followed by energy minimization. If numtimes is 0, only the final energy minimization will be carried out. If numtimes is specified as a negative number, only file conversions will take place. Simulated annealing is a good global optimizer but there is no guarantee that the global optimum will be found. An average SCX score is calculated before and after the fitting. In this calculation, the radius ratio is set to 1 and the SCX energy is divided by the minimum energy and the number of atoms. The score is therefore dimensionless.
Version 1.080601 introduces three new options. The chiralcut option [default value -1.8] imposes a chiral constraint on the network of bonds within the same chain whose lengths are shorter than the specified value. Whether they are correct or not, chiral centers are locked at the time the elastic network is formed. Thus, starting structures should be cleaned up before a Yup.scx run. A negative value turns this feature off. The chiralconst option [default value 1] other than 1, scales all the chiral force constant by the specified factor. The chiral options need tuning (that is why they are turned off by default). The preminimize option (default value 1000) carries out the specified number of steps of energy minimization before the simulated annealing. Specify a value of 0 to turn this feature off.
EXAMPLES
Each of the following three examples contain one command each: 1: Yup.scx \  -s rib.spi -v 2.3 \  -p rRNA.pdb --pdb=tRNA.pdb -p mRNA.pdb \  --steps=5000 \  -P 5K\- \  ribo01 riboA >& ribo.txt
This example shows the use of both long and short options, although one would usually stick to one style or the other. The model is constructed from three PDB source files: rRNA.pdb, tRNA.pdb and mRNA.pdb. A partition map file named ribo01.py is created, containing the atoms from the three PDB files. The SPIDER format density map file rib.spi, with voxels of 2.3Å, is converted to the SCX file riboA.scx. For the fitting procedure, the example overrides the number of steps (which would have been proportional to the total number of atoms in the model) to 5000. A value is specified for the pdbprefix option, so the results will be three files named 5K-rRNA.pdb, 5K-tRNA.pdb and 5K-mRNA.pdb.	Note the following UNIX practices: 1. the long command line is broken into several lines using the backslash continuation character; 2. a single letter option is separated by a space from its value, the assignment operator is used for long option; 3. the hyphen character at the end of the PDB prefix is protected by a backslash, we could also protect the entire string with double quotes; 4. the output is redirected from the terminal to a file ribo.txt.
2: Yup.scx --steps 10000 --pdbprefix=10K- ribo01 riboA In this example, a longer fitting procedure is tried, using the partition map file ribo01.py and the SCX file riboA.scx created in the previous example. Now the number of steps is doubled from the previous example and the resulting PDB files are prefixed with "10K-". 3: Yup.scx ribo01 riboA In the final example, a fitting is attempted using the previously created partition map and SCX files, with default settings. If this run is successful, we can expect to find three PDB result files: SCX-rRNA.pdb, SCX-tRNA.pdb and SCX-mRNA.pdb.