Bundle Example: Define Presets¶
This example describes how to create a ChimeraX bundle
that defines presets that will appear in the ChimeraX
Presets menu and be usable in the
The steps in implementing the bundle are:
bundle_info.xmlcontaining information about the bundle,
Create a Python package that interfaces with ChimeraX and implements the preset functionality, and
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_preset. 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.
The files in the
tut_preset folder are:
tut_preset- 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
presets.py- source code to define/execute presets
The file contents are shown below.
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.
1<!-- 2ChimeraX bundle names must start with "ChimeraX-" 3to avoid clashes with package names in pypi.python.org. 4When uploaded to the ChimeraX toolshed, the bundle 5will be displayed without the ChimeraX- prefix. 6--> 7 8<BundleInfo name="ChimeraX-TutorialPresets" 9 version="0.1" package="chimerax.tut_preset" 10 minSessionVersion="1" maxSessionVersion="1"> 11 12 <!-- Additional information about bundle source --> 13 <Author>UCSF RBVI</Author> 14 <Email>firstname.lastname@example.org</Email> 15 <URL>https://www.rbvi.ucsf.edu/chimerax/</URL> 16 17 <!-- Synopsis is a one-line description 18 Description is a full multi-line description --> 19 <Synopsis>Example for adding presets</Synopsis> 20 <Description>Example code for implementing ChimeraX bundle. 21 22Implements new preset "thin sticks", possibly useful for depicting small molecules. 23 </Description> 24 25 <!-- Categories is a list where this bundle should appear --> 26 <Categories> 27 <Category name="Depiction"/> 28 </Categories> 29 30 <!-- Dependencies on other ChimeraX/Python packages --> 31 <Dependencies> 32 <Dependency name="ChimeraX-Core" version="~=1.3"/> 33 <Dependency name="ChimeraX-PresetMgr" version="~=1.1"/> 34 </Dependencies> 35 36 <Providers manager="presets"> 37 <Provider category="small molecule" name="thin sticks" /> 38 <Provider category="small molecule" name="ball and stick" /> 39 </Providers> 40 41 <Classifiers> 42 <!-- Development Status should be compatible with bundle version number --> 43 <PythonClassifier>Development Status :: 3 - Alpha</PythonClassifier> 44 <PythonClassifier>License :: Freeware</PythonClassifier> 45 </Classifiers> 46 47</BundleInfo>
Category tags are
changed to reflect the new bundle name and documentation
(lines 8-10, 19-23, and 26-28).
Since the presets use functionality from the PresetMgr bundle, the
section has been changed to reflect that (lines 31-34).
Providers section on lines 36-39 informs ChimeraX that
this bundle defines two presets, named “thin sticks” and “ball and stick”,
and that their category is “small molcule” for organizing them in the Presets
menu and for the
category argument of the
More details about the
Providers section for presets can be found
in Defining Presets.
There are also deletions relative to previous examples. For instance,
there are no
ChimeraXClassifier tags since this
bundle does not provide a help page nor does it implement a tool.
src is the folder containing the source code for the
Python package that implements the bundle functionality.
devel command, used for building and
installing bundles, automatically includes all
src as part of the bundle. (Additional
files may also be included using bundle information tags
DataFiles as shown in Bundle Example: Add a Tool.)
The only required file in
.py files are typically arranged to implement
different types of functionality. For example,
is used for command-line commands;
for graphical interfaces;
io.py for reading and saving
As described in Bundle Example: Hello World,
the initialization code that defines the
that ChimeraX needs in order to invoke bundle functionality.
bundle_api class to be derived from
chimerax.core.toolshed.BundleAPI with methods
overridden for registering commands, tools, etc.
1# vim: set expandtab shiftwidth=4 softtabstop=4: 2 3from chimerax.core.toolshed import BundleAPI 4 5 6# Subclass from chimerax.core.toolshed.BundleAPI and 7# override the method for defining presets 8# inheriting all other methods from the base class. 9class _MyAPI(BundleAPI): 10 11 # Override method for defining presets 12 @staticmethod 13 def run_provider(session, name, mgr, **kw): 14 # 'session' is the current chimerax.core.session.Session object 15 # 'name' is the name of the preset to execute 16 # 'mgr' is the preset manager (a.k.a. session.presets) 17 # 'kw', the keyword dictionary, is empty 18 # 19 # Note that this method is called by all managers that your 20 # bundle declares providers for, so if your bundle has providers 21 # for multiple different managers the the 'mgr' argument will 22 # not always be the session.presets instance, and some managers 23 # may provide non-empty keyword dictionaries to providers. 24 25 from .presets import run_preset 26 run_preset(session, name, mgr) 27 28 29# Create the ``bundle_api`` object that ChimeraX expects. 30bundle_api = _MyAPI()
run_provider() method is called by the presets manager (
whenever one of the presets your bundle provides is requested, typically via the Presets
menu or the preset command.
The arguments to
session, the current
name, the name of the preset to execute,
PresetsManager instance (a.k.a.
kw, a keyword dictionary which is always empty in the case of presets.
Since all managers that your bundle offers
Providers for call this method,
other calls to this method may have different
kw argument values
(and the run_provider code would have to be more complex).
Since this example bundle only provides presets, it simply calls its
function to execute the requested preset, which is discussed below.
presets.py defines the function
that is invoked (from
run_provider(), above) when either of our presets are requested.
1# vim: set expandtab shiftwidth=4 softtabstop=4: 2 3def run_preset(session, name, mgr): 4 """Run requested preset.""" 5 6 # A preset needs to call mgr.execute(preset_info) to 7 # execute the preset, so that information about the 8 # preset's contents can be properly logged. The 9 # 'preset_info' argument can either be an executable 10 # Python function (that takes no arguments) or a 11 # string containing one or more ChimeraX commands. 12 # If there are multiple commands, the commands are typically 13 # separated with '; ', though in unusual cases (perhaps 14 # a very long series of commands) the commands could be 15 # newline separated -- in the latter case the newline- 16 # separated command string will be executed in individual 17 # calls to chimerax.core.commands.run() whereas '; '- 18 # separated commands will use only one call. 19 # 20 # Here we form a command string and use it with mgr.execute() 21 base_cmd = "size stickRadius 0.07 ballScale 0.18" 22 if name == "thin sticks": 23 style_cmd = "style stick" 24 elif name == "ball and stick": 25 style_cmd = "style ball" 26 else: 27 raise ValueError("No preset named '%s'" % name) 28 mgr.execute(base_cmd + '; ' + style_cmd) 29
run_preset() function needs to in turn call
the preset manager’s
method to actually execute the preset, so that the proper information
about the preset can be logged.
The single argument to
is either a Python function taking no arguments,
or a string containing a ChimeraX command.
The string is typically not just a single command, but multiple
commands separated by semi-colon (‘;’) characters,
which is the approach our
run_presets() function uses to
execute both a
(to make the sticks/balls thin/small) and a
to switch to stick or ball-and-stick style.
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
build sub-folder below the source code
folder. C/C++ source files, if any, are compiled and
also copied into the
The files in
build are then assembled into a
Python wheel in the
The file with the
.whl extension in the
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
flag guarantees that ChimeraX will exit even if installation
fails for some reason.
With ChimeraX bundles being packaged as standard Python
wheel-format files, they can be distributed as plain files
and installed using the ChimeraX
command. Thus, electronic mail, web sites and file
sharing services can all be used to distribute ChimeraX
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.
Bundle Example: Define a Chemical Subgroup Selector (previous topic)
Bundle Example: Define Presets (current topic)