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.

Usually during your experiment, the MAX IV 3 GeV ring will operate in top up mode and X-rays will be delivered to the beamline. You can monitor the electron beam current on MXCuBE. However the electron beam in the accelerator may be lost on occasion. If this happens, you can reopen the beamline from the Beamline Actions drop down menu (“open_beamline_shutters” option). When you finish your experiment, run the “end_beamtime” option from the same menu to close the beamline.

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.

Note:Currently, the MAX IV sample changer supports samples mounted on UniPucks only.

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 samples entered via ISPyB (useful if you have partially filled pucks and you only want to see locations with samples), by sample name, etc.

Filtering the displayed samples. You can choose multiple criteria.

Important: Double-check that the fill pattern of pucks match exactly the information entered in ISPyB. If the robot attempts to mount an non-existing sample, it will stop operating!

Once your samples are in place in the robot dewar and the hutch is searched and locked, the robot can be powered up (staff will show you how to do this if needed). Note that once it is done, you will not be able to inside the hutch without disabling the instrument. If you need to go inside the hutch during robot operation, follow this procedure:

  • From MXCuBe3, use the Beamline Actions drop down menu to select the “prepare_open_hutch”. This scripted action will move the sample exchanger and other beamline motors to a safe position.
  • During execution of the script, a window will pop up on MXCuBE3. Do not press the “abort” button, doing so may require a robot reset by staff.
  • Once a “Run” button appears at the top of the window, it is safe to go inside the hutch.

Mounting single samples

Once a sample information is loaded onto MXCuBE3 you can mount it by right clicking on the sample block. This displays a sample menu that displays all the possible actions for the sample.

    Sample menu shown upon right-clicking on a given sample

    To just mount the single sample, without any setup of an automated data collection run or other sequential actions, click on Mount. Once the sample is visible on the video screen, follow the steps in the sections below to center the sample and set up the data collection.

The rest of the selections in the menu are related to sample inclusion in a queue of automated or semiautomated tasks, as documented in the next section.

Queuing up samples and tasks

Although you can select and mount the samples one at a time, it is often 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 of interest, but you can also hold down the Ctrl key and click on individual samples. The selected samples will be surrounded by a discontinuous grey frame. then, use the Add to Queue button to add all the selected samples to the queue. The samples in the queue will be highlighted in blue. To remove a sample from the queue, right click on the sample and select Dequeue sample.
    • Selected samples.
    • If you wish to define characterization or data collection tasks at this point, use the drop down menu next to the Add to Queue, as described in the Data Collection section. The same parameters will be applied to all the samples in your current selection. Note that it is not possible to execute the newly defined data collection at this stage (the Run button is inactive). If you do not want to define tasks at this stage, simply skip this step.
    • 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 bottom of the task definition box. If you added data collection parameters, a small square will be displayed on the samples in the queue for each of the task or tasks added (C for “characterization” or DC for “data collection”. You can add multiple tasks for each sample.
    • If you want to remove a data collection task, click on the cross in the task button. It will also be possible to define the data collection tasks modify the parameters or add more data collections once the sample is mounted.

    If you have not defined any data collection tasks, go to the Data collection Tab and click on the Mount button next to each samples to mount them and collect data one by one. Before mounting a sample, the robot will automatically dismount the previous one .
    If you have defined tasks for all the samples, 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 configuration pop-up window will open with some options to run the queue:
      Window showing all the tasks that run sequentially in 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. Only do this if you are confident that your chosen parameters for data collection or sample characterization are appropriate.
      3. Record crystal snapshots (see the information below).
    • 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 for manual sample setup.

Manual sample is an option for sample mounts or containers incompatible with the sample exchanger or for collecting data at room temperature. 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, use the Beamline Actions drop down menu and select “prepare new sample”. 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.

Once the sample is mounted, provide names for the sample and the protein in the respective input boxes in MXCuBE3:

  • Select the Queued Samples tab and click on the button named Create new sample
  • 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.
  • 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.

  • If not using the sample exchanger, change the phase to Centring (the sample exchanger mount procedure changes the phase automatically). In the centring phase, a backlight is inserted to make it easy to see the crystal and the sample moves 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; or translate the sample using the arrows on the translation tool located to the left of the screen.
    Sample translation tool. Click on the arrows to translate the sample . Click on the settings symbol to define the length of the translation.

    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 proceed to a data collection already set up for a sample mounted with the robot, or 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 set up a data collection from the newly centered 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.Note: If you click outside the centered point, you will access a different special menu to set up 2D data collection. The options in this menu are under commissioning and should not be used.

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 the run name header 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, we recommend using exposure times of 20 ms per degree. With a defocused beam (50 microns), 0.5 degree images with 10 ms exposure per image at 50-100 % attenuation result in good quality data. We strongly recommend collecting 180 or 360 degrees. If the crystal is larger than the maximum available beam aperture size (currently 50 microns) it is advantageous to set up a helical data collection instead (see next section). For small crystals (around 10 microns) it may be better to use the focused beam with a small aperture. If the crystal does not last long enough to collect a 180 degrees or even a minimally complete data set, 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.
  • The sample queue will also be lost after a server reset and you will not be able to see which samples you have already collected data from either. However, the sample collection information is preserved in the ISPyB Data collection tab.
  • Currently MXCuBE does not issue any warning if the X-rays are not being delivered to the sample. If the diffraction images suddenly look blank (no scatter from the air creating a beamstop shadow, no counts on the detector), check that there is a current in the ring and that the beamline is open. If there is air scatter on the detector, check the alignment of the sample. If the beamline is open but the problem persists, contact staff.