ChimeraX-Clipper Python API

Note: this documentation is for the ChimeraX-specific portion of the ChimeraX-Clipper API. For most day-to-day work in ChimeraX you should only need to use the Commands. The vast majority of the lower-level API is a direct mapping of the underlying Clipper C++ API (with some modifications to support threading of performance-critical functions), and your first stop should be that documentation. When in doubt, the PyBind11 source code for the bindings themselves may be found here.

High-level Management

class chimerax.clipper.symmetry.SymmetryManager(session, model=None, mtzfile=None, spotlight_mode=True, spotlight_radius=12, hydrogens='polar', ignore_model_symmetry=False, set_lighting_to_simple=True, debug=False)

Handles crystallographic symmetry and maps for an atomic model.

delete()

Supported API. Delete this model.

draw_unit_cell_and_special_positions(offset=None)

Quick-and-dirty drawing mapping out the special positions (positions which map back to themselves by at least one non-unity symop) within one unit cell. A sphere will be drawn at each grid-point with non-unit multiplicity, and colour-coded according to multiplicity:

• 2-fold: white

• 3-fold: cyan

• 4-fold: yellow

• 6-fold: magenta

Ultimately it would be nice to replace this with something more elegant, that masks and scrolls continuously along with the model/ map visualisation.

Args:

• offset (1x3 numpy array, default = None):

  Optional (u,v,w) offset (in fractions of a unit cell axis)

draw_unit_cell_box(offset=None, cylinder_radius=0.05)

Draw a parallellepiped around one unit cell.

isolate_and_cover_selection(atoms, include_surrounding_residues=5, show_context=5, mask_radius=3, extra_padding=0, hide_surrounds=True, focus=True, include_hydrogens=False)

Expand the map(s) (if present) to cover a given atomic selection, then mask them to within a given distance of said atoms to reduce visual clutter. Adjust the atomic visualisation to show only the selected atoms, plus an optional surrounding buffer zone. Args:

• atoms (ChimeraX Atoms object):

  The main selection we’re interested in. The existing selection will be expanded to include the whole residue for every selected atom.

• include_surrounding_residues (float):

  Any residue with an atom coming within this radius of the primary selection (including symmetry atoms) will be added to the selection covered by the map. To cover only the primary selection, set this value to zero.

• show_context (float):

  Any residue within an atom coming within this radius of the previous two selections will be displayed, but will not be considered for the map masking calculation.

• mask_radius (float):

  Components of the map more than this distance from any eligible atom will be hidden.

• extra_padding (float):

  Optionally, further pad the volume by this distance. The extra volume will be hidden, but available for calculations.

• hide_surrounds (bool):

  If true, all residues outside the selection region will be hidden

• focus (bool): If true, the camera will be moved to focus on the selection (only the atoms in the master model will be considered)

• include_hydrogens (bool):

  Include hydrogens for the purposes of masking (this should almost never be necessary)

property map_mgr

Master manager handling all maps associated with this model.

property position

static restore_snapshot(session, data)

Create object using snapshot data.

property stepper

Provides methods for “stepping” back and forth through the model according to secondary structure. For example, each call to stepper.step_forward() (with default arguments) will return an atom selection corresponding to the next pair of defined secondary structure elements plus their flanking loops.

property structure

The atomic model managed by this symmetry manager.

swap_model(new_model, keep_old=False)

Swap out the current atomic model for a new one.

swap_model_from_file(filename, keep_old=False)

Load a model from file, and replace the current coordinates with the result.

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class chimerax.clipper.symmetry.Unit_Cell(atoms, cell, spacegroup, grid_sampling, padding=10)

Map Management

class chimerax.clipper.maps.MapMgr(crystal_manager, spotlight_radius=12, default_oversampling_rate=2.0, auto_add=True)

Top-level manager for all maps associated with a model.

cover_atoms(atoms, transforms=None, transform_indices=None, mask_radius=3, extra_padding=12)

Expand all maps to a region large enough to cover the atoms, plus mask_radius+extra_padding in every direction. If provided, transforms should be a Places object, and transform_indices a Numpy array giving the index of the Place to be used to transform the coordinates of each atom. Unlike cover_coords(), the mask will be periodically updated in response to atom movements.

