Robem user’s guide (v4.01)

 

NOTE – robem user’s guide unchanged from v4.0

Table of Contents

I. Introduction.. 2

Conventions. 2

Image formats. 2

II. Common tasks. 3

Launching robem... 3

Exiting robem... 3

Reading/writing files from within robem... 3

Zooming in/out. 3

Getting pixel coordinates and value, measuring distances. 4

III. Boxing particles from a micrograph.. 4

Generating box coordinates. 4

Saving box coordinates AND boxed image files. 5

Saving just box coordinates. 5

Reading box coordinates. 6

IV. Estimating defocus level 6

Generate incoherent average of transforms. 6

Set microscope parameters. 6

Pick CTF points (stigmated images). 7

Defocus Refinement. 7

Writing results. 7

V. Visualization.. 8

Viewing map sections. 8

Viewing radial projections. 8

Viewing icosahedral projections. 8

Viewing shaded surface representations. 9

Toggling between 3D representations and section view... 9

Viewing and saving a 2D movie.. 9

Writing sections, projections, or surface renderings. 10

VI. Difference maps. 10

VII. Data manipulation.. 11

Manipulating pixel intensities in maps or boxed image files. 11

Deleting images from boxed image file.. 11

Applying mirror plane reflections to map.. 12

Truncating or adding to a map.. 12

VIII. Running robem in batch mode. 12

 


I. Introduction

 

This document describes robem, a multipurpose tool for carrying out many of the image pre-processing and analysis steps required for solving and interpreting cryo-reconstructions.

 

We do not attempt to cover every capability of robem, but rather focuses on what we feel are the most important ones. Like most academic software that was originally intended for in-house use, robem contains many features that are either experimental, have become obsolete, or are in various states of development. Every effort will be made to keep the documentation up to date, but lags between the software and documentation are inevitable.

 

Robem is often used in conjunction with our image reconstruction software (auto3dem) and an automation tool (autopp) that can be used to handle many of the repetitive tasks that arise when working with multiple micrographs. These are both described elsewhere.

 

Conventions

 

All robem controls and dialogues are displayed in bold font. Navigation through multiple levels of pull down menus is indicated using the syntax

 

TopLevel > 2ndLevel > 3rdLevel …                                   

 

Unix/Linux command line operations are indented and displayed in fixed font. The “%” sign is the Unix prompt and not part of the command

 

     % unix command line

 

Image formats

 

Robem was developed in conjunction with our image processing software (auto3dem, P3DR, PO2R, PPFT, etc.) and works primarily with the Portable Image Format (PIF). It is straightforward to convert files between PIF and the MRC formats using both 3rd party programs (e.g. BSOFT) and applications that are bundled with our software distributions. The main point that must be kept in mind is that the two formats have different definitions for the phase origin. MRC maps and boxed images always have even dimensions and the origin lies between the central pixels. For PIF images, the dimensions are always odd and the origin lies at the central pixel. As a result, the center pixel of transformed images will correspond to a spatial frequency of zero.

II. Common tasks

 

Many basic operations are common to multiple tasks performed by robem. In an effort to minimize repetition, they are described below.

 

Launching robem

 

Robem is launched directly from the UNIX/Linux command line. For convenience, we suggest running in the background. Although there are a large number of command line arguments, most of these are normally used only when robem is run under the control of autopp. Typically usage is either with no arguments or with an image name specified.

 

            % robem &

     % robem -pre image.pif &

 

Exiting robem

 

The preferred way to exit robem is through File > Exit. This automatically closes the main window and any other windows that are currently open. In the event that robem freezes, it can also be killed from the command line after first identifying the process number.

 

            % ps -u username | fgrep robem

     12345    pts/2   00:00:01 robem

     % kill -9 12345

 

Reading/writing files from within robem

 

In some cases files are automatically written after performing certain operations, but in general most input/output is performed through the File menu. Some examples are shown below.

 

Read image files:                   File > Read > Image Files

Read box coordinates:         File > Read > Box Coords

Write boxed images:                         File > Write > Circle Boxes

Write box coordinates:        File > Write > Box Coords

 

Zooming in/out

 

It is possible to zoom in or out when viewing any of the PIF data types (maps, boxed images, micrographs). This can be done in several ways:

 

Select Zoom tool on the main tool bar and position cursor over image

Left click to zoom in, center click to zoom out, right click to restore default

 

Use leftmost arrows on main tool bar to increment/decrement zoom

 

Type desired zoom into leftmost text box on main menu

 

Getting pixel coordinates and value, measuring distances

 

These operations are done using the Point tool and the Point Values dialogue.

 

