MxDC and MxLIVE: software for data acquisition, information management and remote access to macromolecular crystallography beamlines

An integrated computer software system for on-site and remote collection of macromolecular crystallography (MX) data at the Canadian Light Source (CLS) is described. The system consists of an integrated graphical user interface for data collection and beamline control [MX Data Collector (MxDC)] which provides experiment-focused control of beamline devices, and a laboratory information management system [MX Laboratory Information Virtual Environment (MxLIVE)] for managing sample and experiment information through a web browser. The system allows remote planning and transmission of sample and experiment parameters to the beamline through MxLIVE, on-site or remote data collection through MxDC guided by information from MxLIVE, and remote monitoring and download of experimental results through MxLIVE. The system is deployed and in use on both MX beamlines at the CLS which constitute the Canadian Macromolecular Crystallography Facility.

1. Introduction

The Canadian Macromolecular Crystallography Facility (CMCF) at the Canadian Light Source (CLS) synchrotron operates two beamlines for macromolecular crystallography (MX) (Cutler et al., 2007). Together, both beamlines serve an MX community of more than 50 research groups across Canada and the USA, contributing to a growing number of publications and Protein Data Bank depositions (Grochulski et al., 2011).

The success of any synchrotron MX facility is dependent on the availability of user-friendly software with intuitive user interfaces that are robust, easy to learn and provide tools for efficient acquisition of MX data by both experts and non-experts. This requirement is made even more important as an increasing number of inexperienced users with little or no crystallography training are seeking access to MX beamlines for their research. These factors have guided a number of efforts over the years to develop user-friendly software for MX beamlines (Kinder et al., 1996; Skinner & Sweet, 1998; McPhillips et al., 2002; Skinner et al., 2006; Okazaki et al., 2008; Gabadinho et al., 2010). Some of these efforts have also included development of laboratory information management systems with web-based graphical user interfaces for sample and experiment management (Beteva et al., 2006; Okazaki et al., 2008; González et al., 2008). The variety and diversity of beamline hardware and low-level control systems deployed on MX beamlines across facilities, and sometimes across MX beamlines within the same facility, has been an obstacle to standardization of the software used for MX data acquisition and experiment management. Although many of these software packages are freely available under open-source licenses, deployment outside their home institution has sometimes involved very intrusive modifications resulting in essentially new software development efforts (Stepanov et al., 2011).

Taking these challenges into consideration during the development of the CMCF facility, we have developed a modular software system which provides a standard set of features expected from an automated MX beamline (Fodje et al., 2010). The software system builds on the convergence of feature sets widely recognized by the MX community and includes a user-friendly easy-to-learn graphical user interface (GUI) for interactive data acquisition called MxDC, a web-based laboratory information management system for sample and experiment management known as MxLIVE, and an automated strategy determination and data processing pipeline called Auto­Process. MxDC and AutoProcess have been in use at the CMCF since 2007 and the full system integrating MxDC, MxLIVE and Auto­Process has been the standard mode of operating both beamlines at the CMCF since the beginning of 2011. This paper describes the implementation and features of MxDC and MxLIVE. AutoProcess will be described in a separate report.

2. MxDC  

2.1. Design and architecture

