SymExp: Symmetry expansion of molecular coordinates¶

Section author: Michael S. Chapman <chapmami@ohsu.edu>

Authors:

Michael S. Chapman <chapmami@ohsu.edu>,

Oregon Health & Science University

Version:

0.5, March 23, 2016

Usage:

python -u -m symexp.py [options] <input-pdb-file>

Synopsis¶

Expands coordinates by both molecular (non-crystallographic) and crystallographic (lattice) symmetry:

Finds atoms in the neighborhood of a point (sphere) or a molecular fragment (neighbor).

Optionally completes structures of neighboring atoms into residues or chains.

Does not attempt to fill a crystal cell or asymmetric unit.

For efficient analysis of interactions.

Symexp is the stand-alone front end for symmetry.py which is called by several scripts, for which this serves as supplementary documentation.

Sources of Documentation¶

All of the following should be referenced:

Program options

Brief explanations of the arguments for stand-alone runs are given with: symexp -h, further information below.

Commands

Within the program (SymExp> prompt), available commands are listed with help -a; help about command is provided by help command, and for all commands by help -rl. The help text is reproduced later in this document.

Examples

The scripts directory in the installation contains run_symexp.sh, that exemplifies two types of usage using coordinate files from the installation test directories.

Details, API

Details are encoded within docstrings that are accessible to programmers using Interactive Development Environments (IDEs). They are also compiled with sphinx into html files, linked from the module index on the home page. This is the searchable, cross-linked (API) reference documentation that will explain the meaning of parameters, performance of different functions etc..

The documentation is accessed from (index.html) on-line or in the distribution directory doc/html. (Additional formats can be generated with sphinx.)

Command-line options¶

The most up-to-date documentation is generated from python -u -m symexp -h:

Input files¶

local_symmetry¶

A file that will be evaluated (in python) as a tuple of operators. Each operator is a tuple of name (str), rotation (tuple) and translation (tuple of 3 Angstrom floats). The rotation is the matrix specified as three row-tuples, each as a tuple of 3 floats). The unit operator is implied and therefore optional. The example below specifies two additional symmetry equivalents:

(   ("p",    (
        (0.500000,       0.809000,      -0.309000),
        (-0.809000,       0.309000,      -0.500000),
        (-0.309000,       0.500000,       0.809000)
            ),
        (0.000000,       0.000000,       0.000000)),
    ("e",    (
        (0.309000,      -0.500000,       0.809000),
        (0.500000,       0.809000,       0.309000),
        (-0.809000,       0.309000,       0.500000)
            ),
       (0.000000,       0.000000,       0.000000)))

Command interpreter¶

The command interpreter is available for programs in stand-alone mode, but generally not when called from / embedded in another package.

Syntax:¶

Commands are entered at the prompt in a unix-shell style:

command [option(s)] [positional argument(s)]
where options can be provided as -x [value] (x is a single letter), or --option[=value] in “two-dash” long form.
Various standard short-cuts are pre-defined, and any command can be shortened to a unique abbreviation. Note that the abbreviation given in the help is not always long enough to be unique (a bug inherited from cmd2).
Comments can be included with “#”, with text to the end-of-line then ignored.

Shell:¶

The cmd2 shell-like interface is inherited, offering history, command editing and redirects. Redirects can be awkward, because of the conflict with logical operators (<, |, >) used in selections (which therefore need to be quoted).

Hierachical structure:¶

Sub-commands are only available after entering the command. Higher-level commands are generally not available in sub-commands. The exceptions are general utility commands such as shell, shortcuts & set. Help, by default, is specific to the command level, but this behaviour can be changed with the --all (-a) & --recursive (-r}) options. Note that load (“@”) & related commands do not transcend different command levels.

Just-in-time calculation & pre-requisites:¶

A number of efficiencies are possible by pre-calculating and repeatedly using objects. Rather than pre-calculating at startup all objects that might be needed, the program attempts to calculate the minimal needed, just-in-time. For the most part, the pre-requisites are figured out and tasks are executed when needed using pre-assigned (or default) parameters. One exception is that any command with a “parameterize” pre-requisite will issue an error message if not already performed (mind-reading is not an option!).

The order that commands are entered is sometimes important, particularly when the embedded python interpreter is invoked with “py” (see below). Given the flexibility of the “py” command, there is no way to figure out the pre-requisites. Users should be especially attentive to AttributeErrors that might indicate an unmet pre-requisite dependence.

Error recovery:¶

Inherited from cmd2, exceptions are captured at the Command level, printing at least an error message, but without aborting the whole program. On interactive use, this conveniently often offers a second chance. If run as a script, users should search the output for “Error”, lest one has scrolled by. The default is a terse error message, but this can be changed to a full traceback using “set debug True” (still does not abort).

Selected commands and implementation-specific limitations.¶

@FILE or load FILE:¶

Used to run commands from an external file. The limitation is that commands cannot descent/ascend through nested sub-commands. Thus, for example, commands within parameterize would have to be given separately. The same limitation applies to variants _relative_load (@@).

Command list¶

The most up-to-date documentation is generated from python -u -m symexp /dev/null /dev/null help exit:

