MXCuBE3 is the user interface for macromolecular crystallography experiments used at BioMAX. MXCuBe3 is the result of an international collaboration to create an intuitive and user friendly application. This page describes how to use the MXCuBE3 GUI to carry out experiments at BioMAX. Click on each of the following links to display information for each step.

MXCuBE3 runs on the Firefox browser installed on all the BioMAX control workstations. The GUI can be launched either from the MXCuBE3 icon on the workstation desktop or by typing the command “mxcube” on a terminal window. Type your user name and password to log in and access the  list of you active proposals. Click on the current  proposal and then on the  Select Proposal button.

Preparing to use the sample changer

Before connecting to MXCuBE3 to mount samples with the sample changer, you must have prepared a shipment containing a list of samples in ISPyB as described in the sample shipping procedure. This ensures that all your data will be given a unique name and stored under a directory named after your samples.

Once your samples are loaded in the robot dewar, log in to ISPyB, select your proposal number and click on the Prepare experiment tab. Follow the steps listed in the page:

  • Select the dewar or dewars containing your samples.
  • Select the dewar containing the samples from the ISPyB “Prepare Experiment” tab.
  • Select the location (“basket”) in the sample changer dewar for all the UniPucks in the shipment. Click the Save button after completing this step.
  • Assignment of sample container to position in sample changer dewar.
  • On MXCuBE3, click on the Sample Viewer menu, and synchronize the sample list with ISPyB. ALl the samples will be displayed in the screen.
  • Click on the ISPyB button to synchronize the sample information with ISPyB.

It is a good idea to filter the display to list only the samples you are interested in. For example, you can filter by basket, which will only list the samples in a single UniPuck placed in that basket, by name of the sample, etc.

Filtering the displayed samples. You can choose multiple criteria.

Mounting single samples

Queuing up samples and tasks