MxDC is modular and layered above the low-level beamline instrument control system. The first layer, also called the beamline control module (BCM), provides a functional abstraction of all hardware devices usually found at MX beamlines. Although the low-level control system at the CMCF is based on the Experimental Physics and Industrial Control System (EPICS) (Dalesio et al., 1994), the design is hardware- and control-system-independent, allowing a clear separation between hardware and device function. The BCM also includes sub-modules called `engines' which achieve specific experimental objectives by coordinating several devices. Examples of engines include the diffraction engine which collects diffraction frames and the spectroscopy engine which performs excitation and X-ray absorption near-edge structure (XANES) scans. The final layer consists of graphical widgets which allow interaction with devices and engines.

MxDC has been designed to be used primarily on Linux systems. It has been developed using the Python programming language (van Rossum, 2003), using the Zope Component Architecture (Weitershausen, 2007) for component interfaces and registration, the Twisted Framework (Fettig, 2005) for network connectivity, the Multicast DNS protocol (https://www.multicastdns.org/ ) for service discovery and dynamic configuration, and the GTK+ toolkit (Krause, 2007). The GObject system, part of the GTK+ toolkit, is used to achieve an event-driven architecture for low-level objects within the BCM.

2.2. The MxDC GUI

The MxDC GUI is an experiment-focused interface for controlling experiments. MxDC follows a layout which is conceptually similar to other MX data acquisition GUIs such as Blu-ICE (McPhillips et al., 2002) and MxCuBE (Gabadinho et al., 2010). The MxDC window contains a menu bar which provides short-cuts to commonly used commands, a main application area, and a status bar at the bottom of the window which displays the live status of the storage ring and beamline. The main application area contains a series of task-specific tabs labeled `Beamline Setup', `Samples', `Data Collection', `Screening', `Fluorescence Scans' and `Processing Results' (Fig. 1a). The MxDC GUI has been designed only for experiment control and does not contain any staff-only widgets for beamline commissioning or device calibration.

Figure 1 Screenshots of the MxDC GUI showing the application window with the `Beamline Setup' tab selected (a) and the `Samples' tab (b).

2.2.1. Beamline setup

The `Beamline Setup' tab (Fig. 1a) provides a single location where users can set up the beamline parameters in preparation for an experiment. The widgets in this tab include control buttons which allow users to restore and optimize the beam after a synchrotron refill, or reconfigure the sample environment for sample mounting, centering or data collection. Within this tab, users may also modify various beamline parameters such as energy, beam size, beam attenuation, beam-stop position, detector distance, detector 2θ angle, and goniometer rotations. A resolution predictor in the top-right corner shows the achievable resolution distribution on the detector surface for the current parameters. Video feeds from the beamline such as the sample microscope and hutch cameras are also available. In addition, beamline diagnostic checks for critical devices are displayed to give users a quick way of identifying problems. A log at the bottom shows detailed log messages and beamline events from MxDC.

2.2.2. Samples

The `Samples' tab (Fig. 1b) groups together all the functionality for managing samples. The first part of this functionality is provided by widgets in the top-left region which allow users to import information about their crystals into MxDC either from a previously filled spreadsheet or from MxLIVE (§4). Once imported, a list of available containers and crystals is displayed allowing users to associate containers with locations within the robotic automounter or select individual crystals for data collection by name. Currently supported container types are canes, universal containers (Uni-Puck) and SSRL cassettes (Cohen et al., 2002). An automounter widget allows users to select crystals for mounting based on their location within the automounter and provides controls for mounting, dismounting and washing crystals. This widget also shows the status of the automounter, the progress of current operations and the color-coded individual status of each sample location.

The sample viewer in the bottom-left region of the window displays a video feed from the sample microscope and allows users to align and center their samples in the X-ray beam. To assist in crystal centering and alignment, the sample viewer contains widgets for changing the zoom level, adjusting the sample lighting, and performing ±90° and 180° rotation increments around the gonio­meter spindle axes. Three methods of sample alignment are available. In `Click' centering, the user clicks a point on the video display and the point is moved to the position of the beam. The process is repeated twice, 90° apart, to completely center the crystal. The two remaining centering methods, `Loop' and `Crystal' centering, are fully automated and make use of the external XREC crystal centering software (Pothineni et al., 2006).

The final widget on the `Samples' tab is the cryojet widget which displays and controls the state of the sample cryogenic system. The widget provides control of the nozzle position, and annealing by stopping the flow of the cold nitrogen stream for a specified amount of time.

2.2.3. Data collection

The `Data Collection' tab allows users to perform the main function of MxDC, which is to collect diffraction image data (Fig. 2a). This tab is very similar in layout to the Blu-ICE `Collect Tab' (McPhillips et al., 2002) such that users accustomed to Blu-ICE will feel comfortable with MxDC. However, this tab deviates from Blu-ICE in subtle ways and includes features not available in Blu-ICE.

