Bundle Example: Define a Chemical Subgroup Selector

This example describes how to create a ChimeraX bundle that defines a chemical subgroup selector that can be used in command line target specifier for identifying atoms of interest.

The steps in implementing the bundle are:

  1. Create a bundle_info.xml containing information about the bundle,

  2. Create a Python package that interfaces with ChimeraX and implements the atom-selection functionality, and

  3. Install and test the bundle in ChimeraX.

The final step builds a Python wheel that ChimeraX uses to install the bundle. So if the bundle passes testing, it is immediately available for sharing with other users.

Source Code Organization

The source code for this example may be downloaded as a zip-format file containing a folder named tut_sel. Alternatively, one can start with an empty folder and create source files based on the samples below. The source folder may be arbitrarily named, as it is only used during installation; however, avoiding whitespace characters in the folder name bypasses the need to type quote characters in some steps.

Sample Files

The files in the tut_sel folder are:

  • tut_sel - bundle folder

    • bundle_info.xml - bundle information read by ChimeraX

    • src - source code to Python package for bundle

      • __init__.py - package initializer and interface to ChimeraX

      • selector.py - source code to define target selector

The file contents are shown below.

bundle_info.xml

bundle_info.xml is an eXtensible Markup Language format file whose tags are listed in Bundle Information XML Tags. While there are many tags defined, only a few are needed for bundles written completely in Python. The bundle_info.xml in this example is similar to the one from the Bundle Example: Add a Tool example with changes highlighted. For explanations of the unhighlighted sections, please see Bundle Example: Hello World, Bundle Example: Add a Command and Bundle Example: Add a Tool.

The BundleInfo, Synopsis and Description tags are changed to reflect the new bundle name and documentation (lines 8-10 and 17-24).

The ChimeraXClassifier tag on line 42 informs ChimeraX that there is one chemical subgroup selector named endres in the bundle. The last field is a short description for the selector. If endres appears in the target specification of a ChimeraX command, the bundle function associated with endres will be invoked to find the atoms of interest, e.g. the command sel endres will select the ending residues of chains.

src

src is the folder containing the source code for the Python package that implements the bundle functionality. The ChimeraX devel command, used for building and installing bundles, automatically includes all .py files in src as part of the bundle. (Additional files may also be included using bundle information tags such as DataFiles as shown in Bundle Example: Add a Tool.) The only required file in src is __init__.py. Other .py files are typically arranged to implement different types of functionality. For example, cmd.py is used for command-line commands; tool.py or gui.py for graphical interfaces; io.py for reading and saving files, etc.

src/__init__.py

As described in Bundle Example: Hello World, __init__.py contains the initialization code that defines the bundle_api object that ChimeraX needs in order to invoke bundle functionality. ChimeraX expects bundle_api class to be derived from chimerax.core.toolshed.BundleAPI with methods overridden for registering commands, tools, etc.

The register_selector() method is called by ChimeraX, once for each selector listed in bundle_info.xml, before the first time a command target specification is parsed. In this example, the method is called a single time with selector name endres.

The arguments to register_selector(), in bundle API version 1, are bi, a chimerax.core.toolshed.BundleInfo instance, si, a chimerax.core.toolshed.SelectorInfo instance, and logger, a chimerax.core.logger.Logger instance. The method is expected to call chimerax.core.commands.register_selector() to define a selector whose name is given by si.name. Note that there is no session argument because, like commands, selectors are session-independent; that is, once registered, a selector may be used in any session.

src/selector.py

selector.py defines both the callback function, _select_endres, that is invoked when endres is encountered in a target specification, as well as the function for registering select_endres with ChimeraX.

The code in selector.py is designed to register multiple selector callback functions using the same registration function. When register() is called from __init__.bundle_api.register_selector(), it looks up the callback function associated with the given selector name using the _selector_func dictionary, and registers it using chimerax.core.commands.register_selector.

A selector callback function is invoked with three arguments: session, a chimerax.core.session.Session instance, models, a list of chimerax.core.models.Model instances, and results, a chimerax.core.objects.Objects instance. The callback function is expected to process all the given models and add items of interest to results. Currently, the only items that can be added are instances of chimerax.core.models.Model, chimerax.atomic.Atom and chimerax.atomic.Bond. Typically, Model instances are only added explicitly for non-atomic models. More commonly, atoms (and bonds) are added using the add_atoms() method.

Building and Testing Bundles

To build a bundle, start ChimeraX and execute the command:

devel build PATH_TO_SOURCE_CODE_FOLDER

Python source code and other resource files are copied into a build sub-folder below the source code folder. C/C++ source files, if any, are compiled and also copied into the build folder. The files in build are then assembled into a Python wheel in the dist sub-folder. The file with the .whl extension in the dist folder is the ChimeraX bundle.

To test the bundle, execute the ChimeraX command:

devel install PATH_TO_SOURCE_CODE_FOLDER

This will build the bundle, if necessary, and install the bundle in ChimeraX. Bundle functionality should be available immediately.

To remove temporary files created while building the bundle, execute the ChimeraX command:

devel clean PATH_TO_SOURCE_CODE_FOLDER

Some files, such as the bundle itself, may still remain and need to be removed manually.

Building bundles as part of a batch process is straightforward, as these ChimeraX commands may be invoked directly by using commands such as:

ChimeraX --nogui --exit --cmd 'devel install PATH_TO_SOURCE_CODE_FOLDER exit true'

This example executes the devel install command without displaying a graphics window (--nogui) and exits immediately after installation (exit true). The initial --exit flag guarantees that ChimeraX will exit even if installation fails for some reason.

Distributing Bundles

With ChimeraX bundles being packaged as standard Python wheel-format files, they can be distributed as plain files and installed using the ChimeraX toolshed install command. Thus, electronic mail, web sites and file sharing services can all be used to distribute ChimeraX bundles.

Private distributions are most useful during bundle development, when circulation may be limited to testers. When bundles are ready for public release, they can be published on the ChimeraX Toolshed, which is designed to help developers by eliminating the need for custom distribution channels, and to aid users by providing a central repository where bundles with a variety of different functionality may be found.

Customizable information for each bundle on the toolshed includes its description, screen captures, authors, citation instructions and license terms. Automatically maintained information includes release history and download statistics.

To submit a bundle for publication on the toolshed, you must first sign in. Currently, only Google sign in is supported. Once signed in, use the Submit a Bundle link at the top of the page to initiate submission, and follow the instructions. The first time a bundle is submitted to the toolshed, it is held for inspection by the ChimeraX team, which may contact the authors for more information. Once approved, all subsequent submissions of new versions of the bundle are posted immediately on the site.

What’s Next