atomspec: atom specifier cli annotation and evaluation

The ‘atomspec’ module provides two classes:

  • AtomSpecArg : command line argument annotation class.
  • AtomSpec : atom specifier class.

AtomSpecArg is a cli type annotation and is used to describe an argument of a function that is registered with the cli module. When the registered function is called, the argument corresponding to the AtomSpecArg is an instance of AtomSpec, which contains a parsed version of the input atom specifier. The model elements (atoms, bonds, models, etc) that match an AtomSpec may be found by calling the ‘evaluate’ method which returns an instance of Objects. Each type of model elements may be accessed as an attribute of the Objects instance.

Selectors

A (name, function) pair may be registered as a ‘selector’ in an atom specifier. The selectors may either be global (e.g., chemical groups) or session-specific (e.g., active site). The selector name may appear wherever a model, residue or atom string does. The selector function is called when the atom specifier is evaluated and is expected to fill in an Objects instance.

Example

Here is an example of a function that may be registered with cli:

from chimerax.core.commands import cli, atomspec

def move(session, by, modelspec=None):
    if modelspec is None:
        modelspec = atomspec.everything(session)
    spec = modelspec.evaluate(session)
    import numpy
    by_vector = numpy.array(by)
    from chimerax.core.geometry import place
    translation = place.translation(by_vector)
    for m in spec.models:
        m.position = translation * m.position
move_desc = cli.CmdDesc(required=[("by", cli.Float3Arg)],
                        optional=[("modelspec", atomspec.AtomSpecArg)])

Notes

AtomSpecArg arguments should always be optional because not providing an atom specifier is the same as choosing all atoms.

class AtomSpec(operator, left_spec, right_spec)

Bases: object

AtomSpec instances store and evaluate atom specifiers.

An AtomSpec instance, returned by AtomSpecArg arguments in cli command functions, keeps track of an atom specifier. When evaluated, the model elements that match the specifier are returned.

evaluate(session, models=None, **kw)

Return results of evaluating atom specifier for given models.

Parameters:

session : chimerax.core.session.Session instance

The session in which to evaluate atom specifier.

models : list of chimerax.core.models.Model instances

Defaults to None, which uses all models in ‘session’.

**kw : keyword arguments

If ‘models’ is None, ‘kw’ is passed through to call to ‘session.models.list’ to generate the model list.

Returns:

Objects instance

Instance containing data (atoms, bonds, etc) that match this atom specifier.

class AtomSpecArg(name=None, url=None, html_name=None)

Bases: chimerax.core.commands.cli.Annotation

Command line type annotation for atom specifiers.

See cli documentation for details on type annotations.

classmethod parse(text, session)

Parse text and return an atomspec parse tree

all_objects(session)

Return Objects that matches everything.

deregister_selector(name)

Deregister a name as an atom specifier selector.

Parameters:

session : instance of chimerax.core.session.Session

Session in which the name may be used. If None, name is global.

name : str

Previously registered selector name.

Raises:

KeyError

If name is not registered.

everything(session)

Return AtomSpec that matches everything.

Parameters:

session : instance of chimerax.core.session.Session

Session in which the name may be used. If None, name is global.

Returns:

AtomSpec instance

An AtomSpec instance that matches everything in session.

get_selector(name)

Return function associated with registered selector name.

Parameters:

session : instance of chimerax.core.session.Session

Session in which the name may be used. If None, name is global.

name : str

Previously registered selector name.

Returns:

Callable object or None.

Callable object if name was registered; None, if not.

list_selectors(session)

Return a list of all registered selector names.

Parameters:

session : instance of chimerax.core.session.Session

Session in which the name may be used. If None, name is global.

Returns:

iterator yielding str

Iterator that yields registered selector names.

register_selector(name, func, logger)

Register a (name, func) pair as an atom specifier selector.

Parameters:

session : instance of chimerax.core.session.Session

Session in which the name may be used. If None, name is global.

name : str

Selector name, preferably without whitespace.

func : callable object

Selector evaluation function, called as ‘func(session, models, results)’ where ‘models’ are chimerax.core.models.Model instances and ‘results’ is an Objects instance.