Figure 2 Screenshots of the MxDC GUI showing the `Data Collection' tab (a) and the `Screening' tab (b).

In MxDC, the run manager in the right-most region of the window includes an additional `Crystal' parameter and an optional `Skip' parameter but does not include a detector parameter. The `Crystal' parameter is not editable but is updated to reflect the name and MxLIVE ID number of the currently mounted crystal to which the dataset will be associated. The `Skip' parameter allows users to specify frames to be skipped during data collection. MxDC also replaces the two `End' parameters specifying the ending position for angle and frame number with two `Total' parameters which specify the total angle and number of frames to be collected, respectively. `Run 0', dedicated in Blu-ICE for single test frames, may be used in MxDC to collect any number of frames, and on subsequent runs a text field is available to allow comments to be added to the dataset. In the central region of the `Data Collection' tab, MxDC replaces the Blu-ICE exposure control and beam optimization functionality with a `Selected Crystal' area and a `Selected Strategy' area. The `Selected Crystal' area displays the crystal selected from the `Samples' tab along with a button to mount or dismount it. The `Selected Strategy' area is only visible when dataset parameters are available either from a MAD scan or from a strategy calculation (§2.2.6). In such cases, clicking the update button within a run will update the run parameters to match the selected strategy.

The left-most region of the window contains a full featured diffraction image viewer which displays diffraction frames as they are collected and also allows loading previously collected frames from disk. The image viewer allows panning, zooming, contrast and brightness adjustments, color-mapping of intensity values, intensity profile plots along user-drawn lines, distance measurements between peaks in reciprocal space, and displays the intensity and resolution of the diffraction image at the current mouse position. The viewer also highlights overloaded pixels and allows users to inspect image header parameters defined within the images.

2.2.4. Screening

The `Screening' tab allows users to perform automated screening of a series of samples (Fig. 2b). Samples are selected for automated screening from a list of all available crystals displayed at the top-left corner. Users can then select a sequence of screening actions and parameters to be performed on each selected crystal using the widgets in the top-right corner of the window. At the lower-right corner of the window, a list of all queued screening tasks is displayed and users can `start', `stop' or `pause' the screening process, as well as monitor its progress. A tabbed video widget with tabs for the sample viewer and the hutch viewer in the lower-left corner allows crystal centering and hutch inspection without leaving the screening tab. Diffraction images resulting from the screening sequence are displayed in the diffraction viewer tab next to the sample selection region.

2.2.5. Fluorescence scans

The `Fluorescence Scan' tab allows users to perform either X-ray excitation scans for identifying heavy atoms in their crystals, or X-ray fluorescence scans prior to single- or multi-wavelength anomalous diffraction (SAD/MAD) experiments (Fig. 3). A periodic table widget displaying the absorption edges available on the beamline allows users to easily select an edge for the scan, and a plot widget shows the resulting spectra. After a scan is complete, the data are automatically analysed. For MAD scans, the data are analysed using the program CHOOCH (Evans & Pettifer, 2001) to select three energies and their corresponding f ′ and f ′′ scattering factors. These results are displayed in the lower-left region of the window with controls allowing users to either transfer the parameters to the `Data Collection' tab, or create new runs with those parameters as defaults (Fig. 3a). For excitation scans, each spectrum is considered as a linear combination of the emission spectra of all excitable elements for the given energy. Emission lines and rates used for this purpose were obtained from the National Institute of Standards and Technology Atomic Spectra database (Ralchenko, 2005). A least-squares optimization method is then used to fit the contribution of each element and elements contributing more than one-half of a percent to the total spectrum are presented (Fig. 3b).

Figure 3 The `Fluorescence Scan' tab of MxDC showing results from MAD edge scans (a) and excitation scans (b). Users choose elements to annotate on the emission spectra, by selecting them in the `Results' section. The `Scan Parameters' section on the left allows users to modify the prefix, directory, edge or energy, exposure time and beam attenuation to be used during the scan.

2.2.6. Processing results