Select Point tool on main tool bar

Move tip of cursor over pixel to obtain value and coordinates

Left click to mark point and save values

Center click to mark point and get distance to first point

Right click to clear all points

 

If the pixel size is listed in the image header, distances will be listed in both pixels and in Angstroms. As of version 4.0, the behavior of the point screen has been made more intuitive and clicking the middle mouse button always measures distance to first point and redraws screen.

 

Since it is such a common operation, the Point Values dialogue also contains a button marked Center that places a mark at the center of the image and automatically clears all other points. (Note - this currently only works properly for maps)

III. Boxing particles from a micrograph

 

Creating a boxed image file involves two steps: generating the coordinates of the boxed particles and using the box coordinates to extract pixels from the micrograph. These can either be done together or treated as two distinct steps.

 

Generating box coordinates

 

After the micrograph has been read into robem, it will be displayed in the main window. To box particles, zoom into the desired part of the image and then

 

Select Box tool on main tool bar

Left click with cursor over center of particle to create box

Right click an existing box to delete

Left click and drag an existing box to move

 

The box dimensions are set using controls within the Boxing dialogue. The various box components are turned on/off using the buttons next to the Emma Radius, Feather Width, Box Size, and Empty Shell Width controls.

 

Feather Width is normally kept at zero. The values of the Emma Radius and Empty Shell Width have no impact on the boxed images and are used simply as a guide to the eye to help with boxing. The Box Size control sets the size of the boxed image that will be written. The value should be odd to be consistent with the PIF convention.

 

To clear all boxes, click on the Clear Boxes button in the Boxing dialogue. Toggle next to Display Circle# controls display of box numbers and the Color button cycles through the box number color. All other controls are used for advanced features such as automatic boxing.

 

Saving box coordinates AND boxed image files

 

After particles have been boxed:

 

            File > Write > Circle Boxes

 

Set the name for the boxed image file in the Get file_popup dialogue and click OK. Normally you’ll want this to have the same base name as the micrograph. For example, if the micrograph name were micro1.pif, an appropriate boxed file name would be micro1_box.pif  (this default name is automatically set in v3.15 and later).

 

After clicking OK, the Appodize Params dialogue will appear.  All parameters should already be set correctly: no apodization, circle background method, zero border width, and radius equal to that used during boxing. Clicking the Do It button will automatically write out a box coordinate file with the bcrd extension.

 

Saving just box coordinates

 

After particles have been boxed:

 

File > Write > Box Coords

 

Set the name for the box coordinate file in the Get file_popup dialogue and click OK. Normally you’ll want this to have the same base name as the micrograph. For example, if the micrograph name were micro1.pif, an appropriate box coordinate file name would be micro1.bcrd  (this default name is automatically set in v3.15 and later).

 

Reading box coordinates

 

To read in an existing box coordinate file:

 

     File > Read > Box Coords

 

After loading coordinates, boxes can be added or deleted and new files written.

IV. Estimating defocus level

 

Robem can be used to estimate the defocus level in a micrograph. Unlike some other methods, one of the advantages of the approach taken in robem is that it allows the user to see how well the nodes in the CTF match the locations of the Thon rings in the transform of the data.

 

After reading in a boxed image file containing either boxed particles or a tiling of the micrograph (see documentation on autopp – option 2), take the following steps to estimate the defocus level.

 

Generate incoherent average of transforms

 

FFF > FFT (to open FFT dialogue)

 

On FFT dialogue:

FFT > CTF Estimation (upper right corner)

Make sure that the Incoherent Avg option is selected (default)

Click the Average FFTs button

Set microscope parameters

 

Make sure that microscope parameters are correctly set (text boxes in lower right corner of FFT dialogue). Note that the Mag , PxSiz, and ScStp values are interdependent.

 

Changing Mag, then hitting enter:          PxSiz = (1000*ScStp/Mag)

Changing PxStp, then hitting enter:       Mag = (1000*ScStp/PxSiz)

Changing ScStp, then hitting enter:        PxSiz = (1000*ScStp/PxSiz)

 

Ultimately, the PxSiz value is the only one that matters in the defocus calculations. The Mag and ScStp fields are provided solely as a convenience for pixel size determination.

 

Pick CTF points (stigmated images)

 

In most instances, you will be working with stigmated (i.e. not astigmatic) images. Since this is the typical case, in robem v3.14 and later the Force focus major = focus minor option will be selected. Clicking on the transform will cause a series of circles with radii corresponding to the nodes of the estimated CTF to appear. The goal at this stage is to get the circles to match as closely as possible the locations of the Thon rings. The node selected in the CTF Node Num text box (default = 1) will appear in red and all other nodes will be grey. The defocus level estimate will be updated in the Focus Major and Focus Minor text boxes.

 

