This tutorial requires a DIALS 3 installation.
Please click here to go to the tutorial for DIALS 2.2.

Developer Tutorial

DIALS has been designed to be extensible. If you’ve got a great idea for a new integration algorithm, then, with a bit of work, you should be able to get it running within the DIALS framework. The following tutorial applies for both developers looking to put their algorithms within DIALS itself as well as for those adding algorithms in their own installation.

Spot Finding

Algorithms for computing the possible spot pixels used in spot finding should implement the following interface. An example can be found under “dials/extensions/kabsch_spotfinder_threshold_ext.py”.

class SpotFinderThresholdIface(interface.Interface):

  def __init__(self, params, imageset):
    pass

  @interface.abstractmethod
  def compute_threshold(self, image, mask):
    pass

The algorithm is configured through phil parameters and the imageset. The extension should also provide a compute_threshold method which takes an image and a mask and should return a flex.bool array of the same dimensions where True pixels are possible spot pixels and False pixels are background.

Profile Modelling

Warning

The profile modelling framework is not very mature and may be changed. I’ll try and keep the documentation up-to-date.

Algorithms for computing the profile model should implement the following interface. An example can be found under “dials/extensions/gaussian_rs_profile_model_ext.py”.

class ProfileModelCreatorIface(interface.Interface):

  @interface.abstractmethod
  def create(cls, params, experiments, reflections=None):
    pass

The profile algorithm should have a “create” method that is given phil parameters, experiments and (optionally) reflections. In the absence of reflections, the profile model should be constructable from phil parameters. When reflections are present, the create method should be able to construct the model from the input reflections and experiments.

The algorithm should return an instance of the ProfileModelList class (found in dials.algorithms.profile_model.model_list). The profile model list should contain a list of objects which implement the interface given in the dials.algorithms.profile_model.interface module and shown in brief below.

class ProfileModelIface(object):

  @interface.abstractmethod
  def predict_reflections(self, experiment, **kwargs):
    pass

  @interface.abstractmethod
  def compute_bbox(self, experiment, reflections, **kwargs):
    pass

  @interface.abstractmethod
  def compute_partiality(self, experiment, reflections, **kwargs):
    pass

  @interface.abstractmethod
  def compute_mask(self, experiment, reflections, **kwargs):
    pass

  @interface.abstractmethod
  def dump(self):
    pass

The profile model should have methods for predicting the reflections, computing the bounding box of reflections for a number of experiments, computing the partiality of reflections and computing the foreground/background mask. Of these the bounding box and mask methods are crucial for integration to work; partiality is currently only used in reporting and can be a placeholder.

The extension should have the ability to dump the profile model to phil parameters so that it can be input via a profile.phil file to, for example, re-run integration with the same profile parameters.

Indexing

FIXME

Refinement

FIXME

Integration

Centroid algorithms

Algorithms for computing the reflection centroid should implement the following interface. An example can be found under “dials/extensions/simple_centroid_ext.py”.

class CentroidIface(interface.Interface):

  def __init__(self, params, experiments):
    pass

  @interface.abstractmethod
  def compute_centroid(self, reflections):
    pass

The algorithm is configured through phil parameters and the list of experiments. The extension should also provide a compute_centroid method which takes a list of reflections with extracted shoebox data. The “shoebox” column of the reflection table should contain a list of dials.model.Shoebox types. The algorithm should fill the “xyzobs.px” column of the reflection table with the observed centroid positions.

Background algorithms

Algorithms for computing the reflection background should implement the following interface. An example can be found under “dials/extensions/simple_background_ext.py”.

class BackgroundIface(interface.Interface):

  def __init__(self, params, experiments):
    pass

  @interface.abstractmethod
  def compute_background(self, reflections):
    pass

The algorithm is configured through phil parameters and the list of experiments. The extension should also provide a compute_background method which takes a list of reflections with extracted shoebox data. The “shoebox” column of the reflection table should contain a list of dials.model.Shoebox types. The algorithm should fill the shoebox.background values and return the reflection list.

Deploying algorithms

Within the DIALS project

The DIALS project has the following layout.

dials
|
|-- algorithms
|   |
|   |-- integration
|       |
|       |-- sum
|           |
|           |-- ...
|
|-- interfaces
|   |
|   |-- ...
|
|-- extensions
    |
    |-- summation_integration_ext.py
    |
    |-- ...

Each algorithm should have its implementation encapsulated within a package in the appropriate place. For example, summation integration is implemented within the “dials.algorithms.integration.sum” package. The extension class, which inherits from the appropriate interface, and configures and calls this algorithm should then be placed in the “dials/extensions” folder with an appropriate name. For example, the summation integration extension is placed in the module “dials.extensions.summation_integration_ext”. Modules within the dials.extension package will be automatically loaded when searching for algorithms and any class within these modules that inherits from an interface will be registered for use within the DIALS command line programs.

Within external projects

If you have a project containing algorithms written for use within DIALS that is built using the cctbx build system, it is easy to make DIALS aware of your new algorithms.

A typical project layout is shown below.

my_project
|
|-- algorithms
|   |
|   |-- integration
|       |
|       |-- my_algorithm
|           |
|           |-- ...
|
|-- extensions
    |
    |-- my_algorithm_intensity_ext.py

If your project has this directory structure, with an intensity algorithm implementation within the “my_algorithm” directory and the extension class (inheriting from the IntensityIface class) in the “extension” directory you can make DIALS aware of your algorithm by adding the following code to the libtbx_refresh.py scripy in the top level of your project. This will add the extensions directory in your project to the list of directories searched when loading available algorithms.

# libtbx_refresh.py

from __future__ import division

try:
  from dials.framework import env
  import libtbx.load_env
  from os.path import join
  path = libtbx.env.dist_path("my_project")
  env.cache.add(join(path, "extensions"))
except Exception:
  pass

Running “libtbx.refresh” or “make reconf” will update your build. You can check that your algorithm has been found properly by using the “dials.show_extensions” command-line program which should show a list of extensions implementing each interface with your algorithm listed with the other available algorithms.