The `Processing Results' tab (Fig. 4) displays the results of all on-line data analysis requests, so that users may easily rank and select the best crystals for further data collection. Characterization or screening requests are automatically submitted during automated screening if the `Request Analysis' task is checked in the `Screening' tab. However, a list of all datasets collected during the current session is also displayed in the lower-left region of the window. Using the buttons below the list of datasets, users may submit new data processing or screening requests. In the top-left corner of the screen, a list of data processing requests is displayed and each entry is highlighted according to its status (e.g. in progress, failed, complete). A summary of the results is also shown for completed entries. The entries are organized into groups as defined in the crystal spreadsheet or MxLIVE, and ranked according to the data processing score. Double-clicking an entry in the result list loads a graphical formatted report into the panel on the right of the window. A button beneath the graphical report allows users to select the corresponding crystal for data collection in the `Data Collection' tab. The `active strategy' will also be updated with the calculated strategy if one is available.

Figure 4 The `Data Processing Results' tab of MxDC.

3. MxLIVE  

3.1. Design and architecture

The MxLIVE architecture consists of three components: a server module responsible for application logic functions, a relational database module for information storage, and a web-based user interface which is accessible securely over the World Wide Web using a standard web browser. Both the server module and the GUI have been developed using the Python-based Django web-application framework (Kaplan-Moss & Holovaty, 2007) and the information is stored in a MySQL database (DuBois, 2008). In order to provide a richer user-experience, the user interface combines HTML (Hyper Text Markup Language) with client-side scripts developed with the jQuery JavaScript library (Swedberg & Chaffer, 2010). Remote interaction with external software systems such as MxDC is implemented through JSON-RPC (JavaScript Object Notation Remote Procedure Call) interfaces. For added security all JSON-RPC remote procedure calls between MxLIVE and MxDC use an encrypted channel for communication in addition to API (Application Programming Interface) keys which are restricted to specific internet addresses.

3.2. Data model

MxLIVE uses a data model consisting of objects representing real laboratory objects commonly associated with synchrotron MX experiments, and relationships between these objects that are useful for their organization. Objects that can be managed include `crystals', crystallization `cocktails', `crystal forms', `experiment requests', crystal `containers', dry-shipping `dewars', `shipments', `datasets' and data `processing reports'. An MxLIVE `crystal', which represents a frozen crystal sample mounted on a pin and ready for diffraction, may be linked to a crystallization `cocktail' which contains information about the contents of the drop and/or a `crystal form' which contains crystal cell dimensions and space group. `Cocktails' and `crystal forms', once defined, can be assigned to any number of crystals. Crystals can be grouped into `experiment requests' which allow users to specify the type of experiment to perform on associated crystals (e.g. Native, MAD or SAD), the experimental strategy and the parameters to be used (e.g. photon energy, anomalous scatterer, resolution limit etc.). For shipping, crystals are organized into `containers' (e.g. canes, Uni-Pucks, SSRL cassettes) and placed in one or more dry-shipping `dewars' which are sent together as a `shipment' to the synchrotron facility.

3.3. Features

3.3.1. Data entry

Information about samples and their relationships can be input into the system in three ways: (i) users may create objects manually and associate them with related objects using tools available on the web-based interface; (ii) users may input sample information into a pre-formatted spreadsheet template using external spreadsheet software and then upload them using the MxLIVE web interface to automatically create corresponding objects and associations; (iii) external software such as MxDC may upload experimental results such as `datasets' and `processing reports' using JSON-RPC interfaces.

3.3.2. Managing objects