You can select and mount the samples one at a time, but often it is more efficient to select several of them and set up a queue, which allows a number of tasks to be performed in an automatic or semiautomated sequence, while also providing the possibility to set up different tasks or data collection modes for some or all of the samples:

  • Select the samples. The fastest way to do this is to click and draw a rectangle over all the samples you want to look at, and then use the Add to Queue button. You can select and add to the queue as many groups of sample as you want, and even click on the samples one by one if you want to collect them in a specific order (make should to hold down the Ctrl key if you select samples sequentially by clicking on them)
  • Selected samples.
  • At this point, you can use the drop down menu next to the Add to Queue button to add characterization or data collection parameters as described in the Data Collection section. The same parameters will be applied to all the samples; it will still be possible to define the data collection taks modify the parameters or add more data collections once the sample is mounted.
  • Menu to add a task for all the samples selected

    Adding a sample characterization task. The variables in the directory and data set names will be substituted by the values defined in ISPyB for each of the samples.

  • Click on the Add to queue button at the botton of the task definition box. The samples in the queue will be then highlighted in blue with a small square for each of the task or tasks added (C for “characterization” or DC for “data collection”.

Finally, you can execute the queue by clicking on the Collect button in the Sample Overview tab or Run Queue in the Data collection Tab.

  • A conformation pop-up window will open with some options to run the queue:
    1. The Auto loop centering option should be unchecked since it is not implemented at BioMAX yet
    2. Select Automount next sample to dismount the current sample after all the tasks are defined and mount the following sample in the queue automatically. It only makes sense to do this if there are characterization or data collection tasks defined in the queue and you are confident that your chosen parameters are appropriate.
    3. Record crystal snapshots (see the information below).
    4. Window showing all the tasks that run sequentially in the queue.
  • Click Collect when everything is OK.

You will be able to stop or pause the queue execution from the Data Collection view whenever you want to change the tasks or introduce more tasks.

"Create new sample" button. Use before going in to the hutch to mount a new sample
Click “Create new sample” button before going in the hutch to mount a new sample.

Currently, only manual sample mounting is enabled at BioMAX. MXCuBE3 can be used to automatically close the beamline shutter and retract the instruments surrounding the diffractometer to facilitate mounting of a new sample (this configuration is known as the Transfer phase). To set the transfer phase, select the Queued Samples tab and click on the button named Create new sample. At this point, it is not necessary to provide a name for the new sample yet. Then, go into the hutch, mount the new sample and search and lock the hutch.

Input boxes used to enter the sample and protein names that will identify the data set.
Input boxes used to enter the sample and protein names that will identify the data set.

Provide names for the sample and the protein in the respective input boxes. These names will be the base for the dataset files and data storage directory names, so you may not use any spaces or strange characters; if the input box remains lined in red, the chosen name is not valid.

  • Click Add sample and mount. This will create an entry for the sample under the Current tab. If you click Add sample instead, the sample will just be added to the queued samples list, and you will have to “mount” it by clicking on the button next to the sample name. If you do not like the name you have created or you think that the sample does not look right and do not want to proceed to image collection, click Finish to remove it.
  • Change the phase to Centring. This inserts a backlight to make it easy to see the crystal and it moves the sample close to the center of the camera view, provided that the length of the pin is standard. If the crystal is far away from the beam position (marked with a blue circle), right click on the crystal or, if not visible, on any portion of the pin or the mount that you can see on the screen and  select Move to beam.  Use the arrows next to the Omega input box to rotate the motor by 90 degrees and adjust the sample position in the other direction. You can also access the Move to beam function by holding the Shift key and double clicking on the point you wish to center.

    Sample visualization and video interaction menu
    Sample visualization and video interaction menu
  • Click on the icon named 3-click Centring to centre the sample in three clicks. Once the crystal is roughly centered at low zoom level, click on the Zoom icon to magnify the image or by holding the Z key and using the mouse scroll wheel. Adjust the centering if necessary with a new 3-click center -note that the first click will not do anything in terms of centering the crystal, it just reactivates the 3-centring function!  After the centering is done, the point will be displayed in white. Make sure that you do not click on the 3-centring icon again, this will lose the coordinates for the centered position and you will have to recenter again in order to set up data collection.
  • It is a good idea to rotate Omega to make sure that the crystal remains in the beam at all orientations. You can use the arrows next to the input box to rotate the motor in 90 degree steps as mentioned above; you can also change the step size by entering a different number next in the input box to the right of the motor position; or hold down the R key and use the mouse scroll wheel.
  • If you want to set up a helical data collection or collect data from multiple spots on the crystal, make sure that you save the current position, by right clicking on the point and selecting Save point. Saved points are displayed in green. If you just want to collect data from a single point you can either save it or just select either Add Characterization or Add Datacollection from the right-click menu. You can move to any previously saved point by clicking on it.

Right-click on a defined point to access the data collection options
Right-click on a defined point to access the data collection options

There are three different modes implemented for data collection, described below. In general, the only input required is what is displayed in the setup window when you select the desired mode. Note that the default input values shown the first time you setup a data collection are not necessarily correct for your samples. Inspect them carefully and change them according to the recommendations below or the advice of the support person. The values you choose will be saved and selected by default for subsequent runs. If you type a parameter that differs from the current value, the input box will be lined in orange. This only means that the position of the motor will change when you start the data collection. The software will not allow you to type invalid values (for example, a value for the resolution that would result in the detector moving past its motion limit). Some optional input boxes will appear when clicking on the three dots below the required input. Some of these options are not fully implemented yet and it is better not to use them, unless the support person indicates otherwise.

  • Clicking on the  Run Now button will start the data collection. Add to Queue will add it to the current queue, which can be of use when mounting samples manually to collect data from different points of the sample. Once a data collection is queued, use the Change button to modify the input parameters before the data collection is executed.
  • Running data collections are displayed in blue. If you notice a problem with the data collection setup, click on the  Stop button to abort the data collection fully. Stopped runs are highlighted in red. It is possible to restart stopped runs by clicking on the run and then on any of the displayed input parameters. This will reopen the setup window.
  • The Pause button will stop the current action and allow you to resume the data collection, but does not have any effect once the actual data acquisition with the detector starts.
  • Once the data collection is complete, it will be highlighted in green. Data collections that finish with an error are displayed in red. If the collection finishes with a warning, it will be displayed in orange.
  • You can clone any run by right clicking on it and selecting Duplicate from the drop down menu. The duplicated run will be then added to the end of the queue. Click on it and then on one of the input parameters to edit the data collection parameters.

Sample characterization

Sample characterization setup panel
Sample characterization setup panel

This function is used to collect up to 4 diffraction shots from a crystal at different orientations 90 degrees apart. Automated image analysis has not been implemented yet, but you can examine the images with the program Albula. A shortcut to run Albula in monitoring mode is provided in the workstation desktop.

For the characterization images, it is better to collect over a wide omega oscillation to make it easier to evaluate the quality of the diffraction by eye (0.5 or 1 degree), with an exposure time of 0.05-0.1 seconds per image and transmission of 10-40%, depending on the collimator size. For the resolution, try a value somewhat better than you expect. Also beam in mind that the initial resolution from the test images, whether estimated visually or calculated by integrating the images, will often be an underestimate of the useful diffraction limit of the crystal.

Data collection

For data collection on a single point, thin phi slicing is strongly recommended. Typically delta omega is set to 0.1 degrees, and the exposure time is 0.01 seconds per image, , with a transmission of 10-50%, or higher for small or poorly diffracting crystals. We strongly recommend collecting 180 or 360 degrees. If the crystal is larger than the maximum available beam aperture size (currently 20 microns) it is advantageous to set up a helical data collection instead (see next section). For small crystals, you may not be able to collect a 180 degrees or even a complete data set from a single crystal. In this case, consider using

Data collection setup panel
Data collection setup panel

a  strategy based on characterization images to optimize the completeness/oscillation range ratio.

Helical scan

If the crystal is larger than the beam, the best practice to minimize radiation damage is to make the beam as large as the crystal. If you are already using the largest beam size available at the beamline, helical collection will help mitigate radiation damage by bringing a fresh volume of the crystal into the beam for each image.

To set up a helical data collection, you must define the start and end points of the data collection along the crystal. You do this by centering the crystal and saving each of the points as described above. Then, click and drag the mouse over an area including both points. That will draw a line between the points defining the data collection axis. Ideally, it is best to use two points along the omega axis, but translation along the perpendicular axis is better than collecting about a fixed point.

To collect crystal snapshots, click on the Snapshot icon. Make sure that you are in the centring phase, since it provides the best view of the crystal. After you have collected the snapshot, you can save the file to any location in your directories.

To have snapshots taken automatically during data collection, use the Settings pull down menu. You can take up to 4 snapshots. Bear in mind that the images are taken in the centring phase at intervals of 90 degrees and the changes between phases add extra time to the data collection.

Once a data collection is finished, the software will launch several automated data processing pipelines. The results can be browsed in the ISPyB interface. To access ISPyB from MXCuBe3 , select the completed data collection run and click on the ISPyB link. The ISPyB application will open in another browser tab. The first time you open you need to type in your user account name and password to log in. Once logged in, go back to the tab where MXCuBE3 is running and click on the link again. ISPyB will remember your credentials and take you directly to the results page for the selected data collection.

The most common issue you are likely to see is lack of response of the video screen (it does not refresh and it does not respond to input). This is usually caused by a loss of connection to the video server and can often be solved easily by refreshing the MXCuBE3 application page.

If it is not just the video that is not responding, or if a simple page reload does not work, try logging out and closing and reopening the browser. If the problem persists, call support staff so that they can restart the server and log in again to MXCuBE3. The video does not reconnect automatically after a server reset, and you will have to refresh the page to get it to update.