Symexp v0.5.0, 03/12/15 (Command: /home/chapman/Devel/RSRef/FTatom/src/symexp.py) [?1034h Symexp> help

Documented commands (type help <topic>):¶

_load	ed	hi	li	neighbors	pdbout	run	shell	sphere
_relative_load	edit	history	list	parrot	py	save	shortcuts	test
cmdenvironment	help	l	load	pause	r	set	show

Undocumented commands:¶

EOF eof exit q quit

Symexp> exit

Command Help¶

(See also Program control / utilities, below.) The most up-to-date documentation is generated from python -u -m symexp then help -rl:

neighbors¶

Identify neighbors within distance of (selected) atoms.

Usage: neighbors [options] arg

Options:

`-h, --help`	show this help message and exit
`-d FLOAT, --distance=FLOAT`
	Searches for neighbors within distance of any atom (default: 3.5 A).

pdbout¶

Write coordinates (symmetry expansion as per command-line arguments).

Usage: pdbout [options] [Header inserted into top of PDB file]

Options:

`-h, --help`	show this help message and exit
`-o FILE, --file=FILE`
	Output file name (required argument).
`-a, --anisotropic`
	Output anisotropic U, riding w/ coordinates from input PDB.

sphere¶

Find atoms & symmetry equivalents near given point.

Usage: sphere [options] displacement (A)

Options:

`-h, --help`	show this help message and exit
`-c xyz-components, --center=xyz-components`
	Center of sphere (default: [0.0, 0.0, 0.0]).
`-r FLOAT, --radius=FLOAT`
	Radius (default: 10.0)

Program control / utilities¶

(Available from top-level and all sub-menus.) The most up-to-date documentation is generated from python -u -m symexp then help -rl:

_load¶

Runs script of command(s) from a file or URL.

_relative_load¶

Runs commands in script at file or URL; if this is called from within an already-running script, the filename will be interpreted relative to the already-running script’s directory.

cmdenvironment¶

Summary report of interactive parameters.

edit | ed¶

ed: edit most recent command in text editor

ed [N]: edit numbered command from history ed [filename]: edit specified file name

commands are run after editor is closed. “set edit (program-name)” or set EDITOR environment variable to control which editing program is used.

help¶

Document command or list available commands.

Usage: help [options] [command]

Options:

`-h, --help`	show this help message and exit
`-a, --all`	Include commands inherited from higher levels. (Combining -a -r will be excessively repetitious.)
`-l, --long`	Fully document all commands.
`-r, --recursive`
	Descend through nested command sets.

history | hi¶

history [arg]: lists past commands issued

no arg: list all

arg is integer: list one history item, by index

arg is string: string search

arg is /enclosed in forward-slashes/: regular expression search

Usage: history [options] (limit on which commands to include)

Options:

`-h, --help`	show this help message and exit
`-s, --script`	Script format; no separation lines

list | l | li¶

list [arg]: lists last command issued

no arg -> list most recent command arg is integer -> list one history item, by index a..b, a:b, a:, ..b -> list spans from a (or start) to b (or end) arg is string -> list all commands matching string search arg is /enclosed in forward-slashes/ -> regular expression search

load | l¶

Runs script of command(s) from a file or URL.

parrot¶

parrot [T[rue]|F[alse]|Y[es]|N[o]]: toggle or set command echoing (for log file).

pause¶

Displays the specified text then waits for the user to press RETURN.

py¶

py <command>: Executes a Python command. py: Enters interactive Python mode. End with Ctrl-D (Unix) / Ctrl-Z (Windows), quit(), ‘exit()`. Non-python commands can be issued with cmd("your command"). Run python code from external files with run("filename.py")

run | r¶

run [arg]: re-runs an earlier command

no arg -> run most recent command arg is integer -> run one history item, by index arg is string -> run most recent command by string search arg is /enclosed in forward-slashes/ -> run most recent by regex

save¶

save [N] [filename.ext]

Saves command from history to file.

N => Number of command (from history), or *;

most recent command if omitted

set¶

Sets named Cmd parameter or lists all; unambiguous abbreviations OK.

shell¶

execute a command as if at the OS prompt.

shortcuts¶

Lists single-key shortcuts available.

show¶

Shows value of a parameter.

Usage: show [options] arg

Options:

`-h, --help`	show this help message and exit
`-l, --long`	describe function of parameter

Python Interpreter for advanced functionality¶

Rarely or never needed, parameters that are not accessible through options or commands can be changed through the embedded python interpreter that is invoked with the command py command. See RSRef or Superpose for details.

Credits¶

The underlying algorithms were coded in fortran by Michael S. Chapman in 1991. After several revisions by the same author, expcoord was given a major overhall as it was refactored into C++ in 1995 by Eric Blanc, in the Chapman lab, who introduced various efficiencies. The methods were refactored by Michael into python in 2011, with changes in library dependence, user-interface, inclusion of space group symmetry as well as non-crystallographic (molecular) and dual support for stand-alone and embedded use.

Changed in version 0.5.0: 2/18/15, converted to reStructuredText from Epydoc.

Changed in version 0.1: 12/10/10 Start.