An overview of changes between EMAN1 and EMAN2

We have tried to preserve as many of the conventions from EMAN1 as possible, to limit the difficulty in making the transition. For example, just like EMAN1, middle-clicking (alt-click on Mac) on just about any GUI window will bring up a powerful 'control-panel' for manipulating the image and display. However, in addition to the 2-D image display widgets in EMAN1, EMAN2 includes a powerful set of 3-D display widgets. While in no way are these designed to compete with dedicated packages like Chimera, they do provide users with a quick way of looking at their 3-D results.

Here is a list of some of the most important points:

• All EMAN2 programs start with 'e2' and end with '.py' (because they are python scripts and Windows requires this)
• Most EMAN1 programs have a direct EMAN2 analog, for example, proc2d has become e2proc2d.py, and iminfo has become e2iminfo.py
• All EMAN2 programs will respond to '-h' or '--help' at the command line, and do not require a GUI to view.
• All EMAN2 command-line programs, including the GUI, are written in Python, which gives advanced users a lot of flexibility without having to recompile EMAN2 from source.
• The command-line options in EMAN2 have adopted the standard Unix style rather than the EMAN1 style, for example 'proc2d abc.hed def.spi clip=64,64' has become 'e2proc2d.py abc.hed def.spi --clip=64,64'. In many, but not all, cases, the option names are the same.

• While EMAN2 supports all of the file formats (and more) from EMAN1, if you wish to make sure all of the metadata is stored during processing, you must use either HDF or the BDB database.

• EMAN2 uses an embedded (no database server) database system for storing a lot of image data and metadata. This system is both extremely useful and powerful, and at times very frustrating and irritating.

• EMAN2 supports a modular system for parallel processing, and can support:
  • multi-cpu (threaded) parallelism on the local computer
  • ad-hoc, distributed processing (somewhat like seti-at-home)
  • MPI (though there are a few specific requirements)

Translation Table

Here are a few of the more common EMAN1 commands and their EMAN2 equivalents:

There are, of course, many others as well.

Everything is Modular

In EMAN1, every different filter or option had its own name. For example in proc2d, you had 'lp' for a low-pass Gaussian filter or 'tlp' for a sigmoidal filter. In refine, you would pick between 'phasecls', 'fscls' or 'dfilt'. Every time we wanted to add a new capability, we had to code it into every program and implement new option names, etc. In addition, when using 'lp' you also had to know that the value you specified was a radius in Fourier pixels, unless you also specified apix= in which case it would be 1/half width in A. This is messy, and tends to cause mistakes.

What's the alternative, you ask. The answer, a modular system. In EMAN2, each class of algorithm, such as filters (processors), aligners, cmps (similarity metrics), etc. maintains a list of all available algorithms, and any program using one of these categories can use any algorithm from the list. Each modular operation takes a list of parameters, and the parameter names are matched whenever possible.

For example, say you had a 3-D model and you wanted to high pass-filter it, mask it with a sharp spherical mask, then low pass filter the final result. In eman1, the only safe way to do it was a series of 3 commands:

proc3d model.mrc model.mrc hp=100 apix=2
proc3d model.mrc model.mrc mask=42
proc3d model.mrc model.mrc lp=10 apix=2

In EMAN2, it can be done with a single command, and, if more verbose, the options are clear and readable.

e2proc3d.py model.mrc model.mrc --process=filter.highpass.gauss:cutoff_freq=.01 --process=mask.sharp:outer_radius=42 --process=filter.lowpass.gauss:cutoff_freq=.1

and if you wanted to use a hyperbolic tangent lowpass filter instead of a gaussian, you would simply replace 'filter.lowpass.gauss' with 'filter.lowpass.tanh'. The parameter would be exactly the same.

Of course, if the system is modular, you need some mechanism to find out what the available options are. In the GUI interface, it will present you with a menu of the available options. However, for the command line, or if you want the detailed documentation for any particular option, you use the e2help.py command. For example to list all of the processors, which includes, filters, masks, mathematical operations, etc (178 of them at last count), you would type e2help.py processors. This will give a list of 1 processor per line with parameter names. If you want more details, and a definition of each parameter, then 'e2help.py processors -v 2' will give you a more detailed listing.

Similarly, say you want to specify what similarity metric is used when comparing particles to projections during classification. You can get a list by saying e2help.py cmps. To get a list of the categories available in e2help, just type 'e2help.py' with no options and it will list the categories (at present: processors, cmps, aligners, averagers, projectors, reconstructors, analyzers, symmetries and orientgens).

This system currently embodies over 240 different algorithms for a wide range of different purposes. If you have some image processing task, chances are that e2proc2d.py or e2proc3d.py with the --process option can meet your need. In addition, there is a GUI interface e2filtertool.py which allows you to graphically create filter chains and adjust their parameters interactively. Don't know how much to low pass filter that model ? Run e2filtertool.py on it, and you can play with different filters and parameters to your heart's content.

Everything is Saved and (hopefully) Defined

While EMAN1 did preserve some of the information generated during refinement, there were some omissions that people found frustrating. In EMAN2, we try to preserve everything computed during the refinement (with a few impractical exceptions). While this can take a lot of extra disk space during processing, you are always free to delete any intermediate files you don't want and increasingly, disk space is cheap. While most users will never need to consult it, the EMAN2 Wiki contains pages documenting everything we store: metadata stored in image headers, metadata associated with a project, and information on intermediate files, conventions, etc.