cover_box(minmax)

Set the map box to fill a volume encompassed by the provided minimum and maximum xyz coordinates. Automatically turns off live scrolling.

cover_coords(coords, mask_radius=3, extra_padding=3)

Expand all maps to a region large enough to cover the coords, plus mask_radius+extra_padding in every direction.

delete()

Supported API. Delete this model.

property display

property last_covered_selection

Last set of coordinates covered by self.crystal_mgr.isolate_and_cover_selection(). Read-only.

property nxmapset

Handler for all real-space (non-crystallographic) maps associated with this model.

static restore_snapshot(session, data)

Create object using snapshot data.

property spotlight_center

Current (x,y,z) position of the centre of the “spotlight”. Read-only.

property spotlight_mode

Is live map scrolling turned on? Can only be changed via the master symmetry manager.

property spotlight_radius

Get/set the radius (in Angstroms) of the live map display sphere.

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

update_spotlight(trigger_name, new_center)

Update the position of the “spotlight” to surround the current centre of rotation. If this manager is not currently displayed, then filling the volumes with data around the new position will be deferred unless force is set to True.

property xmapsets

Sets of crystallographic maps associated with this model. Each XmapSet handles the set of maps derived from a single crystallographic dataset.

class chimerax.clipper.maps.XmapSet(manager, crystal_data=None, use_live_maps=True, use_static_maps=True, fsigf_name=None, bsharp_vals=None, exclude_free_reflections=False, fill_with_fcalc=False, exclude_missing_reflections=False, show_r_factors=True, auto_add_to_session=True)

Handles the organisation, visualisation and re-calculation (where applicable) of crystallographic maps. Two general types of maps are supported: “static” maps generated from pre-calculated amplitudes and phases (e.g. as generated by your favourite refinement package); and “live” maps calculated on-the-fly directly from atomic coordinates and experimentally observed amplitude data. Each XmapSet handles the data from one crystal. Furthermore, live map recalculation requires a single Fobs/sigFobs dataset - if more than one is found, the user will be asked to choose.

add_live_xmap(name, b_sharp=0, is_difference_map=False, exclude_missing_reflections=False, exclude_free_reflections=True, fill_with_fcalc=True, color=None, style=None, transparency=0.0, contour=None, display=True, auto_add_to_session=True)

Add a “live” crystallographic map, calculated from atomic positions and experimental x-ray reflection data. The map will be automatically recalculated in the background whenever changes are made to the atomic model.

add_static_xmap(dataset, is_difference_map=None, color=None, style=None, contour=None, display=True, auto_add_to_session=True, _session_restore=False)

Add a crystallographic map based on pre-calculated amplitudes and phases. This map will remain unchanged no matter what happens to the atomic model.

delete()

Supported API. Delete this model.

property name

static restore_snapshot(session, data)

Create object using snapshot data.

set_box_limits(minmax, force_fill=False)

Set the map box to fill a volume encompassed by the provided minimum and maximum grid coordinates. Automatically turns off live scrolling.

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class chimerax.clipper.maps.XmapHandler_Static(mapset, dataset, is_difference_map=False)

An XmapHandler_Static is in effect a resizable window into a periodic crystallographic map. The actual map data (a clipper Xmap object) is calculated via fast Fourier transform from a pre-calculated set of amplitudes and phases (e.g. as provided by a refinement package), and filled into the XmapHandler_Static.data array as needed. Mothods are provided for tracking and filling a box around the centre of rotation, and static display of a given region.

is_probably_fcalc_map()

Attempt to guess if a map loaded from a file is Fcalc (that is, simply calculated from the atomic coordinates and properties). All we can really go on here is some simple heuristics.

static restore_snapshot(session, data)

Create object using snapshot data.

property stats

Should return a 2-tuple of (mean, sigma) for the map

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class chimerax.clipper.maps.XmapHandler_Live(mapset, name, is_difference_map=False, session_restore=False)