Selecting the Zoom button, changing the Overlay Intensity, and using the Flicker button to toggle the estimated CTF nodes often makes it easier to select a more accurate starting estimate for defocus value.

 

Defocus Refinement

 

Clicking the Defocus Refinement button will open the Automatic Defocus Refinement dialogue. In this new window, click the Estimate Defocus button followed by Update FFT screen.

 

The quality of the defocus estimate at this point is determined by the agreement between the Signal-Bkg and CTF^2 curves. Note that the latter does not contain decay terms, so look for agreement in the locations rather than heights of the peaks. Another indication of a good fit is a Signal-Bkg curve with well defined multiple peaks.

 

A slightly better defocus value can often be found by clicking the *10 button (launch ten more iterations of defocus refinement), but this generally only helps if the defocus estimate is relatively close to the true value.

 

If a good agreement between the curves cannot be found, return to the main FFT dialogue and try selecting a new defocus estimate. In some cases, the signal in the data set may be so weak that accurate CTF determination is not possible. If using boxed particles, it may be helpful to go back and use a tiling of the micrograph in order to get a stronger signal (see documentation on autopp – option 2).

 

Writing results

 

After you are satisfied with the defocus estimation, a parameter file compatible with the auto3dem image reconstruction software can be written by clicking either the Generate Param File (full) or Generate Param File (empty) button. The former will create a file that contains the header information (boxed micrograph name, image and microscope parameters) plus records containing dummy information for the boxed particles, whereas the latter writes out just header information. The empty option is particularly useful when defocus estimation was performed using a tiling of the micrograph, in which case the boxes do not correspond to particles.

 

IMPORTANT NOTE REGARDING EMPTY FILES: Auto3dem is designed to handle empty particle parameter files and will assign random orientations and origins corresponding to the box centers. This feature only works as expected only if all parameter files are empty.

V. Visualization

 

While robem does not have the flexibility found in many dedicated visualization tools (e.g. Chimera), it does provide capabilities that are particularly useful for interrogating virus structures.

 

Viewing map sections

 

When a map is first loaded into robem, sections of the map lying perpendicular to the z-axis are displayed. By default, the central section is shown in the upper left corner of the viewing area, but this can be changed by entering a new section number in the SecNum text box or by using the arrows next to this box.

 

Viewing radial projections

 

Display > 3D Rendering (if not already open)

 

In 3D Rendering dialogue:

Select Radial/Icos Proj

Set MaxRadius using slider, arrows or text box

Click TryIt button or right click on blank area of dialogue

 

The Immediate Update option can also be selected so that display will automatically update when parameters are changed.

 

KNOWN BUG – Changing MaxRadius or MinRadius will sometimes cause robem to crash, particularly if either value is outside of the allowed range of radii for the map. Reading in the map on the command line using the –pre option seems to prevent this error.

 

Viewing icosahedral projections

 

Display > 3D Rendering (if not already open)

 

In 3D Rendering dialogue:

Select Radial/Icos Proj

Set MaxRadius using slider, arrows or text box

Select Icos RadPrj

Select options in Icos options dialogue

Click TryIt button or right click on blank area of 3D rendering dialogue

 

The Bulge option in the Icos Options dialogue generates a projection on a bulged icosahedral surface, where the degree of bulge is controlled by the Slide value (0 = normal icosahedron, 1 = sphere).

 

Viewing shaded surface representations

 

Display > 3D Rendering (if not already open)

 

In 3D Rendering dialogue:

Select Shade

Set Surface Density using slider, arrows or text box

Click TryIt button or right click on any blank area of dialogue

 

Surface shading tends to be slow, so we suggest tuning off The Immediate Update option.

 

Toggling between 3D representations and section view

 

On the main menu tool bar, the icon between the Point tool and SecNum text box can be used to toggle between the 2D and 3D representations. Returning to the 2D view will always result in the central section being displayed in the upper left corner of main viewing area.

 

Viewing and saving a 2D movie

 

Display > 2D Movie/Display

 

Upon opening the Movie dialogue, the first section of the map will be displayed. The set of controls on the right side of the menu bar are used to set the movie attributes. By default all sections of the map will be shown, but the range of sections can be set using the two small vertical scroll bars on the left (first section) and right (last section). The play and loop buttons launch single and continuous showings of the movie, respectively. When viewing the movie in continuous mode, the direction button determines whether the movie starts over from the starting section or runs backwards until starting section is reached.

 