MxLIVE provides tools for creating objects, modifying their properties, associating them with each other, prioritizing, deleting or archiving them. The availability of these tools for a specific object within the interface depends on the type of object being managed and the state of the object in the experimental life-cycle. For example, newly created objects attain a `draft' status during which they can be modified and deleted. However, once they are sent as part of a shipment, the system prevents further modification or deletion.

To simplify the preparation of samples for shipment, MxLIVE also enables users to review shipments for shipping to ensure that all experiments have been properly defined and all crystals are accounted for. Shipping labels can be printed directly from the MxLIVE interface, and once the shipment has been physically sent to the synchrotron the user can notify beamline staff of the incoming shipment with the click of a button. MxLIVE also allows users to track the state of a shipment (e.g. `sent', `on-site', `returned').

3.4. Web interface

The MxLIVE web interface is made up of three regions stacked vertically (Fig. 5a). The navigation area, the top-most region of the browser page, includes information about the current user, links for logging out of the system, and a tabbed navigation menu which provides quick access to different parts of the interface. The navigation area is visible from every page on the interface. The tool area is located immediately below the navigation area and its content varies depending on the context. A descriptive title about the context of the page (e.g. the name and ID of the current crystal) is usually displayed on the left and links to all relevant tools are displayed on the right. To improve usability, descriptive icons are displayed next to these links. In some cases, extra tools are displayed in the tool area, such as a search form and links which can be used to filter lists of objects (list filters). The main content area, located immediately below the tool area, is where most of the content is displayed. The overall organization of content in MxLIVE is based on three distinct interface concepts: (i) the dashboard, (ii) object lists and (iii) object entries.

Figure 5 Screenshots of the MxLIVE web-based user interface showing the user dashboard (a) and an object list display for data processing reports (b).

3.4.1. MxLIVE dashboard

Users logging in to MxLIVE are immediately directed to the dashboard (Fig. 5a), a home page that aggregates project-level functionality in one place. Here users are presented with an overview of their account, a summary of the state of sent, on-site and returned shipments, a log of recent activity and links to documentation on how to use MxLIVE. The tool area of the dashboard provides tools which allow users to edit their profile, send feedback about MxLIVE to staff, download spreadsheet templates, and upload information from spreadsheets. The entire dashboard has been designed to be viewed at once on most standard monitors.

3.4.2. Object lists

An object list is a table of entries of a specific object type available within MxLIVE (Fig. 5b). Access to an object list is gained through the tabbed navigation bar, or by following a link from an individual object entry page. The object list enables users to view all entries in table format, search through them, sort and order them based on different fields (or columns) and filter them based on status, or other properties such as modification date. If more entries are available than can be displayed on a single page, the table will be paginated. It is also possible to add new entries from the object list page using the add tool which presents the user with a form specific to the object type of interest. In addition, the tool area contains search and list filter tools. Each row in the table represents a different individual object and clicking on it directs the browser to a detailed object entry page for the corresponding entry. A side bar to the right of the table displays a log of recent activity for objects on the list. The activity log contains hyperlinks which allow users to jump directly to the corresponding object of interest.

3.4.3. Object entries

An object entry is a page which presents detailed information about a single object of a specific type and its associations (Fig. 6). Object entry pages exist for crystals, experiments, containers, dewars, shipments, datasets and processing reports. `Cocktails' and `crystal forms' do not have individual object pages and are therefore managed solely from object lists. Object entries are highly customized for specific object types in order to capture the subtle differences in their associations and to optimize the presentation of information to the user. Furthermore, the object entries are dynamic and present different information based on the status of the object. In general, object entries present some or all of the following information in the main content area: (i) detailed information about the properties of the object; (ii) an activity log of the history of changes performed on the object; (iii) links for accessing individual entries for all associated objects; (iv) a list of objects of different types which can be associated with the current object through simple drag-and-drop. The tool area is dynamically populated with tools appropriate for the current object's status and type. Edit and delete tools are available for objects still in the draft state while the archive tool is only available for objects which have been returned from the synchrotron. The tool area on a shipment entry has a range of additional tools to perform tasks such as printing labels for the shipment, downloading a filled spreadsheet containing the shipment information, adding an additional item to be shipped, such as an external hard drive, or sending the shipment. In the case of datasets and processing reports, tools are provided to allow downloading the associated files (Fig. 6). Although users may download individual files at all times, the ability to download compressed archives of full datasets can be enabled by staff on a case-by-case basis. The tool area for every object entry also contains a help tool and a link to the object list for the relevant object type.

Figure 6 MxLIVE pages for inspecting individual experiment requests (a) and viewing dataset images (b).