An XmapHandler_Live is in effect a resizable window into a periodic crystallographic map. The actual map data (a clipper Xmap object) is recalculated as needed from the combination of atomic coordinates and measured diffraction data, and filled into the XmapHandler_Live.data array as needed. Mothods are provided for live recalculation, tracking and filling a box around the centre of rotation, and static display of a given region.

delete()

Supported API. Delete this model.

static restore_snapshot(session, data)

Create object using snapshot data.

property stats

Should return a 2-tuple of (mean, sigma) for the map

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class chimerax.clipper.maps.NXmapSet(manager, name)

Manages real-space maps. The most important difference between these and crystallographic maps is that there is no guarantee that two maps will have the same grid (i.e. voxel size and angles).

static restore_snapshot(session, data)

Create object using snapshot data.

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class chimerax.clipper.maps.NXmapHandler(mapset, volume=None, data=None, name=None, is_difference_map=False)

Real-space equivalent to XmapHandler_Static. Doesn’t actually use any of the clipper engine, but provides a unified interface.

static restore_snapshot(session, data)

Create object using snapshot data.

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

File I/O

chimerax.clipper.clipper_mtz.load_hkl_data()

Mouse Modes

class chimerax.clipper.mousemodes.RotateMouseMode(session)

mouse_double_click(event)

Supported API. Override this method to handle double clicks. Keep in mind that you will also receive the mouse_down and mouse_up events. If your mouse_up handler needs to behave differently depending on whether it is the second part of a double click, have it check the self.double_click boolean, and make sure to call this base method so that the boolean is set.

class chimerax.clipper.mousemodes.ClipPlaneAdjuster(session, zoom_mode)

wheel(event)

Supported API. Override this method to handle mouse wheel events.

class chimerax.clipper.mousemodes.Z_Shift_CofR(session)

mouse_down(event)

Supported API. Override this method to handle mouse down events. Derived methods can call this base class method to set mouse_down_position and last_mouse_position and properly handle double clicks.

mouse_drag(event)

Supported API. Override this method to handle mouse drag events.

mouse_up(event)

Supported API. Override this method to handle mouse down events. Derived methods can call this base class method to set mouse_down_position and last_mouse_position to None.

wheel(event)

Supported API. Override this method to handle mouse wheel events.

class chimerax.clipper.mousemodes.ZoomMouseMode(session)

property clip_multiplier

Multiplier applied to the camera-cofr distance to decide the position of the rear clipping plane. Clamped to the range (0..1)

class chimerax.clipper.mousemodes.SelectVolumeToContour(session, cooldown_time=0.15)

Designed to work together with ContourSelectedVolume. Each step of the mouse wheel increments through the currently loaded Volume objects, temporarily selecting the current pick to highlight it in the display. Stores a reference to the last selected volume, accessible via picked_volume. If the last selected volume has never been set or has been deleted, picked_volume defaults to the first Volume object in session.models.list().

wheel(event)

Select the next visible volume.

class chimerax.clipper.mousemodes.ContourSelectedVolume(session, selector, symmetrical=True, sensitivity=0.02)

wheel(event)

Supported API. Override this method to handle mouse wheel events.

class chimerax.clipper.mousemodes.ShiftToReferenceAsuMenuEntry

callback(session, event)

Perform the entry’s action.

criteria(session, event)

Return a boolean that indicates whether the menu should include this entry (usually based on the current contents of the selection).

dangerous = True

If a menu is hazardous to click accidentally, ‘dangerous’ should be True. Such entries will be organized at the bottom of the menu after a separator.

label(*args)

Returns the text of the menu entry.

Miscellaneous Utilities

chimerax.clipper.util.atom_list_from_sel(atom_list)

Takes a ChimeraX Atoms object, and creates a Clipper Atoms_list object from the relevant atom properties.

chimerax.clipper.util.guess_suitable_contour(volume, model, mask_radius=3, atom_radius_scale=0.5)

Find the contour level that would make the volume inside the contour for the region immediately surrounding the model approximately equal to the volume of the model’s atoms scaled by atom_radius_scale.

chimerax.clipper.util.set_to_default_cartoon(session, model=None)

Adjust the ribbon representation to provide information without getting in the way.