MXCuBE3 at BioMAX – User Guide
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.
To launch MXCuBE3 from an already open browser window, type the url http://mxcube.maxiv.lu.se. Once the interface loads, log in with you DUO user name and password and select the proposal.
Note: The first time ever you log in at a BioMAX machine under you user account, there will be no MXCuBE or other experiment software icons displayed until you open a terminal. This will run a login script and set up the desktop environment.
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, by selecting “beamtime_start”. When you finish your experiment outside staff support hours, run the “beamtime_end” option from the same menu to close the beamline.
You can enter the energy for the experiment from the top bar in MXCuBE. Depending on the starting and ending energies, it can take over a minute for all the motors involved to finish moving. During this time, the beam position is not stable. A brief message will appear on the GUI when the beam has stabilized. The alternative is to select the “check beam” tool under Beamline Actions and run it to see if the beam has stabilized; or use the Monitor beam tool mentioned below.
The beam focus can be changed between 50×50, 100×100 and 5×20 microns (vertical, horizontal). Since October 2020 you can change between 50 and 100 micron focus from the Beamline Actions. To use the fully focused beam, contact staff.
Important: Do not confuse the focus size with the actual beam size defined by the diffractometer apertures. See the section on how to prepare for data collection below.
MXCuBE does not currently have a continuous beam monitor, but you can display a live plot of the beam position in the experiment hutch, from the Monitor beam icon present on the beamline workstation or remote server desktop. Clicking on the icon will open a window showing the vertical (in green) and horizontal (blue) beam positions. They both should oscillate by a around 0. You can change the scale of the plot with the mouse scroll wheel. If the beam position is offset from zero by more than 5-10 units the beamline could be misaligned and you should contact staff.
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 EXI (EXtended 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:The MAX IV sample changer supports samples mounted on UniPucks only.
Once you arrive to the beamline, staff will show you how to place your samples in the robot dewar. We recommend that you use the IsaraLoader iPad tool while you load the pucks so that the puck positions are automatically entered in EXI.
If you cannot use the IsaraLoader tool, you need to log in to EXI to assign the puck positions; select your proposal number and click on the Prepare experiment tab; then, follow the steps listed in the page:
- Select the dewar or dewars containing your samples. If you do not see the shipment, try unclicking the “Display only shipments scheduled for future sessions or in processing status” checkbox. That will display all the shipments in the database.
- Select the location (“basket”) in the sample changer dewar for each UniPucks in the shipment. Click the Save button after completing this step.
Once the pucks are assigned (manually from EXI or automatically by the IsaraLoader), go to MXCuBE3:
- Enable the robot from the Data Collection menu, by clicking on the button to the left of the safety shutter – the hutch must be searched and locked.
- Go to the Sample Viewer menu, synchronize with the ISPyB database to obtain your sample information (as of October 2020 it is no longer necessary to click on “Get samples from SC”). All the sample names will then be displayed in the screen instead of the default Sample:’container’:’port’.
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 EXI (useful if you have partially filled pucks and you only want to see locations with samples), by sample name, etc.
Important: Double-check that the fill pattern of pucks match exactly the information entered in EXI.
If you need to go inside the hutch after you have started 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.
- After the procedure is finished, the “Run” button will appear at the top of the window; then it is safe to go inside the hutch.
You will also follow the same procedure to go inside the hutch to dismount your samples after the experiment. Please make sure to close the dewar lid after dismounting the samples.
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.
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.
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.
- If you wish to define characterization or data collection tasks at this point, use the Add to Queue drop-down menu, and provide the data collection parameters 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.
- 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:
- The Auto loop centering attempts to center the loop in the beam. Automated centering may not work optimally for all cases, particularly small crystals in large loops, but it will bring the sample area into focus and make it easier to center the crystal with the 3-click tool described below. Therefore it is currently always run by default. The function also leaved the diffractometer in the “centering phase”, with the back light inserted and ready for “3-click centering”.
- Select Automount next sample to dismount the current sample after all the data collections are completed and mount the following sample in the queue automatically. Only do this if you have pre-defined data collections and you have mounted your crystal so that the autoloop centering places them reliably in the beam.
- 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.
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.
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.
- Once you have mounted the sample, return to MXCuBE and change the diffractometer phase to Centring. Follow the steps described in the next section to bring the sample into focus and inspect it visually before proceeding with data collection.
- The sample exchanger mount procedure changes the phase automatically to centring mode after mounting a new sample. 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.
- 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: 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.
- Check that the beam size is set to the correct value. In the general case, the beam should match as closely as possible the crystal size. The diameter of the blue circle on the video corresponds to the size of the aperture, so it should be easy to see which one matches best the crystal size. If your crystals are nearly or larger than 0.1 mm, use the 100 micron aperture in combination with a 100 micron beam focus. For crystals below 0.1 mm and above 0.015 mm use the 50 micron beam focus and an aperture of 50 or 20 microns. For very small crystals, it is best to use the fully focused beam and a 10 o 5 micron aperture.
- 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 inside 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, Add Datacollection or any of the other options available from the right-click menu. You can move to any previously saved point by clicking on it.
- If you right click outside the point you will have access to a different menu to collect 2D data (without rotating the crystal). This option can be useful to locate a good diffraction spot on an inhomogeneous crystal or determine a difficult-to-see crystal location
Knowing the flux (total number of photons per second on the sample) is important to be able to estimate the time that the crystal can last in the beam. MXCuBE3 will measure the flux before starting each data collection and saves it under the ISPyB database experimental parameters and can be consulted from the EXI interface; it also displays the last value measured at the top of the GUI. This value will depend on the beamline transmission and the beam defining aperture in use and also depends somewhat on the beam energy. Typically, you expect to measure near 412 photons/s through the 50 micron aperture with the unfocused beam (50 microns) and full transmission.
For the flux measurement, the software changes the MD3 phase and translates the sample closer to the cryojet by a small amount to avoid exposing it to the X-rays. It will be returned to the original position once the measurement is finished.
If you want to measure the beam manually (for example, to check the flux after changing the energy, the beam focus or the aperture size) open the Beamline Actions and run the calculate_flux action. Note: The flux value only gets updated before each data collection or when you run the calculate_flux function. If the beam disappears afterwards, the flux value will not change automatically. If you get a flux value of the order of or less than 107 photons/s (which is the error level in the measurement), there is no beam reaching the sample. If that is the case, check for obvious causes:
- Too high beam transmission – If you change the energy to a lower value and there are attenuation filters in the beam the transmission will decrease and can eventually become 0. Changing the transmission will let the beam through again.
- Loss of the electron beam in the R3 accelerator. Monitor the electron beam status and, after the beam has been injected, start the beam as described in a previous section. Contact staff if you experience problems.
The beamline action “checkbeam” will also provide an estimate of the flux based on a beam monitor before the diffractometer. This value is less accurate that the value measured at the sample position as it does not take into account the beam aperture, and it does not get written out to the ISPyB database. It can be used nevertheless to determine if the beamline has recovered correctly after a beam loss, for example, resulting from an electron beam dump. Values less than 2-3 times the normal indicate that the beamline may need realignment. If this happens, changing the energy by about 2 keV from the current position and back may sometimes move the beam back to the correct position. If it does not, contact staff.
The flux value can be used for dose calculation, for instance in the raddose server.
There are three different modes implemented for oscillation data collection, described below. Since 2020, modes are available to to measure XRF spectra and energy scans over an absorption edge. 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.
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 20-100%, 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.
Since 2020 there is the option, available from the Settings menu to carry out characterization image analysis and calculate a diffraction plan (strategy). If you use this option, be aware that the data collection will not be marked as finished until the characterization analysis is completed. Calculating the diffraction plan is useful to obtain an estimate of the dose absorbed by the sample. However, we recommend collecting always 180-360 degrees to improve the data quality, even if the diffraction plan gives a shorter total rotation range to obtain a complete data set.
Sometimes the crystals diffract to low resolution and are very mosaic as a result of a non-optimize cooling procedure. In these cases, annealing the crystal sometimes allows crystal reorganization and improves the quality. If you want to try retracting the cryojet to let the crystal warm up briefly, you can do so from the beamline actions. Note that this is a “last resort” tool and it should not be used to get rid of superficial ice from an otherwise reasonable crystal, as it will cause more damage than good in this case.
For data collection on a single point, we recommend using exposure times of 11 ms per degree. With a defocused beam (50 microns), 0.1 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, or more, for de novo phasing experiments (in this case, please consider offsetting the kappa axis to obtain more accurate data) 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, described in the next section. For small crystals (around 10 microns) it may be better to use the focused beam with a small aperture.
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.
The XRF scan is useful to detect the presence of heavy metals in the sample, whether they are present in the buffer or bound to the protein. In some cases, this can be useful to identify features in the density map.
When you start the scan, the fluorescence detector will move to point towards the sample. The software will acquire a series of very short exposures to determine the optimal beam transmission, which is typically rather low. Then, the crystal is exposed during the time selected in the input window (we recommend to use 0.1 seconds). The resulting spectrum will be saved to the ISPyB database. Often, the dose received by the crystal during this measurement is not higher than the equivalent of 10-20 diffraction images, but if you are concerned about minimizing the dose, you can collect it after data collection, or use a poor quality sample.
The result file will be stored together with the diffraction images in the sample directory. Besides the h5 format file, we also save a png file for easier visualization. This file is also visible in EXI.
Energy scan and SAD/MAD data collection
If a heavy atom is present in the sample and the absorption edge is within the energy range of the beamline, it is possible to do an energy scan to locate the position of the absorption edge (different, in the general case, to the theoretical value).
Tip:Before you start the energy scan, we recommend moving the energy near the absorption edge position. This will save you a little time since you will need to characterize the crystal diffraction and collect data near that energy, since the energy will move automatically back to the starting position after the scan is finished.
To start an energy scan, select the option from the right-click menu associated to a point. A periodic table will then show up. You need the select the element of interest. If you select an element with L edges, the L3 edge will be scanned. As for the XRF scan described above, the software will acquire a series of very short exposures to determine the optimal beam transmission at an energy close to the absorption edge. Then it will carry out the energy scan itself and will write out the results to the ISPyB database. Please inspect carefully the output file in EXI, since the program used for analysis (Chooch) can fit incorrectly a very poor or non-existing signal.
When you create a data collection following a scan, the energies selected by the analysis, corresponding to the maximum f” (‘peak’), minimum f’ (‘inflection’) and maximum f’ (‘remote’) are listed in the data collection input box. To do a SAD experiment, select and click on the ‘peak’ energy to import it to the energy input box. The energy will change automatically for data collection
The interleaved (wedge) data collection for MAD experiments is not available yet. For MAD, we recommend doing low dose data collection at only two of the energies, one of which should be the remote. Eg: collect 180 degrees at 20 % transmission at the peak or inflection energy, and then at the remote. In difficult cases or P1 symmetry, collect a second data set at the two energies from 180 to 360 degrees.
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.
Once a data collection is finished, the software will launch several automated data processing pipelines. The results can be browsed both in the ISPyB and EXI interface. At the moment, only the ISPyB interface is accessible from MXCuBe3; to access it, 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.
Please also see Data handling and processing at BioMAX.
MXCuBE3 supports multiple user log in from multiple locations, at the beamline or remotely. Any user belonging to the same proposal can be logged in simultaneously, although only one can issue commands and has control over the interface; this user is called “master”; by default, the master is the user who logs in first. The users who log in afterwards are “observers”. When one more than one user is logged, the number of observer users is displayed on top of the link to the Remote Access (RA) tab, and an icon to the chat tool appears to the right bottom of the interface. The RA tab lists all the users logged in and who is the current master.
The master user should be able to mount samples, collect data and control the beamline through MXCuBE regardless of location. The observer users can navigate through all the MXCuBE tabs and see what the user in control is doing. They can also use remote tools such as the beamline video feed and the chat and request control through by clicking on the Ask for control button in the Remote Access (RA) tab. Observers cannot use the Take control button; only user support staff can use this button, if it is necessary for experiment support or troubleshooting.
If an observer asks for control, the master can give control by clicking on the window that appears on their instance of MXCuBE. There is also a general option to transfer control by default after a timeout period, enabled by default. Finally, the master user can also give control at any time to any other account logged in by clicking on the control icon in the last column of the user information list in the RA tab (but the master cannot log out any other user; that is also a support staff tool).
For general information about obtaining and preparing for remote beamtime, please read Remote experiments at BioMAX.
- The most common problem is a lack of response of the video screen (it does not refresh and it does not respond to input). This lack of response can also happen with other information displayed on real time and is usually caused by a glitches in the connection to the video or other servers. It usually can be solved easily by refreshing the MXCuBE3 application page web page.
- Sometimes, it is only the omega motor that is not responding. You can test this by trying to rotate the sample. If the omega value does not change and you do not see the sample rotating either in MXCuBE or in the beamline video, find and run Abort_MD3 from the list of beamline actions.
- 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. Since May 2020 you can also restart the server outside support hours from the beamline actions.
- 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 database, and you can view it from the EXI Data explorer tab.
- If the sample changer fails to mount a sample, ie, it finished the mounting operation but there is no sample or a sample base on the goniometer, MXCuBE will give an error. To be able to continue mounting samples, go to the Beamline actions and click the button empty_sample_mounted.
- If the Sign out button appears to be inactive, try increasing the size of the browser window. This can be a problem when running MXCuBE3 on a small screen.
- Currently MXCuBE will give an error at the beginning of the data collection if the calculated flux is 0, or if the beam has not stabilized after an energy change, but it will not stop the task. If the diffraction images look blank (no scatter from the air creating a beamstop shadow, no counts on the detector), there is likely no beam reaching the sample. The most common reason is a beam dump. Please see the sections about starting the beamtime and measuring the flux to help diagnose the problem.