3.4.4. Staff portal

The MxLIVE staff portal is a concurrent version of the user interface used only by beamline staff. It follows the same user-interface concepts described above, but complements it with staff-only features. For example, beamline staff can also manage `runlists' which represent a list of sample containers to be loaded into the automounter and analyzed in a single session on a given beamline. The `runlist' entry page allows staff to associate a container with a given location within the robotic automounter on a given beamline. Only one `runlist' may be loaded on each beamline at a time and a given container cannot be simultaneously mounted more than once.

The staff portal also enables staff to receive shipments by simply scanning in the barcode on the MxLIVE label that was attached to the dewar prior to shipping. Other features available only through the staff portal include the ability to read feedback messages from users and the ability to enable a specific dataset for download by users.

In contrast with the user portal where each user can only see or modify their information, the staff portal provides access to information which has been sent to the facility from all users. Draft information and other information which has not been explicitly sent are not visible to staff. Except for changes in object status during the normal course of an experiment and the ability to add staff comments to user objects, all other user information displayed in the staff portal is read-only.

4. Integration with MxDC

MxDC can act as a consumer of information produced by MxLIVE. An active MxDC session can request a list of all sample containers available in MxLIVE for the currently logged-in user. The returned information will include only samples belonging to a shipment which has been received on-site, and will include information from any active `runlists' which have been defined by staff for the given sample containers. The information is displayed in both the `Samples' and the `Screening' tabs of MxDC. MxDC also keeps track of the groupings of crystals in experimental requests and uses this information to group data processing reports for easy comparison within the `Processing Results' tab. In addition, MxDC uses suggested data collection parameters defined within experiment requests as defaults when defining a data collection run for any crystals which are part of the experiment request.

MxDC also acts as a producer of information to be stored in MxLIVE. In this role, it uploads information about collected datasets and data processing reports to MxLIVE. Datasets are associated with the crystal on which they were collected, and data processing results are associated with the corresponding datasets. Newly uploaded datasets and reports are highlighted on the users' dashboard and users can immediately inspect the frames or navigate to its associated crystal or data processing report.

5. Authentication and remote access

Unlike Blu-ICE and MxCUBE which support multiple concurrent sessions, only one session of MxDC is allowed to run on a given beamline at a time. Users attempting to start another instance of MxDC are presented with an error message and detailed information about the active session such as hostname, user name and the date and time the session started. Another way in which MxDC differs from both Blu-ICE and MxCUBE is the fact that MxDC does not implement a separate authentication process for individual sessions. Instead, access is obtained through a single step system log-on used to access beamline workstations. The integration of MxDC and MxLIVE requires that MxLIVE use the same user authentication database as the Linux system on which MxDC runs. At the CMCF beamlines, a single LDAP (Lightweight Directory Access Protocol) server is used for this purpose.

Remote data collection is achieved by using the NoMachine NX remote desktop virtualization software system (https://www.nomachine.com/ ) that has already been used successfully at other facilities (Gabadinho et al., 2008). Remote users connect securely to a virtual beamline workstation on which they may run MxDC, perform their experiments and process their data.

6. Conclusion

MxDC is a mature and easy-to-use software system for data acquisition at MX beamlines. Combined with MxLIVE, a laboratory information management system, and AutoProcess, an automated data processing pipeline, we have achieved a complete integration of information tracking from sample preparation at users' home laboratories through shipping of samples to the beamline, experiment management and monitoring during data acquisition and, finally, inspection and download of experimental data and results. The system is deployed and is used actively at both CMCF beamlines at the Canadian Light Source by more than 50 research groups from across Canada and the USA. It is also used by beamline staff performing the `Mail-In' service crystallography.

Although the system is currently deployed only at the Canadian Light Source, MxDC and MxLIVE have been designed to be deployable at any MX facility. The MxDC BCM was designed to be easily extended to support different control systems and device types. To facilitate this, a complete simulated beamline which permits MxDC to run on simulated devices is included as an example. The software is available on demand from the authors.