Clicking the Save button will cause the last movie that was viewed to be saved to disk. Both an animated GIF (movie.gif) and a set of movie frames in PCX format (robem_nnn.pcx) will be written.

 

The existing PCX files will be deleted before writing the new files to avoid any confusion that may arise from mixing files from multiple movies. Note that the PCX files are sequentially numbered and do not necessarily correspond to the section numbers. These files are provided for those users who wish to exert finer control over the movie (speed, timing, included frames, etc.) using a separate editing tool.

 

Writing sections, projections, or surface renderings

 

To write an image containing the map section listed in the SecNum box or the 3D rendering shown in main viewing area:

 

File > Write > RAW image

Set name in the Get file_popup dialogue

Choose Write current ImgNum in Get Choice dialogue

VI. Difference maps

 

Difference maps generated by subtracting one map from another can often highlight subtle changes in a structure. In order for the results to be meaningful, the maps must be at the same magnification and have the same mean pixel density. Robem provides the capability to read in two maps, perform the necessary scaling operations, and generate the difference map.

 

After the first map has already been read:

 

Manipulate > Subtract 3D Map

 

On Subtract 3D Map dialogue:

Click Browse to read in the map to subtract from original map

Click Find Mag button until Starting Mag no longer changes

Click Find Scaling button until scaling equation no longer changes

 

In the main viewing area, the original map will be shown on the left, the scaled “subtract” map in the center, and the difference map on the right. The Flicker button can be used to switch back and forth between the two maps. The *10 button displays ten cycles of flickering and the Inf button turns on flickering until disabled. The red and green tools next to the flicker buttons control the flicker rate.

 

To save the scaled “subtract” map and the difference maps, select the Save Second & Difference Maps option and click the Subtract Map button. Two new maps, named secondMap.pif and diffMap.pif, will be written to disk.

VII. Data manipulation

 

After the map or boxed image file has been altered, be sure to write out a new file if you want to save the changes.

 

File > Write > Circle Boxes (boxed image files)

File > Write > Map (3D maps)

 

Manipulating pixel intensities in maps or boxed image files

 

After opening the Fix Map or Image Values dialogue (Manipulate > Fix Values), various transformations can be applied to the data. Note that the transformations only occur for those pixels that fall within the radii and ranges specified in the text boxes. By default, these values will be set such that all pixels are affected. For boxed image files, the radii and ranges are applied individually to each image, whereas the Z range determines the image numbers that are affected. Clicking the Fix Values button

 

Deleting images from boxed image file

 

After reading a boxed image file, select the Box tool from the main tool bar. Left clicking anywhere on an image will cause a diagonal line to appear through the image and mark it for exclusion when a new file is written. Clicking a second time on an image will remove the red line and mark it for inclusion.

 

Center clicking will cause all boxes between the last box and the current box to be marked. Right clicking anywhere in the main viewing area toggles the state of all images.

 

IMPORTANT – Be extremely careful when using this feature since it is easy for the boxed image file, box coordinates file, and particle parameter file to get out of synch. The image and box coordinate files have no permanent identifier associated with a particle, whereas the particle index in the parameter file refers to the sequential ordering within the image file. Deleting an image would require deleting the corresponding records in the other two files AND renumbering all records after the deleted record in the parameter file. If this sounds complicated, it’s because it is! A safer approach would be to read in the original micrograph and box coordinates file, delete the unwanted boxes, and write out a new set of files.

 

Applying mirror plane reflections to map

 

Manipulate > Invert 3D Map

Apply reflection operations in Invert 3D Map dialogue

 

These operations are normally done to convert a map to the correct hand. Note that for particles with icosahedral symmetry any one of the reflection operations will be equivalent to applying an inverse operation.

 

Truncating or adding to a map

 

            Manipulate > Truncate/Addto

            Set ranges and Fill Value in Truncate/Addto dialogue

            Click Truncate/Add to apply operation

 

Keep in mind that PIF maps that will be used by auto3dem should have odd dimensions so that phase origin is handled correctly. To restore dimensions to original size in text boxes, click Whole Map button.

VIII. Running robem in batch mode

 

Robem is normally run as an interactive program, but does have a number of functions that can be executed in batch mode without having to launch the GUI.

 

In earlier versions of the software, robem had to be run under the control of Xvfb so that graphical output would not be written to the display. As of version 4.0 this is no longer necessary. To run in non-GUI mode, use the –nogui command line option

 

% robem -nogui [other options]

 

The autopp script, which can be used to automate many of the image preprocessing steps, always runs robem in batch mode.